@mistralys/persona-builder 2.1.2 → 2.2.0

package/dist/index.d.cts

@@ -31,7 +31,8 @@ declare function resolvePartials(text: string, partialsMap: Record<string, strin
  * conditionals.ts
  *
  * Pure template-engine function for resolving conditional blocks.
- * Handles {{#if flag}}…{{/if}} and {{#if flag}}…{{else}}…{{/if}} syntax.
+ * Handles {{#if flag}}…{{/if}} and {{#if flag}}…{{else}}…{{/if}} syntax,
+ * including nested {{#if}} blocks inside {{else}} branches.
  * No file-system I/O.
  */
 /**
@@ -41,6 +42,9 @@ declare function resolvePartials(text: string, partialsMap: Record<string, strin
  *   `{{#if flag}}content{{/if}}`
  *   `{{#if flag}}truthy-content{{else}}falsy-content{{/if}}`
  *
+ * Nested conditionals inside `{{else}}` branches are supported:
+ *   `{{#if a}}A{{else}}{{#if b}}B{{else}}C{{/if}}{{/if}}`
+ *
  * Behaviour:
  * - When `context[flag]` is truthy: the delimiters are stripped and the
  *   content before `{{else}}` (or the entire inner block if no `{{else}}`)
@@ -55,6 +59,12 @@ declare function resolvePartials(text: string, partialsMap: Record<string, strin
  * Leading and trailing newlines within the kept content are trimmed so the
  * output does not accumulate extra blank lines.
  *
+ * Nesting algorithm: the regex matches only *innermost* blocks — those
+ * whose content contains no further `{{#if` markers. The replacement loop
+ * repeats until the output stabilises, resolving each nesting level in
+ * depth-first (innermost-first) order. This avoids the closing `{{/if}}`
+ * ambiguity that arises with non-greedy single-pass matching.
+ *
  * @param text    - Template string potentially containing {{#if}} blocks
  * @param context - Key-value map used to evaluate flag truthiness
  * @returns       The template string with conditional blocks resolved
@@ -204,11 +214,19 @@ declare function loadPartials(dir: string): Promise<Record<string, string>>;
  *   - PersonaBuildPlugin — interface every plugin must implement
  */
 /**
- * The two output formats supported by the build pipeline.
- * 'vscode'      → VS Code `.code-workspace` instruction files
- * 'claude-code' → Claude Code instruction files
+ * Identifies a build output target.
+ *
+ * Resolves to `string` to allow custom targets alongside the three built-in
+ * well-known values:
+ *   - `'vscode'`       → VS Code `.prompt.md` / `.agent.md` instruction files
+ *   - `'claude-code'`  → Claude Code `.md` instruction files
+ *   - `'deep-agents'`  → Deep Agents `.md` instruction files
+ *
+ * Use the exported constants `TARGET_VSCODE`, `TARGET_CLAUDE_CODE`, and
+ * `TARGET_DEEP_AGENTS` from `src/targets/types.ts` for type-safe references
+ * to the built-in targets.
  */
-type TargetType = 'vscode' | 'claude-code';
+type TargetType = string;
 /**
  * Typed representation of a persona YAML metadata file.
  *
@@ -236,10 +254,50 @@ interface PersonaMetadata {
 interface SuiteConfig {
     /** Absolute or relative path to the suite source directory */
     srcDir: string;
-    /** Output path for VS Code formatted persona files */
-    outVscode: string;
-    /** Output path for Claude Code formatted persona files */
-    outClaudeCode: string;
+    /**
+     * Output path for VS Code formatted persona files.
+     *
+     * @deprecated Use `outputDirs['vscode']` instead. Kept for backwards
+     *   compatibility. When `outputDirs['vscode']` is present it takes
+     *   precedence. Will be removed in a future major version.
+     */
+    outVscode?: string;
+    /**
+     * Output path for Claude Code formatted persona files.
+     *
+     * @deprecated Use `outputDirs['claude-code']` instead. Kept for backwards
+     *   compatibility. When `outputDirs['claude-code']` is present it takes
+     *   precedence. Will be removed in a future major version.
+     */
+    outClaudeCode?: string;
+    /**
+     * Generic map of output directories keyed by target output-dir key.
+     *
+     * Takes precedence over the deprecated `outVscode` / `outClaudeCode` fields.
+     * Required for custom targets beyond the built-in ones. Each key must match
+     * the target's `outputDirKey` field (declared in its `TargetDefinition`),
+     * **not** necessarily the target name.
+     *
+     * For the three built-in targets `outputDirKey` equals the target name, so
+     * there is no difference in practice:
+     *   - `'vscode'` → `TargetDefinition.outputDirKey === 'vscode'`
+     *   - `'claude-code'` → `TargetDefinition.outputDirKey === 'claude-code'`
+     *   - `'deep-agents'` → `TargetDefinition.outputDirKey === 'deep-agents'`
+     *
+     * For a custom target where `name: 'my-target'` and
+     * `outputDirKey: 'mydir'`, the map key must be `'mydir'`:
+     *
+     * @example
+     * ```ts
+     * outputDirs: {
+     *   'vscode':      './out/vs-code',
+     *   'claude-code': './out/claude-code',
+     *   'deep-agents': './out/deep-agents',
+     *   'mydir':       './out/my-target',  // outputDirKey for a custom target
+     * }
+     * ```
+     */
+    outputDirs?: Record<string, string>;
     /**
      * Optional persona mode string (e.g. 'ledger').
      * When present, plugins can use this to branch behaviour.
@@ -301,7 +359,7 @@ interface PersonaBuildPlugin {
      * @param suite    The suite configuration object
      * @returns        Updated rendering context (must include all original keys)
      */
-    onBuildContext?(context: Record<string, unknown>, persona: PersonaMetadata, suite: SuiteConfig): Record<string, unknown>;
+    onBuildContext?(context: Record<string, unknown>, persona: PersonaMetadata, suite: SuiteConfig, target?: TargetType): Record<string, unknown>;
     /**
      * Called for each persona after body rendering.
      *
@@ -464,9 +522,10 @@ declare function runSuiteInit(plugins: PersonaBuildPlugin[], suite: SuiteConfig,
  * @param ctx     Initial rendering context for this persona
  * @param persona Typed metadata for the persona being built
  * @param suite   The suite configuration object
+ * @param target  The current build target (optional — forwarded to each plugin)
  * @returns       Accumulated rendering context after all plugins have run
  */
-declare function runBuildContext(plugins: PersonaBuildPlugin[], ctx: Record<string, unknown>, persona: PersonaMetadata, suite: SuiteConfig): Record<string, unknown>;
+declare function runBuildContext(plugins: PersonaBuildPlugin[], ctx: Record<string, unknown>, persona: PersonaMetadata, suite: SuiteConfig, target?: TargetType): Record<string, unknown>;
 /**
  * Invoke the `onPostRender` hook on every registered plugin, chaining the
  * output string sequentially.
@@ -497,6 +556,156 @@ declare function runPostRender(plugins: PersonaBuildPlugin[], rendered: string,
  */
 declare function runValidate(plugins: PersonaBuildPlugin[], persona: PersonaMetadata, suite: SuiteConfig, target?: TargetType): ValidationResult[];
 
+/**
+ * src/targets/types.ts
+ *
+ * Target type definitions for @mistralys/persona-builder.
+ *
+ * Defines the TargetDefinition interface and well-known target name constants.
+ */
+/**
+ * Describes a build target — maps a target name to its output directory key,
+ * filename context key, default frontmatter template, and optional
+ * auto-injected context flags.
+ */
+interface TargetDefinition {
+    /** Unique target identifier (e.g. 'vscode', 'claude-code'). */
+    name: string;
+    /**
+     * Key used to look up the output directory in the suite's output dir map.
+     * For built-in targets this matches the target name.
+     */
+    outputDirKey: string;
+    /**
+     * Context field name that holds a custom output filename for this target.
+     * When present and non-empty in the rendered context, it overrides the
+     * default filename derived from the persona name.
+     */
+    filenameContextKey?: string;
+    /**
+     * Default frontmatter template string for this target.
+     * Used when neither a plugin nor a BuildConfig template is provided.
+     */
+    defaultFrontmatter: string;
+    /**
+     * Declarative context flags merged into the build context when this target
+     * is rendered. Useful for `{{#if target_vscode}}` guards.
+     *
+     * All entries are spread into the context by `buildContext()` via a
+     * registry lookup — `registry.get(target).contextFlags`. The fallback path
+     * (for targets absent from the registry) injects a single boolean flag
+     * derived from the target name: `target_${name.replace(/-/g, '_')} = true`.
+     */
+    contextFlags?: Record<string, unknown>;
+    /**
+     * Whether this target is included in the default build when no explicit
+     * `targets` array is configured. Defaults to `true` when omitted.
+     *
+     * Set to `false` for opt-in targets (e.g. `'deep-agents'`) that should
+     * only be built when explicitly requested via `config.targets`.
+     */
+    defaultEnabled?: boolean;
+}
+/** Well-known name constant for the VS Code target. */
+declare const TARGET_VSCODE: "vscode";
+/** Well-known name constant for the Claude Code target. */
+declare const TARGET_CLAUDE_CODE: "claude-code";
+/** Well-known name constant for the Deep Agents target. */
+declare const TARGET_DEEP_AGENTS: "deep-agents";
+/**
+ * Default VS Code frontmatter template.
+ *
+ * Minimal fields that work for standalone personas. Projects using numbered
+ * workflows (e.g. ledger) should inject a richer template via a plugin.
+ */
+declare const DEFAULT_FRONTMATTER_VSCODE = "---\nname: '{{name}} v{{version}}'\ndescription: '{{description}}'\ntools: [{{tools_list}}]\n---";
+/**
+ * Default Claude Code frontmatter template.
+ *
+ * Minimal fields that work for standalone personas. Projects using numbered
+ * workflows should inject a richer template via a plugin.
+ */
+declare const DEFAULT_FRONTMATTER_CLAUDE_CODE = "---\nname: {{cc_file_name_stem}}\npermissionMode: {{cc_permission_mode}}\nmodel: {{cc_model}}\nmemory: {{cc_memory}}\nallowedTools: [{{cc_tools_list}}]\n---";
+/**
+ * Default Deep Agents frontmatter template.
+ *
+ * Minimal fields — no IDE-specific properties. Suitable for headless
+ * LangGraph / Deep Agents pipeline executors that consume persona files
+ * without an IDE host.
+ */
+declare const DEFAULT_FRONTMATTER_DEEP_AGENTS = "---\nname: {{name}}\ndescription: {{description}}\n---";
+
+/**
+ * src/targets/registry.ts
+ *
+ * TargetRegistry — holds TargetDefinition entries and allows consumers to
+ * register custom build targets alongside (or instead of) the built-in ones.
+ */
+
+/**
+ * Registry that maps target names to their TargetDefinition objects.
+ *
+ * Consumers can extend the default build system by calling `register()` with
+ * a custom TargetDefinition before invoking `build()`.
+ *
+ * @example
+ * ```ts
+ * import { defaultRegistry } from '@mistralys/persona-builder';
+ *
+ * defaultRegistry.register({
+ *   name: 'my-target',
+ *   outputDirKey: 'my-target',
+ *   defaultFrontmatter: '---\nmy: frontmatter\n---',
+ *   contextFlags: { target_my_target: true },
+ * });
+ * ```
+ */
+declare class TargetRegistry {
+    private readonly _definitions;
+    /**
+     * 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: TargetDefinition): void;
+    /**
+     * 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: string): TargetDefinition;
+    /**
+     * Returns `true` if a target with the given name is registered.
+     *
+     * @param name  The target name to check.
+     */
+    has(name: string): boolean;
+    /**
+     * Returns the names of all registered targets, in registration order.
+     */
+    names(): string[];
+    /**
+     * Returns all registered TargetDefinition objects, in registration order.
+     *
+     * Returns shallow copies — mutating a returned definition does not affect
+     * the registry's internal state.
+     */
+    allDefinitions(): TargetDefinition[];
+    /**
+     * 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(): TargetRegistry;
+}
+
 /**
  * src/builders/types.ts
  *
@@ -541,10 +750,25 @@ interface BuildConfig {
      */
     plugins?: PersonaBuildPlugin[];
     /**
-     * Target output formats to build. Defaults to both `'vscode'` and
-     * `'claude-code'` when omitted.
+     * Target output formats to build.
+     *
+     * Default behaviour depends on whether `targetRegistry` is provided:
+     * - **No custom registry** (default): builds `['vscode', 'claude-code']` to
+     *   preserve backward compatibility — suites that do not configure a
+     *   `'deep-agents'` output directory would otherwise fail silently.
+     * - **Custom registry supplied**: builds all targets registered in that
+     *   registry (equivalent to `registry.names()`).
+     *
+     * Pass an explicit array to override either default:
+     * ```ts
+     * targets: ['vscode', 'claude-code', 'deep-agents']
+     * ```
+     *
+     * Accepts any registered target name — all three built-in targets
+     * (`'vscode'`, `'claude-code'`, `'deep-agents'`) and any custom target
+     * added via `targetRegistry`.
      */
-    targets?: Array<'vscode' | 'claude-code'>;
+    targets?: string[];
     /**
      * When `true`, no files are written to disk. The build still renders all
      * personas and collects ValidationResults, but all write operations are
@@ -558,12 +782,24 @@ interface BuildConfig {
      */
     strict?: boolean;
     /**
-     * Optional map of default frontmatter templates, keyed by target type.
+     * Optional map of default frontmatter templates, keyed by target name.
      * These are used as library defaults and can be overridden by plugin
-     * `frontmatterTemplates`. When absent, built-in defaults from
-     * `src/builders/frontmatter.ts` are used.
+     * `frontmatterTemplates`. When absent, built-in defaults from the
+     * `TargetDefinition.defaultFrontmatter` are used.
      */
-    frontmatter?: Partial<Record<'vscode' | 'claude-code', string>>;
+    frontmatter?: Record<string, string>;
+    /**
+     * Optional target registry to use for this build.
+     *
+     * When provided, overrides the built-in `defaultRegistry` for output
+     * directory resolution, filename key lookup, frontmatter defaults, and
+     * context flag injection. Consumers can register custom targets on the
+     * provided registry to extend the build system without touching source code.
+     *
+     * Defaults to `defaultRegistry` (pre-registered with `'vscode'`,
+     * `'claude-code'`, and `'deep-agents'`) when not supplied.
+     */
+    targetRegistry?: TargetRegistry;
 }
 /**
  * The outcome of building a single persona for a single target.
@@ -571,8 +807,8 @@ interface BuildConfig {
 interface BuildResult {
     /** The suite identifier this persona belongs to */
     suite: string;
-    /** Target platform this result was generated for */
-    target: 'vscode' | 'claude-code';
+    /** Target name this result was generated for (e.g. `'vscode'`, `'claude-code'`, or a custom target) */
+    target: string;
     /** Absolute path to the persona YAML source file */
     personaYamlPath: string;
     /** Absolute path to the output file (may not exist if check mode) */
@@ -610,7 +846,7 @@ interface BuildSummary {
  *
  * Frontmatter template registry for @mistralys/persona-builder.
  *
- * Ships two minimal default templates — one per target — that work for the
+ * Ships three minimal default templates — one per built-in target — that work for the
  * "standalone" persona mode (simple personas without numbered workflows or
  * MCP server blocks).  Projects needing richer frontmatter register custom
  * templates via the `PersonaBuildPlugin.frontmatterTemplates` property.
@@ -622,37 +858,23 @@ interface BuildSummary {
  * No partials in frontmatter — frontmatter is kept deliberately simple.
  */
 
-/**
- * Default VS Code frontmatter template.
- *
- * Minimal fields that work for standalone personas.  Projects using numbered
- * workflows (e.g. ledger) should inject a richer template via a plugin.
- */
-declare const DEFAULT_FRONTMATTER_VSCODE = "---\nname: '{{name}} v{{version}}'\ndescription: '{{description}}'\ntools: [{{tools_list}}]\n---";
-/**
- * Default Claude Code frontmatter template.
- *
- * Minimal fields that work for standalone personas.  Projects using numbered
- * workflows should inject a richer template via a plugin.
- */
-declare const DEFAULT_FRONTMATTER_CLAUDE_CODE = "---\nname: {{cc_file_name_stem}}\npermissionMode: {{cc_permission_mode}}\nmodel: {{cc_model}}\nmemory: {{cc_memory}}\nallowedTools: [{{cc_tools_list}}]\n---";
 /**
  * Resolve frontmatter template precedence.
  *
  * Precedence order (highest wins):
- *   1. Plugin `frontmatterTemplates` — the last plugin with a matching key
- *      wins (plugins are applied in reverse-registration order so the
- *      *first* registered plugin with a template takes precedence over later
- *      ones, matching the general plugin-chain contract).
+ *   1. Plugin `frontmatterTemplates` — plugins are checked in registration
+ *      order; the first plugin with a matching key wins.
  *   2. `configTemplates` — templates passed via `BuildConfig.frontmatter`
- *   3. Library defaults (`DEFAULT_FRONTMATTER_VSCODE` / `DEFAULT_FRONTMATTER_CLAUDE_CODE`)
+ *   3. Registry default — `TargetDefinition.defaultFrontmatter` for the target
+ *   4. Library default (`DEFAULT_FRONTMATTER_VSCODE`) — safety fallback only
  *
- * @param target          The build target ('vscode' | 'claude-code')
+ * @param target          The build target name (e.g. `'vscode'`, `'claude-code'`, or a custom target)
  * @param plugins         Registered plugins (searched in order; first match wins)
  * @param configTemplates Optional caller-supplied overrides from BuildConfig
+ * @param registry        Optional TargetRegistry for resolving the built-in default template
  * @returns               The resolved template string
  */
-declare function resolveFrontmatterTemplate(target: 'vscode' | 'claude-code', plugins: PersonaBuildPlugin[], configTemplates?: Partial<Record<'vscode' | 'claude-code', string>>): string;
+declare function resolveFrontmatterTemplate(target: string, plugins: PersonaBuildPlugin[], configTemplates?: Record<string, string>, registry?: TargetRegistry): string;
 /**
  * Render a frontmatter template string against the given context.
  *
@@ -714,9 +936,17 @@ declare function renderFrontmatter(template: string, context: Record<string, unk
  * @param config           Top-level BuildConfig
  * @param plugins          Registered plugins
  * @param target           Target output format
+ * @param agentMap         Pre-built cross-suite agent name map
+ * @param registry         Target registry to use. Defaults to `defaultRegistry`.
+ *   **Two-registry limitation:** If you pass a custom `TargetRegistry` only
+ *   to `build()` (via `config.targetRegistry`) and call `buildPersona()`
+ *   directly without also passing that registry here, your custom targets
+ *   will not be visible — `defaultRegistry` will be used instead. Either
+ *   pass the same registry instance explicitly, or call `build()` to have
+ *   the registry forwarded automatically.
  * @returns                BuildResult for this persona × target combination
  */
-declare function buildPersona(personaYamlPath: string, suiteName: string, suiteConfig: SuiteConfig, sharedMeta: Record<string, unknown>, partialsMap: Record<string, string>, config: BuildConfig, plugins: PersonaBuildPlugin[], target: 'vscode' | 'claude-code', agentMap?: Record<string, string>): Promise<BuildResult>;
+declare function buildPersona(personaYamlPath: string, suiteName: string, suiteConfig: SuiteConfig, sharedMeta: Record<string, unknown>, partialsMap: Record<string, string>, config: BuildConfig, plugins: PersonaBuildPlugin[], target: string, agentMap?: Record<string, string>, registry?: TargetRegistry): Promise<BuildResult>;
 /**
  * Build all personas in a suite for a single output target.
  *
@@ -732,9 +962,17 @@ declare function buildPersona(personaYamlPath: string, suiteName: string, suiteC
  * @param config       Top-level BuildConfig
  * @param plugins      Registered plugins
  * @param target       Target output format
+ * @param agentMap     Pre-built cross-suite agent name map
+ * @param registry     Target registry to use. Defaults to `defaultRegistry`.
+ *   **Two-registry limitation:** If you pass a custom `TargetRegistry` only
+ *   to `build()` (via `config.targetRegistry`) and call `buildSuite()`
+ *   directly without also passing that registry here, your custom targets
+ *   will not be visible — `defaultRegistry` will be used instead. Either
+ *   pass the same registry instance explicitly, or call `build()` to have
+ *   the registry forwarded automatically.
  * @returns            Array of BuildResult objects, one per persona
  */
-declare function buildSuite(suiteName: string, suiteConfig: SuiteConfig, config: BuildConfig, plugins: PersonaBuildPlugin[], target: 'vscode' | 'claude-code', agentMap?: Record<string, string>): Promise<BuildResult[]>;
+declare function buildSuite(suiteName: string, suiteConfig: SuiteConfig, config: BuildConfig, plugins: PersonaBuildPlugin[], target: string, agentMap?: Record<string, string>, registry?: TargetRegistry): Promise<BuildResult[]>;
 /**
  * Top-level build orchestrator.
  *
@@ -843,6 +1081,30 @@ declare function validateStrictMarkers(renderedContent: string, requiredMarkers:
  */
 declare function escapeRegExp(str: string): string;
 
+/**
+ * src/targets/built-in.ts
+ *
+ * Creates and exports the defaultRegistry — a TargetRegistry pre-populated
+ * with the three built-in targets: 'vscode', 'claude-code', and 'deep-agents'.
+ *
+ * Consumers import defaultRegistry when they need to register additional
+ * custom targets or query the built-in target definitions.
+ */
+
+/**
+ * Singleton TargetRegistry pre-populated with the three built-in targets:
+ * `'vscode'`, `'claude-code'`, and `'deep-agents'`.
+ *
+ * Import and call `register()` on this instance to add custom targets before
+ * invoking `build()`.
+ *
+ * **Warning:** This is a module-level singleton. Calling `register()` on it
+ * in tests mutates shared state that persists across test cases. Use
+ * `defaultRegistry.clone()` to obtain an isolated copy for test scenarios
+ * that need to register additional targets.
+ */
+declare const defaultRegistry: TargetRegistry;
+
 /**
  * @mistralys/persona-builder
  *
@@ -851,4 +1113,4 @@ declare function escapeRegExp(str: string): string;
 
 declare const VERSION: string;
 
-export { type BuildConfig, type BuildResult, type BuildSummary, DEFAULT_FRONTMATTER_CLAUDE_CODE, DEFAULT_FRONTMATTER_VSCODE, type PersonaBuildPlugin, type PersonaMetadata, type SuiteConfig, type TargetType, VERSION, type ValidationResult, build, buildPersona, buildSuite, collapseBlankLines, discoverPersonaYamls, ensureBlankLineBeforeHeadings, escapeRegExp, loadContent, loadMetadata, loadPartials, normalizeNewlines, renderFrontmatter, resolveConditionals, resolveFrontmatterTemplate, resolvePartials, resolveVariables, runBuildContext, runPostRender, runSuiteInit, runValidate, serializeTools, serializeToolsList, validateFileName, validateStrictMarkers };
+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, runPostRender, runSuiteInit, runValidate, serializeTools, serializeToolsList, validateFileName, validateStrictMarkers };