@mistralys/persona-builder 2.1.3 → 2.3.0

package/README.md

@@ -1,12 +1,13 @@
 # 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.
 
 ## ✨ Features
 
-- **Dual-target output** — generates both `.agent.md` (VS Code) and `.md` (Claude Code) from a single source
+- **Multi-target output** — generates VS Code `.agent.md`, Claude Code `.md`, Deep Agents `.md`, and any custom format from a single source
+- **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
 - **Plugin architecture** — hook into context building, post-rendering, validation, and frontmatter generation
@@ -24,6 +25,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
@@ -34,8 +38,10 @@ const summary = await build({
   suites: {
     'my-suite': {
       srcDir: path.resolve('./personas/my-suite'),
-      outVscode: path.resolve('./dist/vscode'),
-      outClaudeCode: path.resolve('./dist/claude-code'),
+      outputDirs: {
+        vscode: path.resolve('./dist/vscode'),
+        'claude-code': path.resolve('./dist/claude-code'),
+      },
     },
   },
   sharedPartialsDir: path.resolve('./personas/shared/partials'),
@@ -75,6 +81,7 @@ See the [CLI docs](docs/cli.md) for config file format and all flags.
 | [Configuration Reference](docs/configuration.md) | `BuildConfig`, `SuiteConfig`, and `BuildSummary` fields |
 | [CLI Reference](docs/cli.md) | Command-line flags, config file format, and common patterns |
 | [Public API](docs/api.md) | All exported types and functions |
+| [Project Manifest](docs/agents/project-manifest/README.md) | Canonical documentation for AI agent sessions |
 
 ## 🔌 Plugins
 
@@ -96,7 +103,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,19 +27,48 @@ 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) {
-  return text.replace(
-    /\n*\{\{#if (\w+)\}\}([\s\S]*?)(?:\{\{else\}\}([\s\S]*?))?\{\{\/if\}\}\n*/g,
-    (_match, flag, inner, elseInner) => {
-      if (context[flag]) {
-        return "\n" + inner.replace(/^\n+/, "").replace(/\n+$/, "") + "\n";
-      }
-      if (elseInner !== void 0) {
-        return "\n" + elseInner.replace(/^\n+/, "").replace(/\n+$/, "") + "\n";
-      }
-      return "\n";
-    }
+  const normalized = resolveElseIf(text);
+  const pattern = new RegExp(
+    String.raw`\n*\{\{#if (\w+)\}\}(${NO_NESTED_IF})` + String.raw`(?:\{\{else\}\}(${NO_NESTED_IF}))?\{\{\/if\}\}\n*`,
+    "g"
   );
+  const resolve = (_match, flag, inner, elseInner) => {
+    if (context[flag]) {
+      return "\n" + inner.replace(/^\n+/, "").replace(/\n+$/, "") + "\n";
+    }
+    if (elseInner !== void 0) {
+      return "\n" + elseInner.replace(/^\n+/, "").replace(/\n+$/, "") + "\n";
+    }
+    return "\n";
+  };
+  let result = normalized;
+  let prev;
+  do {
+    prev = result;
+    result = result.replace(pattern, resolve);
+  } while (result !== prev);
+  return result;
 }
 
 // src/engine/variables.ts
@@ -98,11 +127,11 @@ function runSuiteInit(plugins, suite, sharedMeta) {
     }
   }
 }
-function runBuildContext(plugins, ctx, persona, suite) {
+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);
+      accumulated = plugin.onBuildContext(accumulated, persona, suite, target);
     }
   }
   return accumulated;
@@ -127,7 +156,10 @@ function runValidate(plugins, persona, suite, target) {
   return results;
 }
 
-// src/builders/frontmatter.ts
+// src/targets/types.ts
+var TARGET_VSCODE = "vscode";
+var TARGET_CLAUDE_CODE = "claude-code";
+var TARGET_DEEP_AGENTS = "deep-agents";
 var DEFAULT_FRONTMATTER_VSCODE = `---
 name: '{{name}} v{{version}}'
 description: '{{description}}'
@@ -140,7 +172,13 @@ model: {{cc_model}}
 memory: {{cc_memory}}
 allowedTools: [{{cc_tools_list}}]
 ---`;
-function resolveFrontmatterTemplate(target, plugins, configTemplates) {
+var DEFAULT_FRONTMATTER_DEEP_AGENTS = `---
+name: {{name}}
+description: {{description}}
+---`;
+
+// src/builders/frontmatter.ts
+function resolveFrontmatterTemplate(target, plugins, configTemplates, registry) {
   for (const plugin of plugins) {
     if (plugin.frontmatterTemplates && target in plugin.frontmatterTemplates) {
       const tpl = plugin.frontmatterTemplates[target];
@@ -151,7 +189,10 @@ function resolveFrontmatterTemplate(target, plugins, configTemplates) {
     const tpl = configTemplates[target];
     if (tpl !== void 0) return tpl;
   }
-  return target === "vscode" ? DEFAULT_FRONTMATTER_VSCODE : DEFAULT_FRONTMATTER_CLAUDE_CODE;
+  if (registry && registry.has(target)) {
+    return registry.get(target).defaultFrontmatter;
+  }
+  return DEFAULT_FRONTMATTER_VSCODE;
 }
 function renderFrontmatter(template, context, filename) {
   let rendered = resolveConditionals(template, context);
@@ -159,6 +200,112 @@ function renderFrontmatter(template, context, filename) {
   return rendered;
 }
 
+// src/targets/registry.ts
+var TargetRegistry = class _TargetRegistry {
+  // Map preserves insertion order — names() and allDefinitions() are
+  // therefore deterministic and match registration sequence. This is
+  // intentional: the built-in registry guarantees ['vscode', 'claude-code']
+  // ordering for the default targets (AC-2).
+  _definitions = /* @__PURE__ */ new Map();
+  /**
+   * Register a new target definition.
+   *
+   * @param definition  The target descriptor to register.
+   * @throws {Error}    If a target with the same `name` is already registered.
+   */
+  register(definition) {
+    if (this._definitions.has(definition.name)) {
+      throw new Error(
+        `TargetRegistry: target "${definition.name}" is already registered. Use a unique name or remove the existing registration first.`
+      );
+    }
+    this._definitions.set(definition.name, definition);
+  }
+  /**
+   * Retrieve a registered target definition by name.
+   *
+   * Returns a shallow copy — mutating the returned object does not affect
+   * the registry's internal state.
+   *
+   * @param name      The target name to look up.
+   * @returns         A shallow copy of the matching TargetDefinition.
+   * @throws {Error}  If no target with the given name is registered.
+   */
+  get(name) {
+    const def = this._definitions.get(name);
+    if (!def) {
+      const known = this.names().join(", ") || "(none)";
+      throw new Error(
+        `TargetRegistry: target "${name}" is not registered. Registered targets: ${known}.`
+      );
+    }
+    return { ...def };
+  }
+  /**
+   * Returns `true` if a target with the given name is registered.
+   *
+   * @param name  The target name to check.
+   */
+  has(name) {
+    return this._definitions.has(name);
+  }
+  /**
+   * Returns the names of all registered targets, in registration order.
+   */
+  names() {
+    return Array.from(this._definitions.keys());
+  }
+  /**
+   * Returns all registered TargetDefinition objects, in registration order.
+   *
+   * Returns shallow copies — mutating a returned definition does not affect
+   * the registry's internal state.
+   */
+  allDefinitions() {
+    return Array.from(this._definitions.values()).map((def) => ({ ...def }));
+  }
+  /**
+   * Returns a new TargetRegistry pre-populated with the same definitions.
+   *
+   * Useful for test isolation: clone the `defaultRegistry` to get an
+   * independent copy that can be mutated without affecting the singleton.
+   */
+  clone() {
+    const copy = new _TargetRegistry();
+    for (const def of this._definitions.values()) {
+      copy.register({ ...def });
+    }
+    return copy;
+  }
+};
+
+// src/targets/built-in.ts
+var defaultRegistry = new TargetRegistry();
+defaultRegistry.register({
+  name: TARGET_VSCODE,
+  outputDirKey: "vscode",
+  filenameContextKey: "vs_file_name",
+  defaultFrontmatter: DEFAULT_FRONTMATTER_VSCODE,
+  contextFlags: { target_vscode: true },
+  defaultEnabled: true
+});
+defaultRegistry.register({
+  name: TARGET_CLAUDE_CODE,
+  outputDirKey: "claude-code",
+  filenameContextKey: "cc_file_name",
+  defaultFrontmatter: DEFAULT_FRONTMATTER_CLAUDE_CODE,
+  contextFlags: { target_claude_code: true },
+  defaultEnabled: true
+});
+defaultRegistry.register({
+  name: TARGET_DEEP_AGENTS,
+  outputDirKey: "deep-agents",
+  filenameContextKey: "da_file_name",
+  defaultFrontmatter: DEFAULT_FRONTMATTER_DEEP_AGENTS,
+  contextFlags: { target_deep_agents: true },
+  defaultEnabled: false
+});
+
 // src/builders/persona-builder.ts
 async function discoverSuitePersonaYamls(suiteConfig) {
   const metaSubdir = suiteConfig.metaSubdir ?? "meta";
@@ -186,6 +333,18 @@ async function loadPersonaYaml(yamlPath) {
   }
   return record;
 }
+function resolveOutputDir(target, suiteConfig, definition) {
+  const merged = {};
+  if (suiteConfig.outVscode) merged["vscode"] = suiteConfig.outVscode;
+  if (suiteConfig.outClaudeCode) merged["claude-code"] = suiteConfig.outClaudeCode;
+  if (suiteConfig.outputDirs) Object.assign(merged, suiteConfig.outputDirs);
+  const lookupKey = definition?.outputDirKey ?? target;
+  const dir = merged[lookupKey];
+  if (dir) return dir;
+  throw new Error(
+    `buildPersona: no output directory configured for target "${target}". Add outputDirs['${lookupKey}'] to the suite config, or, for the built-in targets, provide the outVscode / outClaudeCode fields.`
+  );
+}
 async function buildAgentNameMap(config) {
   const agentMap = {};
   for (const [, suiteConfig] of Object.entries(config.suites)) {
@@ -199,13 +358,16 @@ async function buildAgentNameMap(config) {
       const slug = typeof persona["slug"] === "string" ? persona["slug"] : path2__default.default.basename(yamlPath, ".yaml");
       const name = typeof persona["name"] === "string" ? persona["name"] : slug;
       const version = typeof persona["version"] === "string" ? persona["version"] : defaultVersion;
-      const key = `agent_${slug.replace(/-/g, "_")}`;
+      const underscoredSlug = slug.replace(/-/g, "_");
+      const key = `agent_${underscoredSlug}`;
       agentMap[key] = `${name} v${version}`;
+      const slugKey = `agent_slug_${underscoredSlug}`;
+      agentMap[slugKey] = slug;
     }
   }
   return agentMap;
 }
-function buildContext(personaMeta, sharedMeta, agentMap = {}) {
+function buildContext(personaMeta, sharedMeta, agentMap = {}, target, registry) {
   const version = typeof personaMeta["version"] === "string" ? personaMeta["version"] : typeof sharedMeta["default_version"] === "string" ? sharedMeta["default_version"] : "0.0.0";
   const merged = {
     ...sharedMeta,
@@ -230,19 +392,42 @@ function buildContext(personaMeta, sharedMeta, agentMap = {}) {
     const ccFileName = merged["cc_file_name"];
     merged["cc_file_name_stem"] = ccFileName.replace(/\.md$/, "");
   }
+  if (!("da_file_name_stem" in merged) && typeof merged["da_file_name"] === "string") {
+    const daFileName = merged["da_file_name"];
+    merged["da_file_name_stem"] = daFileName.replace(/\.md$/, "");
+  }
+  if (typeof merged["da_file_name"] === "string") {
+    const daTools = Array.isArray(merged["da_tools"]) ? merged["da_tools"] : tools;
+    if (!("da_tools_list" in merged)) {
+      merged["da_tools_list"] = serializeToolsList(daTools);
+    }
+    if (!("da_tools_json" in merged)) {
+      merged["da_tools_json"] = serializeTools(daTools);
+    }
+  }
   for (const [key, value] of Object.entries(agentMap)) {
     if (!(key in merged)) {
       merged[key] = value;
     }
   }
+  if (target !== void 0) {
+    if (registry && registry.has(target)) {
+      const flags = registry.get(target).contextFlags ?? {};
+      for (const [key, value] of Object.entries(flags)) {
+        merged[key] = value;
+      }
+    } else {
+      merged[`target_${target.replace(/-/g, "_")}`] = true;
+    }
+  }
   return merged;
 }
-async function buildPersona(personaYamlPath, suiteName, suiteConfig, sharedMeta, partialsMap, config, plugins, target, agentMap = {}) {
+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);
+  let context = buildContext(personaMeta, sharedMeta, agentMap, target, registry);
   const personaMetaTyped = personaMeta;
-  context = runBuildContext(plugins, context, personaMetaTyped, suiteConfig);
-  const fmTemplate = resolveFrontmatterTemplate(target, plugins, config.frontmatter);
+  context = runBuildContext(plugins, context, personaMetaTyped, 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";
@@ -260,15 +445,10 @@ ${body}
 `);
   output = runPostRender(plugins, output, personaMetaTyped, target);
   const validationResults = runValidate(plugins, personaMetaTyped, suiteConfig, target);
-  const outputDir = target === "vscode" ? suiteConfig.outVscode : suiteConfig.outClaudeCode;
-  let outputBasename;
-  if (target === "vscode" && typeof context["vs_file_name"] === "string") {
-    outputBasename = context["vs_file_name"];
-  } else if (target === "claude-code" && typeof context["cc_file_name"] === "string") {
-    outputBasename = context["cc_file_name"];
-  } else {
-    outputBasename = contentBasename;
-  }
+  const def = registry.has(target) ? registry.get(target) : void 0;
+  const outputDir = resolveOutputDir(target, suiteConfig, def);
+  const fnKey = def?.filenameContextKey;
+  const outputBasename = fnKey && typeof context[fnKey] === "string" ? context[fnKey] : contentBasename;
   const outputPath = path2__default.default.join(outputDir, outputBasename);
   const check = config.check ?? false;
   let written = false;
@@ -287,7 +467,7 @@ ${body}
     written
   };
 }
-async function buildSuite(suiteName, suiteConfig, config, plugins, target, agentMap = {}) {
+async function buildSuite(suiteName, suiteConfig, config, plugins, target, agentMap = {}, registry = defaultRegistry) {
   const metaSubdir = suiteConfig.metaSubdir ?? "meta";
   const sharedYamlPath = path2__default.default.join(suiteConfig.srcDir, metaSubdir, "_shared.yaml");
   const sharedMeta = await loadRawYaml(sharedYamlPath);
@@ -313,7 +493,8 @@ async function buildSuite(suiteName, suiteConfig, config, plugins, target, agent
       config,
       plugins,
       target,
-      agentMap
+      agentMap,
+      registry
     );
     results.push(result);
   }
@@ -321,12 +502,13 @@ async function buildSuite(suiteName, suiteConfig, config, plugins, target, agent
 }
 async function build(config) {
   const plugins = config.plugins ?? [];
-  const targets = config.targets ?? ["vscode", "claude-code"];
+  const registry = config.targetRegistry ?? defaultRegistry;
+  const targets = config.targets ?? registry.names().filter((n) => registry.get(n).defaultEnabled !== false);
   const allResults = [];
   const agentMap = await buildAgentNameMap(config);
   for (const [suiteName, suiteConfig] of Object.entries(config.suites)) {
     for (const target of targets) {
-      const suiteResults = await buildSuite(suiteName, suiteConfig, config, plugins, target, agentMap);
+      const suiteResults = await buildSuite(suiteName, suiteConfig, config, plugins, target, agentMap, registry);
       allResults.push(...suiteResults);
     }
   }