@mistralys/persona-builder 2.5.0 → 2.6.0

package/dist/index.d.cts

@@ -86,7 +86,7 @@ declare function resolveConditionals(text: string, context: Record<string, unkno
  * variables.ts
  *
  * Pure template-engine function for resolving variable substitutions.
- * Handles {{varName}} syntax. No file-system I/O.
+ * Handles {{varName}} substitution and \{{varName}} escape syntax. No file-system I/O.
  */
 /**
  * Resolve variable substitutions in a template string.
@@ -96,6 +96,10 @@ declare function resolveConditionals(text: string, context: Record<string, unkno
  * the original marker is preserved and a warning is emitted via
  * `console.warn`, identifying the file by `filename` for easier debugging.
  *
+ * **Escape syntax:** prefix a marker with a backslash (`\{{varName}}`) to
+ * emit the literal `{{varName}}` text in the output without performing any
+ * lookup or triggering an unresolved-variable warning.
+ *
  * Note: this step must run AFTER `resolvePartials` and `resolveConditionals`
  * so that only plain variable markers remain.
  *
@@ -1304,6 +1308,51 @@ declare function validateStrictMarkers(renderedContent: string, requiredMarkers:
  */
 declare function escapeRegExp(str: string): string;
 
+/**
+ * src/utils/changelog.ts
+ *
+ * Utility for extracting version and date metadata from a changelog block scalar.
+ *
+ * Pure function — zero imports, no I/O, no side effects.
+ */
+/**
+ * Version and date metadata extracted from a changelog entry.
+ *
+ * `date` is an empty string when the changelog entry has no date component.
+ */
+interface ChangelogMeta {
+    /** Semver version string, e.g. `'1.5.0'` */
+    version: string;
+    /** ISO date string (`YYYY-MM-DD`), or `''` if absent */
+    date: string;
+}
+/**
+ * Extract `version` and `date` from the first matching line of a changelog
+ * block scalar.
+ *
+ * Lines are inspected in order; the first line that contains a recognisable
+ * semver entry wins. This ensures that a later entry with a date does not
+ * shadow an earlier entry that has no date.
+ *
+ * Accepts `unknown` input so callers can pass raw YAML values without casting.
+ * Returns `undefined` when the input is not a non-empty string or contains no
+ * recognisable version line.
+ *
+ * @param input  Raw changelog value (typically a YAML block scalar string)
+ * @returns      Extracted `{ version, date }`, or `undefined`
+ *
+ * @example
+ * resolveChangelogMeta('1.5.0 (2026-06-13): Added feature')
+ * // => { version: '1.5.0', date: '2026-06-13' }
+ *
+ * resolveChangelogMeta('1.5.0: Added feature')
+ * // => { version: '1.5.0', date: '' }
+ *
+ * resolveChangelogMeta(undefined)
+ * // => undefined
+ */
+declare function resolveChangelogMeta(input: unknown): ChangelogMeta | undefined;
+
 /**
  * src/targets/built-in.ts
  *
@@ -1336,4 +1385,4 @@ declare const defaultRegistry: TargetRegistry;
 
 declare const VERSION: string;
 
-export { type BuildConfig, type BuildResult, type BuildSummary, DEFAULT_FRONTMATTER_CLAUDE_CODE, DEFAULT_FRONTMATTER_DEEP_AGENTS, DEFAULT_FRONTMATTER_VSCODE, type PersonaBuildPlugin, type PersonaMetadata, type SuiteConfig, TARGET_CLAUDE_CODE, TARGET_DEEP_AGENTS, TARGET_VSCODE, type TargetDefinition, TargetRegistry, type TargetType, VERSION, type ValidationResult, build, buildPersona, buildSuite, collapseBlankLines, defaultRegistry, discoverPersonaYamls, ensureBlankLineBeforeHeadings, escapeRegExp, loadContent, loadMetadata, loadPartials, normalizeNewlines, renderFrontmatter, resolveConditionals, resolveFrontmatterTemplate, resolvePartials, resolveVariables, runBuildContext, runPartials, runPersonaPartials, runPostRender, runSuiteInit, runValidate, serializeTools, serializeToolsBlock, serializeToolsList, validateFileName, validateStrictMarkers };
+export { type BuildConfig, type BuildResult, type BuildSummary, type ChangelogMeta, DEFAULT_FRONTMATTER_CLAUDE_CODE, DEFAULT_FRONTMATTER_DEEP_AGENTS, DEFAULT_FRONTMATTER_VSCODE, type PersonaBuildPlugin, type PersonaMetadata, type SuiteConfig, TARGET_CLAUDE_CODE, TARGET_DEEP_AGENTS, TARGET_VSCODE, type TargetDefinition, TargetRegistry, type TargetType, VERSION, type ValidationResult, build, buildPersona, buildSuite, collapseBlankLines, defaultRegistry, discoverPersonaYamls, ensureBlankLineBeforeHeadings, escapeRegExp, loadContent, loadMetadata, loadPartials, normalizeNewlines, renderFrontmatter, resolveChangelogMeta, resolveConditionals, resolveFrontmatterTemplate, resolvePartials, resolveVariables, runBuildContext, runPartials, runPersonaPartials, runPostRender, runSuiteInit, runValidate, serializeTools, serializeToolsBlock, serializeToolsList, validateFileName, validateStrictMarkers };

package/dist/index.d.ts

@@ -86,7 +86,7 @@ declare function resolveConditionals(text: string, context: Record<string, unkno
  * variables.ts
  *
  * Pure template-engine function for resolving variable substitutions.
- * Handles {{varName}} syntax. No file-system I/O.
+ * Handles {{varName}} substitution and \{{varName}} escape syntax. No file-system I/O.
  */
 /**
  * Resolve variable substitutions in a template string.
@@ -96,6 +96,10 @@ declare function resolveConditionals(text: string, context: Record<string, unkno
  * the original marker is preserved and a warning is emitted via
  * `console.warn`, identifying the file by `filename` for easier debugging.
  *
+ * **Escape syntax:** prefix a marker with a backslash (`\{{varName}}`) to
+ * emit the literal `{{varName}}` text in the output without performing any
+ * lookup or triggering an unresolved-variable warning.
+ *
  * Note: this step must run AFTER `resolvePartials` and `resolveConditionals`
  * so that only plain variable markers remain.
  *
@@ -1304,6 +1308,51 @@ declare function validateStrictMarkers(renderedContent: string, requiredMarkers:
  */
 declare function escapeRegExp(str: string): string;
 
+/**
+ * src/utils/changelog.ts
+ *
+ * Utility for extracting version and date metadata from a changelog block scalar.
+ *
+ * Pure function — zero imports, no I/O, no side effects.
+ */
+/**
+ * Version and date metadata extracted from a changelog entry.
+ *
+ * `date` is an empty string when the changelog entry has no date component.
+ */
+interface ChangelogMeta {
+    /** Semver version string, e.g. `'1.5.0'` */
+    version: string;
+    /** ISO date string (`YYYY-MM-DD`), or `''` if absent */
+    date: string;
+}
+/**
+ * Extract `version` and `date` from the first matching line of a changelog
+ * block scalar.
+ *
+ * Lines are inspected in order; the first line that contains a recognisable
+ * semver entry wins. This ensures that a later entry with a date does not
+ * shadow an earlier entry that has no date.
+ *
+ * Accepts `unknown` input so callers can pass raw YAML values without casting.
+ * Returns `undefined` when the input is not a non-empty string or contains no
+ * recognisable version line.
+ *
+ * @param input  Raw changelog value (typically a YAML block scalar string)
+ * @returns      Extracted `{ version, date }`, or `undefined`
+ *
+ * @example
+ * resolveChangelogMeta('1.5.0 (2026-06-13): Added feature')
+ * // => { version: '1.5.0', date: '2026-06-13' }
+ *
+ * resolveChangelogMeta('1.5.0: Added feature')
+ * // => { version: '1.5.0', date: '' }
+ *
+ * resolveChangelogMeta(undefined)
+ * // => undefined
+ */
+declare function resolveChangelogMeta(input: unknown): ChangelogMeta | undefined;
+
 /**
  * src/targets/built-in.ts
  *
@@ -1336,4 +1385,4 @@ declare const defaultRegistry: TargetRegistry;
 
 declare const VERSION: string;
 
-export { type BuildConfig, type BuildResult, type BuildSummary, DEFAULT_FRONTMATTER_CLAUDE_CODE, DEFAULT_FRONTMATTER_DEEP_AGENTS, DEFAULT_FRONTMATTER_VSCODE, type PersonaBuildPlugin, type PersonaMetadata, type SuiteConfig, TARGET_CLAUDE_CODE, TARGET_DEEP_AGENTS, TARGET_VSCODE, type TargetDefinition, TargetRegistry, type TargetType, VERSION, type ValidationResult, build, buildPersona, buildSuite, collapseBlankLines, defaultRegistry, discoverPersonaYamls, ensureBlankLineBeforeHeadings, escapeRegExp, loadContent, loadMetadata, loadPartials, normalizeNewlines, renderFrontmatter, resolveConditionals, resolveFrontmatterTemplate, resolvePartials, resolveVariables, runBuildContext, runPartials, runPersonaPartials, runPostRender, runSuiteInit, runValidate, serializeTools, serializeToolsBlock, serializeToolsList, validateFileName, validateStrictMarkers };
+export { type BuildConfig, type BuildResult, type BuildSummary, type ChangelogMeta, DEFAULT_FRONTMATTER_CLAUDE_CODE, DEFAULT_FRONTMATTER_DEEP_AGENTS, DEFAULT_FRONTMATTER_VSCODE, type PersonaBuildPlugin, type PersonaMetadata, type SuiteConfig, TARGET_CLAUDE_CODE, TARGET_DEEP_AGENTS, TARGET_VSCODE, type TargetDefinition, TargetRegistry, type TargetType, VERSION, type ValidationResult, build, buildPersona, buildSuite, collapseBlankLines, defaultRegistry, discoverPersonaYamls, ensureBlankLineBeforeHeadings, escapeRegExp, loadContent, loadMetadata, loadPartials, normalizeNewlines, renderFrontmatter, resolveChangelogMeta, resolveConditionals, resolveFrontmatterTemplate, resolvePartials, resolveVariables, runBuildContext, runPartials, runPersonaPartials, runPostRender, runSuiteInit, runValidate, serializeTools, serializeToolsBlock, serializeToolsList, validateFileName, validateStrictMarkers };

package/dist/index.js

@@ -65,7 +65,10 @@ function resolveConditionals(text, context) {
 
 // src/engine/variables.ts
 function resolveVariables(text, context, filename) {
-  return text.replace(/\{\{(\w+)\}\}/g, (match, varName) => {
+  return text.replace(/(\\?)\{\{(\w+)\}\}/g, (match, escape, varName) => {
+    if (escape === "\\") {
+      return `{{${varName}}}`;
+    }
     if (varName in context && context[varName] !== void 0) {
       return String(context[varName]);
     }
@@ -240,6 +243,26 @@ function renderFrontmatter(template, context, filename) {
   return rendered;
 }
 
+// src/utils/changelog.ts
+var RE_VERSION_WITH_DATE = /^(\d+\.\d+\.\d+)\s*\((\d{4}-\d{2}-\d{2})\)\s*:/;
+var RE_VERSION_ONLY = /^(\d+\.\d+\.\d+)\s*:/;
+function resolveChangelogMeta(input) {
+  if (typeof input !== "string" || input.trim() === "") {
+    return void 0;
+  }
+  for (const line of input.split(/\r?\n/)) {
+    const withDate = RE_VERSION_WITH_DATE.exec(line);
+    if (withDate !== null) {
+      return { version: withDate[1], date: withDate[2] };
+    }
+    const versionOnly = RE_VERSION_ONLY.exec(line);
+    if (versionOnly !== null) {
+      return { version: versionOnly[1], date: "" };
+    }
+  }
+  return void 0;
+}
+
 // src/targets/registry.ts
 var TargetRegistry = class _TargetRegistry {
   // Map preserves insertion order — names() and allDefinitions() are
@@ -397,7 +420,8 @@ async function buildAgentNameMap(config) {
       const persona = await loadPersonaYaml(yamlPath);
       const slug = typeof persona["slug"] === "string" ? persona["slug"] : path4.basename(yamlPath, ".yaml");
       const name = typeof persona["name"] === "string" ? persona["name"] : slug;
-      const version = typeof persona["version"] === "string" ? persona["version"] : defaultVersion;
+      const clMeta = resolveChangelogMeta(persona["changelog"]);
+      const version = clMeta?.version ?? defaultVersion;
       const underscoredSlug = slug.replace(/-/g, "_");
       const key = `agent_${underscoredSlug}`;
       agentMap[key] = `${name} v${version}`;
@@ -417,7 +441,8 @@ function buildContext(options) {
     configVariables,
     suiteVariables
   } = options;
-  const version = typeof personaMeta["version"] === "string" ? personaMeta["version"] : typeof sharedMeta["default_version"] === "string" ? sharedMeta["default_version"] : "0.0.0";
+  const clMeta = resolveChangelogMeta(personaMeta["changelog"]);
+  const version = clMeta?.version ?? (typeof sharedMeta["default_version"] === "string" ? sharedMeta["default_version"] : "0.0.0");
   const merged = {
     ...configVariables ?? {},
     ...suiteVariables ?? {},
@@ -425,6 +450,9 @@ function buildContext(options) {
     ...personaMeta,
     version
   };
+  if (!("last_updated" in merged)) {
+    merged["last_updated"] = clMeta?.date ?? "";
+  }
   const tools = Array.isArray(merged["tools"]) ? merged["tools"] : [];
   if (!("tools_list" in merged)) {
     merged["tools_list"] = serializeToolsList(tools);
@@ -691,6 +719,6 @@ function escapeRegExp(str) {
 var _pkgRequire = createRequire(import.meta.url);
 var VERSION = _pkgRequire("../package.json").version;
 
-export { DEFAULT_FRONTMATTER_CLAUDE_CODE, DEFAULT_FRONTMATTER_DEEP_AGENTS, DEFAULT_FRONTMATTER_VSCODE, TARGET_CLAUDE_CODE, TARGET_DEEP_AGENTS, TARGET_VSCODE, TargetRegistry, VERSION, build, buildPersona, buildSuite, collapseBlankLines, defaultRegistry, discoverPersonaYamls, ensureBlankLineBeforeHeadings, escapeRegExp, loadContent, loadMetadata, loadPartials, normalizeNewlines, renderFrontmatter, resolveConditionals, resolveFrontmatterTemplate, resolvePartials, resolveVariables, runBuildContext, runPartials, runPersonaPartials, runPostRender, runSuiteInit, runValidate, serializeTools, serializeToolsBlock, serializeToolsList, validateFileName, validateStrictMarkers };
+export { DEFAULT_FRONTMATTER_CLAUDE_CODE, DEFAULT_FRONTMATTER_DEEP_AGENTS, DEFAULT_FRONTMATTER_VSCODE, TARGET_CLAUDE_CODE, TARGET_DEEP_AGENTS, TARGET_VSCODE, TargetRegistry, VERSION, build, buildPersona, buildSuite, collapseBlankLines, defaultRegistry, discoverPersonaYamls, ensureBlankLineBeforeHeadings, escapeRegExp, loadContent, loadMetadata, loadPartials, normalizeNewlines, renderFrontmatter, resolveChangelogMeta, resolveConditionals, resolveFrontmatterTemplate, resolvePartials, resolveVariables, runBuildContext, runPartials, runPersonaPartials, runPostRender, runSuiteInit, runValidate, serializeTools, serializeToolsBlock, serializeToolsList, validateFileName, validateStrictMarkers };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map