@mistralys/persona-builder 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,829 @@
+/**
+ * partials.ts
+ *
+ * Pure template-engine function for resolving partial inclusions.
+ * Supports {{> name}} syntax with up to depth-2 recursion to handle
+ * partials-within-partials. No file-system I/O.
+ */
+/**
+ * Resolve partial inclusions in a template string.
+ *
+ * Replaces `{{> name}}` markers with the content from `partialsMap`.
+ * Recursion is capped at depth 2 so that:
+ *   - depth 0 → 1: outer partials are expanded
+ *   - depth 1 → 2: one level of nested partials are expanded
+ *   - depth 2: recursion stops, marker is left as-is
+ *
+ * Each resolved partial is `trimEnd()`-ed to prevent trailing blank lines
+ * from causing double-blank-line artefacts during concatenation.
+ *
+ * If a partial name is not found in `partialsMap`, the original marker is
+ * preserved and a warning is emitted via `console.warn`.
+ *
+ * @param text       - Template string potentially containing {{> name}} markers
+ * @param partialsMap - Map of partial name → partial content
+ * @param depth      - Current recursion depth (callers should omit; defaults to 0)
+ * @returns          The template string with partial markers replaced
+ */
+declare function resolvePartials(text: string, partialsMap: Record<string, string>, depth?: number): string;
+
+/**
+ * conditionals.ts
+ *
+ * Pure template-engine function for resolving conditional blocks.
+ * Handles {{#if flag}}…{{/if}} and {{#if flag}}…{{else}}…{{/if}} syntax.
+ * No file-system I/O.
+ */
+/**
+ * Resolve conditional blocks in a template string.
+ *
+ * Syntax:
+ *   `{{#if flag}}content{{/if}}`
+ *   `{{#if flag}}truthy-content{{else}}falsy-content{{/if}}`
+ *
+ * Behaviour:
+ * - When `context[flag]` is truthy: the delimiters are stripped and the
+ *   content before `{{else}}` (or the entire inner block if no `{{else}}`)
+ *   is kept, surrounded by single `\n` delimiters.
+ * - When `context[flag]` is falsy and a `{{else}}` branch exists: the
+ *   content after `{{else}}` is kept, surrounded by single `\n` delimiters.
+ * - When `context[flag]` is falsy and no `{{else}}` branch exists: the
+ *   entire block (including surrounding newlines) is removed, leaving a
+ *   single `\n`.
+ * - Unknown flags (absent from context) are treated as falsy.
+ *
+ * Leading and trailing newlines within the kept content are trimmed so the
+ * output does not accumulate extra blank lines.
+ *
+ * @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
+ */
+declare function resolveConditionals(text: string, context: Record<string, unknown>): string;
+
+/**
+ * variables.ts
+ *
+ * Pure template-engine function for resolving variable substitutions.
+ * Handles {{varName}} syntax. No file-system I/O.
+ */
+/**
+ * Resolve variable substitutions in a template string.
+ *
+ * Replaces `{{varName}}` markers with `String(context[varName])`.
+ * If a variable is not found in `context` (or its value is `undefined`),
+ * the original marker is preserved and a warning is emitted via
+ * `console.warn`, identifying the file by `filename` for easier debugging.
+ *
+ * Note: this step must run AFTER `resolvePartials` and `resolveConditionals`
+ * so that only plain variable markers remain.
+ *
+ * @param text     - Template string potentially containing {{varName}} markers
+ * @param context  - Key-value map of variable name → value
+ * @param filename - Identifier used in warning messages (e.g. persona file path)
+ * @returns        The template string with variable markers substituted
+ */
+declare function resolveVariables(text: string, context: Record<string, unknown>, filename: string): string;
+
+/**
+ * postProcessor.ts
+ *
+ * Pure post-processing functions for cleaning up rendered persona output.
+ * All functions are side-effect-free and operate only on strings.
+ * No file-system I/O.
+ */
+/**
+ * Collapse 3 or more consecutive blank lines into 2 blank lines.
+ *
+ * Specifically converts 4 or more consecutive `\n` characters into `\n\n\n`
+ * (which equals 2 blank lines between paragraphs).
+ *
+ * @param text - Rendered output string
+ * @returns    String with excessive blank lines collapsed
+ */
+declare function collapseBlankLines(text: string): string;
+/**
+ * Ensure every Markdown heading has a blank line immediately before it.
+ *
+ * Also ensures horizontal rules (`---`) have a blank line before and after
+ * them. This corrects spacing gaps caused by partial concatenation where
+ * `trimEnd()` strips trailing newlines and conditionals add only a single
+ * `\n` delimiter.
+ *
+ * @param text - Rendered output string
+ * @returns    String with blank lines inserted before headings and rules
+ */
+declare function ensureBlankLineBeforeHeadings(text: string): string;
+/**
+ * Normalize line endings to LF (`\n`) for OS-agnostic output.
+ *
+ * Converts CRLF (`\r\n`) first, then strips any remaining stray CR (`\r`).
+ *
+ * @param text - String potentially containing CRLF or CR line endings
+ * @returns    String with all line endings normalized to LF
+ */
+declare function normalizeNewlines(text: string): string;
+
+/**
+ * serializer.ts
+ *
+ * Pure serializer functions for converting tool lists to YAML-compatible
+ * string representations. No file-system I/O.
+ */
+/**
+ * Serialize a tools array in YAML single-quote flow format WITH outer brackets.
+ *
+ * Output format: `['tool1', 'tool2', 'tool3']`
+ * Used by the ledger suite to preserve byte-identical frontmatter output.
+ *
+ * @param tools - Array of tool name strings
+ * @returns     YAML flow-sequence string including outer brackets
+ *
+ * @example
+ * serializeTools(['Bash', 'Read']) // => "['Bash', 'Read']"
+ * serializeTools([])              // => "[]"
+ */
+declare function serializeTools(tools: string[]): string;
+/**
+ * Serialize a tools array in YAML single-quote flow format WITHOUT outer brackets.
+ *
+ * Output format: `'tool1', 'tool2', 'tool3'`
+ * Used inside standalone frontmatter templates which supply the surrounding `[ ]`.
+ *
+ * @param tools - Array of tool name strings
+ * @returns     Comma-separated quoted tool names (no outer brackets)
+ *
+ * @example
+ * serializeToolsList(['Bash', 'Read']) // => "'Bash', 'Read'"
+ * serializeToolsList([])              // => ""
+ */
+declare function serializeToolsList(tools: string[]): string;
+
+/**
+ * src/loaders/partials-loader.ts
+ *
+ * File-system loader for Handlebars-style partial snippets.
+ *
+ * Reads every `.md` file in `dir`, keys each entry by the filename stem
+ * (i.e. the portion before the final `.md` extension), and returns the
+ * map.  Callers that need a two-layer (shared → suite-local override)
+ * setup should call `loadPartials` twice and merge the results themselves,
+ * with the suite-local result spreading last.
+ *
+ * All file reads are performed asynchronously.  Path construction uses
+ * `path.join` and `path.posix`-compatible operations so no path-separator
+ * assumptions are baked in.
+ */
+/**
+ * Load all `.md` files in `dir` and return them as a `Record<string, string>`
+ * keyed by filename stem.
+ *
+ * Files whose names do not end in `.md` are silently ignored.
+ * The directory must exist; a missing directory throws an `ENOENT` error from
+ * the underlying `readdir` call (let callers decide how to handle absence).
+ *
+ * @param dir  Absolute (or relative) path to the directory to scan.
+ * @returns    A map from filename stem → file content string.
+ *
+ * @example
+ * const partials = await loadPartials('/project/partials');
+ * // { greeting: 'Hello, {{name}}!', footer: '---\nEnd of file' }
+ */
+declare function loadPartials(dir: string): Promise<Record<string, string>>;
+
+/**
+ * src/plugins/types.ts
+ *
+ * Core plugin system types for @smor/persona-build.
+ *
+ * Defines:
+ *   - TargetType         — union of supported output targets
+ *   - PersonaMetadata    — typed representation of a persona YAML file
+ *   - SuiteConfig        — configuration for a single persona suite
+ *   - ValidationResult   — outcome of a plugin's onValidate hook
+ *   - 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
+ */
+type TargetType = 'vscode' | 'claude-code';
+/**
+ * Typed representation of a persona YAML metadata file.
+ *
+ * Fields map directly to the keys expected in `*.yaml` persona files.
+ * All fields beyond `name` are optional — consumers should treat them
+ * as potentially absent and fall back to suite-level or shared defaults.
+ */
+interface PersonaMetadata {
+    /** Unique persona identifier (matches filename stem) */
+    name: string;
+    /** Human-readable display name */
+    displayName?: string;
+    /** Short description surfaced in frontmatter */
+    description?: string;
+    /** Semantic version string (e.g. "1.2.0") */
+    version?: string;
+    /** Ordered list of tool identifiers */
+    tools?: string[];
+    /** Free-form context variables available during template rendering */
+    [key: string]: unknown;
+}
+/**
+ * Configuration for a single persona suite (directory of related personas).
+ */
+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;
+    /**
+     * Optional persona mode string (e.g. 'ledger').
+     * When present, plugins can use this to branch behaviour.
+     */
+    personaMode?: string;
+    /** Sub-directory within srcDir that contains partials. Default: 'partials' */
+    partialsSubdir?: string;
+    /** Sub-directory within srcDir that contains YAML metadata. Default: 'meta' */
+    metaSubdir?: string;
+    /** Sub-directory within srcDir that contains content Markdown files. Default: 'content' */
+    contentSubdir?: string;
+}
+/**
+ * A single validation outcome returned by a plugin's `onValidate` hook.
+ */
+interface ValidationResult {
+    /** Severity level of the issue */
+    severity: 'error' | 'warning' | 'info';
+    /** Human-readable description of the issue */
+    message: string;
+}
+/**
+ * Interface that every persona build plugin must implement.
+ *
+ * All hooks are optional — a plugin only needs to implement the hooks it
+ * uses. The only required field is `name`, which is used for logging and
+ * identification.
+ *
+ * Hook invocation order (per persona):
+ *   1. onSuiteInit   — once per suite, before any persona is built
+ *   2. onBuildContext — per persona, before template rendering
+ *   3. onPostRender   — per persona, after body rendering
+ *   4. onValidate     — per persona, during the validation phase
+ */
+interface PersonaBuildPlugin {
+    /**
+     * Unique name for this plugin (used in log messages and error reporting).
+     */
+    name: string;
+    /**
+     * Called once per suite before any persona is built.
+     *
+     * Use this hook to perform suite-level setup — e.g. loading external data,
+     * validating the suite config, or mutating `sharedMeta` for downstream hooks.
+     *
+     * @param suite      The suite configuration object
+     * @param sharedMeta Shared metadata merged from `_shared.yaml` (mutate in place if needed)
+     */
+    onSuiteInit?(suite: SuiteConfig, sharedMeta: Record<string, unknown>): void;
+    /**
+     * Called for each persona before template rendering.
+     *
+     * Receives the current rendering context and must return a (possibly mutated)
+     * context object. Plugins are chained: each plugin receives the output of the
+     * previous one.
+     *
+     * @param context  Current rendering context (accumulates across plugins)
+     * @param persona  Typed metadata for the persona being built
+     * @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>;
+    /**
+     * Called for each persona after body rendering.
+     *
+     * Receives the rendered output string and can return a mutated version.
+     * Plugins are chained: each plugin receives the output of the previous one.
+     *
+     * @param output  The rendered persona output string (accumulates across plugins)
+     * @param persona Typed metadata for the persona being built
+     * @param target  The current build target
+     * @returns       Updated output string
+     */
+    onPostRender?(output: string, persona: PersonaMetadata, target: TargetType): string;
+    /**
+     * Called during the validation phase for each persona.
+     *
+     * Return an array of ValidationResult objects (or an empty array).
+     * Results from all plugins are collected into a flat array by the runner.
+     *
+     * @param persona Typed metadata for the persona being built
+     * @param suite   The suite configuration object
+     * @returns       Array of validation results (may be empty)
+     */
+    onValidate?(persona: PersonaMetadata, suite: SuiteConfig): ValidationResult[];
+    /**
+     * Optional map of custom frontmatter templates keyed by target type.
+     *
+     * When present, the builder will use these templates in place of (or to
+     * augment) the library defaults for the matching target.
+     */
+    frontmatterTemplates?: Partial<Record<TargetType, string>>;
+}
+
+/**
+ * src/loaders/metadata-loader.ts
+ *
+ * File-system loader for persona YAML metadata files.
+ *
+ * Provides two exports:
+ *
+ *  1. `discoverPersonaYamls(root)` — recursively walks `root` and returns
+ *     absolute paths for every `*.yaml` file found, regardless of nesting
+ *     depth.  Uses Node's built-in `fs.readdir` with `recursive: true`
+ *     (available since Node 18.17).  No glob library is required.
+ *
+ *  2. `loadMetadata(yamlPath)` — reads a single YAML file and parses it
+ *     with `js-yaml` into a fully typed `PersonaMetadata` object.
+ *
+ * Path construction relies exclusively on `node:path` so the output is
+ * correct on both POSIX and Windows.
+ */
+
+/**
+ * Recursively discover all `*.yaml` files under `root` and return their
+ * absolute paths sorted lexicographically.
+ *
+ * Uses `readdir` with `{ recursive: true }` (Node ≥ 18.17).  Each returned
+ * path is normalised through `path.resolve` so callers always receive
+ * absolute, platform-consistent paths.
+ *
+ * @param root  The directory to search (absolute or resolvable relative path).
+ * @returns     Sorted array of absolute paths to every `*.yaml` file found.
+ *
+ * @example
+ * const yamls = await discoverPersonaYamls('/project/personas/ledger/src/meta');
+ * // ['/project/personas/ledger/src/meta/alpha.yaml', ...]
+ */
+declare function discoverPersonaYamls(root: string): Promise<string[]>;
+/**
+ * Load and parse a single persona YAML file into a typed `PersonaMetadata`
+ * object.
+ *
+ * The YAML is parsed using `js-yaml`'s safe `load` function.  The result
+ * is validated to be a non-null object; if the YAML is empty or does not
+ * parse to an object, an `Error` is thrown.
+ *
+ * `PersonaMetadata` requires a `name` field.  If the YAML does not contain
+ * a `name` key the function throws an `Error` with a descriptive message.
+ *
+ * @param yamlPath  Absolute path to the YAML file.
+ * @returns         Parsed and validated `PersonaMetadata` object.
+ * @throws          `Error` when the file is unparseable, not an object, or
+ *                  is missing the required `name` field.
+ *
+ * @example
+ * const meta = await loadMetadata('/project/meta/my-persona.yaml');
+ * // { name: 'my-persona', description: '...', tools: [...] }
+ */
+declare function loadMetadata(yamlPath: string): Promise<PersonaMetadata>;
+
+/**
+ * src/loaders/content-loader.ts
+ *
+ * File-system loader for persona Markdown content templates.
+ *
+ * Provides a single `loadContent` function that reads the raw string content
+ * of a persona Markdown file from disk.  The content is returned exactly as
+ * stored — no template substitution, no post-processing.  Those concerns
+ * belong to the engine layer.
+ *
+ * All I/O is asynchronous.  Path construction uses `node:path` so the
+ * implementation is path-separator–agnostic.
+ */
+/**
+ * Read a persona Markdown content file and return its raw string content.
+ *
+ * The file is read with UTF-8 encoding.  No parsing, template resolution,
+ * or post-processing is applied — that is the engine layer's responsibility.
+ *
+ * @param mdPath  Absolute (or resolvable relative) path to the `.md` file.
+ * @returns       Raw UTF-8 string content of the file.
+ * @throws        An `ENOENT` error (from `fs/promises`) if the file does not
+ *                exist, or any other I/O error the OS reports.
+ *
+ * @example
+ * const body = await loadContent('/project/content/my-persona.md');
+ * // '{{> greeting}}\n\n## About\n\nThis is {{name}}...'
+ */
+declare function loadContent(mdPath: string): Promise<string>;
+
+/**
+ * src/plugins/runner.ts
+ *
+ * Plugin runner — responsible for invoking plugin hooks in registration order.
+ *
+ * Each exported function corresponds to one lifecycle hook defined in
+ * PersonaBuildPlugin. The runner:
+ *   - Skips plugins that do not implement the requested hook (hook is optional)
+ *   - Invokes hooks in the order plugins are registered (first-in first-called)
+ *   - For accumulating hooks (onBuildContext, onPostRender), each plugin
+ *     receives the output of the previous plugin as its first argument
+ *   - For collecting hooks (onValidate), results are concatenated into a
+ *     flat array
+ *
+ * No file-system I/O. No async operations.
+ */
+
+/**
+ * Invoke the `onSuiteInit` hook on every registered plugin.
+ *
+ * Each plugin may optionally implement this hook. Plugins are called in
+ * registration order. The hook receives the suite config and a mutable
+ * `sharedMeta` object — plugins may mutate `sharedMeta` in place; the
+ * same reference is passed to every subsequent plugin.
+ *
+ * @param plugins    Ordered list of registered plugins
+ * @param suite      The suite configuration object
+ * @param sharedMeta Mutable shared metadata object (mutated in place by plugins)
+ */
+declare function runSuiteInit(plugins: PersonaBuildPlugin[], suite: SuiteConfig, sharedMeta: Record<string, unknown>): void;
+/**
+ * Invoke the `onBuildContext` hook on every registered plugin, accumulating
+ * context mutations sequentially.
+ *
+ * Each plugin receives the context returned by the previous plugin. If a
+ * plugin does not implement `onBuildContext`, the context passes through
+ * unchanged. The final accumulated context is returned.
+ *
+ * @param plugins Ordered list of registered plugins
+ * @param ctx     Initial rendering context for this persona
+ * @param persona Typed metadata for the persona being built
+ * @param suite   The suite configuration object
+ * @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>;
+/**
+ * Invoke the `onPostRender` hook on every registered plugin, chaining the
+ * output string sequentially.
+ *
+ * Each plugin receives the string returned by the previous plugin. If a
+ * plugin does not implement `onPostRender`, the string passes through
+ * unchanged. The final string is returned.
+ *
+ * @param plugins  Ordered list of registered plugins
+ * @param rendered Initial rendered output string
+ * @param persona  Typed metadata for the persona being built
+ * @param target   The current build target
+ * @returns        Final output string after all plugins have run
+ */
+declare function runPostRender(plugins: PersonaBuildPlugin[], rendered: string, persona: PersonaMetadata, target: TargetType): string;
+/**
+ * Invoke the `onValidate` hook on every registered plugin and collect all
+ * returned ValidationResult objects into a single flat array.
+ *
+ * Plugins that do not implement `onValidate` contribute nothing to the result.
+ * The return value is always an array (never null/undefined).
+ *
+ * @param plugins Ordered list of registered plugins
+ * @param persona Typed metadata for the persona being built
+ * @param suite   The suite configuration object
+ * @returns       Flat array of all ValidationResult objects from all plugins
+ */
+declare function runValidate(plugins: PersonaBuildPlugin[], persona: PersonaMetadata, suite: SuiteConfig): ValidationResult[];
+
+/**
+ * src/builders/types.ts
+ *
+ * Core types for the persona builder layer.
+ *
+ * Defines:
+ *   - BuildConfig     — typed configuration accepted by build()
+ *   - BuildResult     — outcome of building a single persona
+ *   - BuildSummary    — aggregated result returned by build()
+ *
+ * TargetType is re-exported from plugins/types so consumers can import
+ * everything builder-related from a single module.
+ */
+
+/**
+ * Top-level configuration accepted by `build()`.
+ *
+ * At minimum, `suites` must be provided. All other fields have sensible
+ * defaults so a minimal configuration is:
+ *
+ * ```ts
+ * const summary = await build({
+ *   suites: { my-suite: { srcDir: './src', outVscode: './out/vs', outClaudeCode: './out/cc' } },
+ * });
+ * ```
+ */
+interface BuildConfig {
+    /**
+     * Named map of suite configurations. Each key is a suite identifier; the
+     * value describes source and output directories for that suite.
+     */
+    suites: Record<string, SuiteConfig>;
+    /**
+     * Absolute path to the shared partials directory. When provided, partials
+     * from this directory are loaded as the base layer before suite-local
+     * partials are overlaid. Optional.
+     */
+    sharedPartialsDir?: string;
+    /**
+     * List of registered plugins. Plugins are invoked in array order for every
+     * hook. Defaults to `[]`.
+     */
+    plugins?: PersonaBuildPlugin[];
+    /**
+     * Target output formats to build. Defaults to both `'vscode'` and
+     * `'claude-code'` when omitted.
+     */
+    targets?: Array<'vscode' | 'claude-code'>;
+    /**
+     * When `true`, no files are written to disk. The build still renders all
+     * personas and collects ValidationResults, but all write operations are
+     * skipped. Defaults to `false`.
+     */
+    check?: boolean;
+    /**
+     * When `true`, the build fails (throws or returns a failed summary) if any
+     * ValidationResult has severity `'error'` or `'warning'`. Defaults to
+     * `false`.
+     */
+    strict?: boolean;
+    /**
+     * Optional map of default frontmatter templates, keyed by target type.
+     * 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.
+     */
+    frontmatter?: Partial<Record<'vscode' | 'claude-code', string>>;
+}
+/**
+ * The outcome of building a single persona for a single target.
+ */
+interface BuildResult {
+    /** The suite identifier this persona belongs to */
+    suite: string;
+    /** Target platform this result was generated for */
+    target: 'vscode' | 'claude-code';
+    /** Absolute path to the persona YAML source file */
+    personaYamlPath: string;
+    /** Absolute path to the output file (may not exist if check mode) */
+    outputPath: string;
+    /** The rendered persona content */
+    content: string;
+    /** Validation results collected from all plugins */
+    validationResults: ValidationResult[];
+    /** Whether the output file was written to disk (false in check mode) */
+    written: boolean;
+}
+/**
+ * Aggregated result returned by `build()` after processing all suites and
+ * targets.
+ */
+interface BuildSummary {
+    /** Whether the overall build succeeded */
+    success: boolean;
+    /** Individual results for each persona × target combination */
+    results: BuildResult[];
+    /**
+     * When `strict` mode is enabled and a failure was detected, this holds all
+     * ValidationResults with severity `'error'` or `'warning'` that caused the
+     * failure. Empty otherwise.
+     */
+    strictFailures: ValidationResult[];
+    /** Total number of persona files processed */
+    totalBuilt: number;
+    /** Total number of output files written (0 in check mode) */
+    totalWritten: number;
+}
+
+/**
+ * src/builders/frontmatter.ts
+ *
+ * Frontmatter template registry for @smor/persona-build.
+ *
+ * Ships two minimal default templates — one per 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.
+ *
+ * Template rendering follows the same two-step sequence as body rendering:
+ *   1. resolveConditionals() — resolve {{#if flag}} blocks
+ *   2. resolveVariables()    — substitute {{varName}} markers
+ *
+ * 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).
+ *   2. `configTemplates` — templates passed via `BuildConfig.frontmatter`
+ *   3. Library defaults (`DEFAULT_FRONTMATTER_VSCODE` / `DEFAULT_FRONTMATTER_CLAUDE_CODE`)
+ *
+ * @param target          The build target ('vscode' | 'claude-code')
+ * @param plugins         Registered plugins (searched in order; first match wins)
+ * @param configTemplates Optional caller-supplied overrides from BuildConfig
+ * @returns               The resolved template string
+ */
+declare function resolveFrontmatterTemplate(target: 'vscode' | 'claude-code', plugins: PersonaBuildPlugin[], configTemplates?: Partial<Record<'vscode' | 'claude-code', string>>): string;
+/**
+ * Render a frontmatter template string against the given context.
+ *
+ * Applies the standard two-step template resolution:
+ *   1. `resolveConditionals` — `{{#if flag}}` blocks
+ *   2. `resolveVariables`    — `{{varName}}` substitution
+ *
+ * @param template  The raw frontmatter template string (may contain markers)
+ * @param context   Key-value context for variable substitution
+ * @param filename  Source filename used in warning messages
+ * @returns         Rendered frontmatter string (ready to prepend to body)
+ */
+declare function renderFrontmatter(template: string, context: Record<string, unknown>, filename: string): string;
+
+/**
+ * src/builders/persona-builder.ts
+ *
+ * Core build orchestrator for @smor/persona-build.
+ *
+ * Exports three public functions:
+ *
+ *  1. buildPersona(personaYamlPath, suiteName, suiteConfig, sharedMeta,
+ *                  partialsMap, config, plugins)
+ *     — Builds a single persona for a single target. Returns a BuildResult.
+ *
+ *  2. buildSuite(suiteName, suiteConfig, config, plugins)
+ *     — Discovers all persona YAMLs for a suite, fires onSuiteInit, maps
+ *       buildPersona() over each, and returns BuildResult[].
+ *
+ *  3. build(config)
+ *     — Top-level entry point. Iterates all suites × targets, calls
+ *       buildSuite() for each combination, and returns a BuildSummary.
+ *       Respects --check (no writes) and --strict (fail on warnings/errors).
+ */
+
+/**
+ * Build a single persona for a single output target.
+ *
+ * Pipeline:
+ *   1. Load sharedMeta + personaMeta (callers supply pre-loaded values)
+ *   2. Build merged context
+ *   3. Run onBuildContext plugin hooks (context accumulation)
+ *   4. Resolve frontmatter template → render frontmatter
+ *   5. Load content template
+ *   6. Render body: partials → conditionals → variables → post-process
+ *   7. Assemble final output (frontmatter + body)
+ *   8. Run onPostRender plugin hooks (output chain)
+ *   9. Run onValidate plugin hooks (validation collection)
+ *  10. Determine output file path
+ *  11. Write output file (unless check mode)
+ *  12. Return BuildResult
+ *
+ * @param personaYamlPath  Absolute path to the persona YAML source file
+ * @param suiteName        Identifier for the suite this persona belongs to
+ * @param suiteConfig      Suite configuration object
+ * @param sharedMeta       Pre-loaded `_shared.yaml` contents
+ * @param partialsMap      Pre-loaded partials map (shared + suite-local merged)
+ * @param config           Top-level BuildConfig
+ * @param plugins          Registered plugins
+ * @param target           Target output format
+ * @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'): Promise<BuildResult>;
+/**
+ * Build all personas in a suite for a single output target.
+ *
+ * Pipeline:
+ *   1. Load `_shared.yaml` for the suite
+ *   2. Load merged partials (shared → suite-local)
+ *   3. Run `onSuiteInit` on all plugins
+ *   4. Discover all persona YAML files
+ *   5. Call `buildPersona()` for each
+ *
+ * @param suiteName    Identifier for this suite
+ * @param suiteConfig  Suite configuration
+ * @param config       Top-level BuildConfig
+ * @param plugins      Registered plugins
+ * @param target       Target output format
+ * @returns            Array of BuildResult objects, one per persona
+ */
+declare function buildSuite(suiteName: string, suiteConfig: SuiteConfig, config: BuildConfig, plugins: PersonaBuildPlugin[], target: 'vscode' | 'claude-code'): Promise<BuildResult[]>;
+/**
+ * Top-level build orchestrator.
+ *
+ * Iterates all `config.suites × config.targets` combinations, calls
+ * `buildSuite()` for each, and aggregates the results into a `BuildSummary`.
+ *
+ * Modes:
+ *   - Normal: renders and writes all personas.
+ *   - `check: true`: renders without writing; useful for CI staleness checks.
+ *   - `strict: true`: throws when any ValidationResult has severity `'error'`
+ *     or `'warning'`. All suites are processed before the throw, so output
+ *     files **will** be written to disk even when the build ultimately fails.
+ *     **For CI usage, combine `strict: true` with `check: true`** to avoid
+ *     leaving partial artefacts on disk when validation fails.
+ *
+ * @param config  Typed build configuration
+ * @returns       Aggregated BuildSummary
+ * @throws        `Error` when `strict: true` and validation failures exist
+ */
+declare function build(config: BuildConfig): Promise<BuildSummary>;
+
+/**
+ * src/validators/filename-validator.ts
+ *
+ * Validates persona output filenames against the project naming convention.
+ *
+ * Convention: kebab-case only — lowercase letters, digits, and hyphens.
+ * No spaces, no uppercase letters, no special characters other than hyphens
+ * and dots (for the file extension).
+ *
+ * This is a pure function: no file I/O, no process.exit, no side effects.
+ * It depends only on `ValidationResult` from `src/plugins/types.ts`.
+ */
+
+/**
+ * Validate a persona filename against the project naming convention.
+ *
+ * Accepts either a bare filename (`my-persona.md`) or a full/relative path
+ * — only the basename (last path segment) is evaluated.
+ *
+ * @param filePath  Filename or path to validate (only the basename is checked)
+ * @returns         Empty array when the filename conforms; one ValidationResult
+ *                  per violated rule otherwise. Each result has severity "error".
+ *
+ * @example
+ * validateFileName('my-persona.md');          // []
+ * validateFileName('My Persona.md');          // [{severity:'error', message:'...'}]
+ * validateFileName('/abs/path/my-persona.md');// []
+ */
+declare function validateFileName(filePath: string): ValidationResult[];
+
+/**
+ * src/validators/strict-validator.ts
+ *
+ * Validates that a set of required marker strings are present in a rendered
+ * persona output string.
+ *
+ * "Strict" mode in the build pipeline guards against incomplete renders —
+ * e.g. a required section marker (e.g. "{{ROLE}}") that was never resolved.
+ * This validator generalises that concept: callers supply the list of marker
+ * strings that *must* appear in the final rendered content.
+ *
+ * This is a pure function: no file I/O, no side effects.
+ * It depends only on `ValidationResult` from `src/plugins/types.ts`.
+ */
+
+/**
+ * Validate that every required marker string is present in the rendered output.
+ *
+ * Each absent marker produces one `ValidationResult` entry with severity
+ * `"error"` and a descriptive message identifying the missing marker.
+ *
+ * @param renderedContent  The final rendered output string to inspect
+ * @param requiredMarkers  Array of marker strings that must appear verbatim in
+ *                         `renderedContent`. An empty array always returns `[]`.
+ * @returns                Empty array when all markers are found; one entry per
+ *                         absent marker otherwise. Each entry has severity "error".
+ *
+ * @example
+ * validateStrictMarkers('Hello world', ['Hello', 'world']); // []
+ * validateStrictMarkers('Hello world', ['{{MISSING}}']);
+ * // [{severity:'error', message:'Required marker "{{MISSING}}" is missing from the rendered output.'}]
+ */
+declare function validateStrictMarkers(renderedContent: string, requiredMarkers: string[]): ValidationResult[];
+
+/**
+ * @smor/persona-build
+ *
+ * Public API barrel export.
+ * Feature modules will be exported from here as they are implemented in subsequent WPs.
+ */
+
+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, loadContent, loadMetadata, loadPartials, normalizeNewlines, renderFrontmatter, resolveConditionals, resolveFrontmatterTemplate, resolvePartials, resolveVariables, runBuildContext, runPostRender, runSuiteInit, runValidate, serializeTools, serializeToolsList, validateFileName, validateStrictMarkers };