@mistralys/persona-builder 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mistralys
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,72 @@
+# 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.
+
+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
+- **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
+- **CI-friendly** — `--check` mode renders without writing; `--strict` exits non-zero on warnings
+- **Programmatic & CLI** — use the `build()` API in scripts or run `persona-build` from the command line
+- **Single dependency** — only `js-yaml` at runtime
+
+## 📋 Requirements
+
+- **Node.js** ≥ 18
+
+## 🚀 Quick Start
+
+```bash
+npm install @smor/persona-build
+```
+
+### Programmatic API
+
+```ts
+import { build } from '@smor/persona-build';
+import path from 'node:path';
+
+const summary = await build({
+  suites: {
+    'my-suite': {
+      srcDir: path.resolve('./personas/my-suite'),
+      outVscode: path.resolve('./dist/vscode'),
+      outClaudeCode: path.resolve('./dist/claude-code'),
+    },
+  },
+  sharedPartialsDir: path.resolve('./personas/shared/partials'),
+});
+
+console.log(`Built ${summary.totalBuilt} persona(s), wrote ${summary.totalWritten} file(s).`);
+```
+
+### CLI
+
+```bash
+# Create a persona-build.config.js, then:
+npx persona-build
+
+# CI staleness check
+npx persona-build --check --strict
+```
+
+See the [CLI docs](docs/cli.md) for config file format and all flags.
+
+## 📖 Documentation
+
+| Guide | Description |
+|-------|-------------|
+| [Directory Convention](docs/directory-convention.md) | Expected source layout (`meta/`, `content/`, `partials/`) |
+| [Template Syntax](docs/template-syntax.md) | Variables, partials, conditionals, and built-in context variables |
+| [Configuration Reference](docs/configuration.md) | `BuildConfig`, `SuiteConfig`, and `BuildSummary` fields |
+| [CLI Reference](docs/cli.md) | Command-line flags, config file format, and common patterns |
+| [Plugins](docs/plugins.md) | `PersonaBuildPlugin` interface and examples |
+| [Public API](docs/api.md) | All exported types and functions |
+
+## 📄 License
+
+MIT

package/dist/cli.cjs

@@ -0,0 +1,514 @@
+#!/usr/bin/env node
+'use strict';
+
+var module$1 = require('module');
+var path2 = require('path');
+var fs = require('fs');
+var url = require('url');
+var promises = require('fs/promises');
+var yaml = require('js-yaml');
+
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var path2__default = /*#__PURE__*/_interopDefault(path2);
+var yaml__default = /*#__PURE__*/_interopDefault(yaml);
+
+// src/engine/partials.ts
+function resolvePartials(text, partialsMap, depth = 0) {
+  if (depth >= 2) return text;
+  return text.replace(/\{\{> ([\w-]+)\}\}/g, (match, name) => {
+    if (!(name in partialsMap)) {
+      console.warn(`[WARN] Partial not found: ${match}`);
+      return match;
+    }
+    return resolvePartials(partialsMap[name], partialsMap, depth + 1).trimEnd();
+  });
+}
+
+// src/engine/conditionals.ts
+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";
+    }
+  );
+}
+
+// src/engine/variables.ts
+function resolveVariables(text, context, filename) {
+  return text.replace(/\{\{(\w+)\}\}/g, (match, varName) => {
+    if (varName in context && context[varName] !== void 0) {
+      return String(context[varName]);
+    }
+    console.warn(`[WARN] Unresolved variable: ${match} in ${filename}`);
+    return match;
+  });
+}
+
+// src/engine/postProcessor.ts
+function collapseBlankLines(text) {
+  return text.replace(/\n{4,}/g, "\n\n\n");
+}
+function ensureBlankLineBeforeHeadings(text) {
+  let result = text.replace(/([^\n])\n(#{1,6} )/g, "$1\n\n$2");
+  result = result.replace(/([^\n])\n(---)\n/g, "$1\n\n$2\n");
+  result = result.replace(/\n(---)\n([^\n])/g, "\n$1\n\n$2");
+  return result;
+}
+function normalizeNewlines(text) {
+  return text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+
+// src/engine/serializer.ts
+function serializeTools(tools) {
+  return "[" + tools.map((t) => `'${t}'`).join(", ") + "]";
+}
+function serializeToolsList(tools) {
+  return tools.map((t) => `'${t}'`).join(", ");
+}
+async function loadPartials(dir) {
+  const entries = await promises.readdir(dir, { withFileTypes: true });
+  const mdFiles = entries.filter(
+    (entry) => entry.isFile() && entry.name.endsWith(".md")
+  );
+  const pairs = await Promise.all(
+    mdFiles.map(async (entry) => {
+      const stem = entry.name.slice(0, -".md".length);
+      const filePath = path2__default.default.join(dir, entry.name);
+      const content = await promises.readFile(filePath, "utf8");
+      return [stem, content];
+    })
+  );
+  return Object.fromEntries(pairs);
+}
+
+// src/plugins/runner.ts
+function runSuiteInit(plugins, suite, sharedMeta) {
+  for (const plugin of plugins) {
+    if (typeof plugin.onSuiteInit === "function") {
+      plugin.onSuiteInit(suite, sharedMeta);
+    }
+  }
+}
+function runBuildContext(plugins, ctx, persona, suite) {
+  let accumulated = ctx;
+  for (const plugin of plugins) {
+    if (typeof plugin.onBuildContext === "function") {
+      accumulated = plugin.onBuildContext(accumulated, persona, suite);
+    }
+  }
+  return accumulated;
+}
+function runPostRender(plugins, rendered, persona, target) {
+  let output = rendered;
+  for (const plugin of plugins) {
+    if (typeof plugin.onPostRender === "function") {
+      output = plugin.onPostRender(output, persona, target);
+    }
+  }
+  return output;
+}
+function runValidate(plugins, persona, suite) {
+  const results = [];
+  for (const plugin of plugins) {
+    if (typeof plugin.onValidate === "function") {
+      const pluginResults = plugin.onValidate(persona, suite);
+      results.push(...pluginResults);
+    }
+  }
+  return results;
+}
+
+// src/builders/frontmatter.ts
+var DEFAULT_FRONTMATTER_VSCODE = `---
+name: '{{name}} v{{version}}'
+description: '{{description}}'
+tools: [{{tools_list}}]
+---`;
+var DEFAULT_FRONTMATTER_CLAUDE_CODE = `---
+name: {{cc_file_name_stem}}
+permissionMode: {{cc_permission_mode}}
+model: {{cc_model}}
+memory: {{cc_memory}}
+allowedTools: [{{cc_tools_list}}]
+---`;
+function resolveFrontmatterTemplate(target, plugins, configTemplates) {
+  for (const plugin of plugins) {
+    if (plugin.frontmatterTemplates && target in plugin.frontmatterTemplates) {
+      const tpl = plugin.frontmatterTemplates[target];
+      if (tpl !== void 0) return tpl;
+    }
+  }
+  if (configTemplates && target in configTemplates) {
+    const tpl = configTemplates[target];
+    if (tpl !== void 0) return tpl;
+  }
+  return target === "vscode" ? DEFAULT_FRONTMATTER_VSCODE : DEFAULT_FRONTMATTER_CLAUDE_CODE;
+}
+function renderFrontmatter(template, context, filename) {
+  let rendered = resolveConditionals(template, context);
+  rendered = resolveVariables(rendered, context, filename);
+  return rendered;
+}
+
+// src/builders/persona-builder.ts
+async function discoverSuitePersonaYamls(suiteConfig) {
+  const metaSubdir = suiteConfig.metaSubdir ?? "meta";
+  const metaDir = path2__default.default.join(suiteConfig.srcDir, metaSubdir);
+  const entries = await promises.readdir(metaDir, { withFileTypes: true });
+  return entries.filter((e) => e.isFile() && e.name.endsWith(".yaml") && !e.name.startsWith("_")).map((e) => path2__default.default.join(metaDir, e.name)).sort();
+}
+async function loadRawYaml(filePath) {
+  if (!fs.existsSync(filePath)) return {};
+  const raw = await promises.readFile(filePath, "utf8");
+  const parsed = yaml__default.default.load(raw);
+  if (parsed === null || parsed === void 0) return {};
+  if (typeof parsed !== "object" || Array.isArray(parsed)) return {};
+  return parsed;
+}
+async function loadPersonaYaml(yamlPath) {
+  const raw = await promises.readFile(yamlPath, "utf8");
+  const parsed = yaml__default.default.load(raw);
+  if (parsed === null || parsed === void 0 || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error(`buildPersona: expected a YAML object in "${yamlPath}"`);
+  }
+  const record = parsed;
+  if (!record["name"]) {
+    record["name"] = path2__default.default.basename(yamlPath, ".yaml");
+  }
+  return record;
+}
+function buildContext(personaMeta, sharedMeta) {
+  const version = typeof personaMeta["version"] === "string" ? personaMeta["version"] : typeof sharedMeta["default_version"] === "string" ? sharedMeta["default_version"] : "0.0.0";
+  const merged = {
+    ...sharedMeta,
+    ...personaMeta,
+    version
+  };
+  const tools = Array.isArray(merged["tools"]) ? merged["tools"] : [];
+  if (!("tools_list" in merged)) {
+    merged["tools_list"] = serializeToolsList(tools);
+  }
+  if (!("tools_json" in merged)) {
+    merged["tools_json"] = serializeTools(tools);
+  }
+  const ccTools = Array.isArray(merged["cc_tools"]) ? merged["cc_tools"] : tools;
+  if (!("cc_tools_list" in merged)) {
+    merged["cc_tools_list"] = serializeToolsList(ccTools);
+  }
+  if (!("cc_tools_json" in merged)) {
+    merged["cc_tools_json"] = serializeTools(ccTools);
+  }
+  if (!("cc_file_name_stem" in merged) && typeof merged["cc_file_name"] === "string") {
+    const ccFileName = merged["cc_file_name"];
+    merged["cc_file_name_stem"] = ccFileName.replace(/\.md$/, "");
+  }
+  return merged;
+}
+async function buildPersona(personaYamlPath, suiteName, suiteConfig, sharedMeta, partialsMap, config, plugins, target) {
+  const personaMeta = await loadPersonaYaml(personaYamlPath);
+  let context = buildContext(personaMeta, sharedMeta);
+  const personaMetaTyped = personaMeta;
+  context = runBuildContext(plugins, context, personaMetaTyped, suiteConfig);
+  const fmTemplate = resolveFrontmatterTemplate(target, plugins, config.frontmatter);
+  const contentBasename = path2__default.default.basename(personaYamlPath, ".yaml") + ".md";
+  const frontmatter = renderFrontmatter(fmTemplate, context, contentBasename);
+  const contentSubdir = suiteConfig.contentSubdir ?? "content";
+  const contentPath = path2__default.default.join(suiteConfig.srcDir, contentSubdir, contentBasename);
+  const bodyTemplate = normalizeNewlines(await promises.readFile(contentPath, "utf8"));
+  let body = resolvePartials(bodyTemplate, partialsMap);
+  body = resolveConditionals(body, context);
+  body = resolveVariables(body, context, contentBasename);
+  body = collapseBlankLines(body);
+  body = ensureBlankLineBeforeHeadings(body);
+  body = body.trimEnd();
+  let output = normalizeNewlines(`${frontmatter}
+
+${body}
+`);
+  output = runPostRender(plugins, output, personaMetaTyped, target);
+  const validationResults = runValidate(plugins, personaMetaTyped, suiteConfig);
+  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 outputPath = path2__default.default.join(outputDir, outputBasename);
+  const check = config.check ?? false;
+  let written = false;
+  if (!check) {
+    await promises.mkdir(outputDir, { recursive: true });
+    await promises.writeFile(outputPath, output, "utf8");
+    written = true;
+  }
+  return {
+    suite: suiteName,
+    target,
+    personaYamlPath,
+    outputPath,
+    content: output,
+    validationResults,
+    written
+  };
+}
+async function buildSuite(suiteName, suiteConfig, config, plugins, target) {
+  const metaSubdir = suiteConfig.metaSubdir ?? "meta";
+  const sharedYamlPath = path2__default.default.join(suiteConfig.srcDir, metaSubdir, "_shared.yaml");
+  const sharedMeta = await loadRawYaml(sharedYamlPath);
+  let partialsMap = {};
+  if (config.sharedPartialsDir && fs.existsSync(config.sharedPartialsDir)) {
+    partialsMap = { ...partialsMap, ...await loadPartials(config.sharedPartialsDir) };
+  }
+  const partialsSubdir = suiteConfig.partialsSubdir ?? "partials";
+  const suitePartialsDir = path2__default.default.join(suiteConfig.srcDir, partialsSubdir);
+  if (fs.existsSync(suitePartialsDir)) {
+    partialsMap = { ...partialsMap, ...await loadPartials(suitePartialsDir) };
+  }
+  runSuiteInit(plugins, suiteConfig, sharedMeta);
+  const personaYamlPaths = await discoverSuitePersonaYamls(suiteConfig);
+  const results = [];
+  for (const yamlPath of personaYamlPaths) {
+    const result = await buildPersona(
+      yamlPath,
+      suiteName,
+      suiteConfig,
+      sharedMeta,
+      partialsMap,
+      config,
+      plugins,
+      target
+    );
+    results.push(result);
+  }
+  return results;
+}
+async function build(config) {
+  const plugins = config.plugins ?? [];
+  const targets = config.targets ?? ["vscode", "claude-code"];
+  const allResults = [];
+  for (const [suiteName, suiteConfig] of Object.entries(config.suites)) {
+    for (const target of targets) {
+      const suiteResults = await buildSuite(suiteName, suiteConfig, config, plugins, target);
+      allResults.push(...suiteResults);
+    }
+  }
+  const strictFailures = config.strict ? allResults.flatMap(
+    (r) => r.validationResults.filter(
+      (v) => v.severity === "error" || v.severity === "warning"
+    )
+  ) : [];
+  const success = !config.strict || strictFailures.length === 0;
+  const summary = {
+    success,
+    results: allResults,
+    strictFailures,
+    totalBuilt: allResults.length,
+    totalWritten: allResults.filter((r) => r.written).length
+  };
+  if (config.strict && !success) {
+    const messages = strictFailures.map((f) => `[${f.severity}] ${f.message}`).join("\n");
+    throw new Error(
+      `Build failed in strict mode \u2014 ${strictFailures.length} validation issue(s):
+${messages}`
+    );
+  }
+  return summary;
+}
+
+// src/cli.ts
+var _pkgRequire = module$1.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli.cjs', document.baseURI).href)));
+var VERSION = _pkgRequire("../package.json").version;
+var USAGE = `
+@smor/persona-build v${VERSION}
+
+Build AI persona documents from YAML metadata and Markdown content templates.
+
+USAGE
+  persona-build [options]
+
+OPTIONS
+  --config <path>   Path to the build config file.
+                    Supports .js (ESM), .cjs, and .json formats.
+                    Default: persona-build.config.js in the current directory.
+  --check           Render personas but skip writing output files.
+                    Always exits 0 on its own. Combine with --strict to
+                    exit 1 when validators report errors or warnings.
+  --strict          Exit 1 if any validation result has severity 'error'
+                    or 'warning'.
+  --help            Show this help message and exit.
+  --version         Print the package version and exit.
+
+EXAMPLES
+  persona-build                            # Build with default config
+  persona-build --config ./my-config.js   # Build with a custom config
+  persona-build --check                   # CI staleness check (no file writes)
+  persona-build --strict                  # Fail on warnings or errors
+  persona-build --check --strict          # Safe CI check \u2014 no writes + strict
+`.trim();
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  const result = {
+    configPath: void 0,
+    check: false,
+    strict: false,
+    help: false,
+    version: false
+  };
+  let i = 0;
+  while (i < args.length) {
+    const arg = args[i];
+    switch (arg) {
+      case "--help":
+      case "-h":
+        result.help = true;
+        break;
+      case "--version":
+      case "-v":
+        result.version = true;
+        break;
+      case "--check":
+        result.check = true;
+        break;
+      case "--strict":
+        result.strict = true;
+        break;
+      case "--config": {
+        const next = args[i + 1];
+        if (!next || next.startsWith("--")) {
+          console.error("Error: --config requires a path argument.");
+          process.exit(1);
+        }
+        result.configPath = next;
+        i++;
+        break;
+      }
+      default:
+        if (arg.startsWith("--")) {
+          console.warn(`Warning: Unknown flag "${arg}" \u2014 ignored.`);
+        }
+    }
+    i++;
+  }
+  return result;
+}
+function resolveConfigPath(cliValue) {
+  if (cliValue) {
+    const resolved = path2__default.default.resolve(cliValue);
+    if (!fs.existsSync(resolved)) {
+      console.error(`Error: Config file not found: ${resolved}`);
+      process.exit(1);
+    }
+    return resolved;
+  }
+  const candidates = [
+    "persona-build.config.js",
+    "persona-build.config.cjs",
+    "persona-build.config.json"
+  ];
+  for (const name of candidates) {
+    const candidate = path2__default.default.resolve(name);
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  console.error(
+    "Error: No config file found. Create persona-build.config.js in the current directory or pass --config <path>."
+  );
+  process.exit(1);
+}
+async function loadConfig(configPath) {
+  const ext = path2__default.default.extname(configPath).toLowerCase();
+  let rawConfig;
+  if (ext === ".cjs" || ext === ".json") {
+    const require2 = module$1.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli.cjs', document.baseURI).href)));
+    rawConfig = require2(configPath);
+  } else {
+    const fileUrl = url.pathToFileURL(configPath).href;
+    const mod = await import(fileUrl);
+    rawConfig = mod.default ?? mod;
+  }
+  if (!rawConfig || typeof rawConfig !== "object" || Array.isArray(rawConfig)) {
+    console.error(
+      `Error: Config file "${configPath}" must export a plain object (BuildConfig).`
+    );
+    process.exit(1);
+  }
+  const config = rawConfig;
+  if (!config.suites || typeof config.suites !== "object") {
+    console.error(
+      `Error: Config file "${configPath}" must have a "suites" property (record of suite configs).`
+    );
+    process.exit(1);
+  }
+  return config;
+}
+function printSummary(summary, check) {
+  const mode = check ? " [check mode \u2014 no files written]" : "";
+  const status = summary.success ? "\u2713 Build succeeded" : "\u2717 Build failed";
+  console.log(`${status}${mode}`);
+  console.log(`  Personas processed : ${summary.totalBuilt}`);
+  if (!check) {
+    console.log(`  Files written      : ${summary.totalWritten}`);
+  }
+  if (summary.strictFailures.length > 0) {
+    console.log(`
+  Validation failures (${summary.strictFailures.length}):`);
+    for (const f of summary.strictFailures) {
+      console.log(`    [${f.severity}] ${f.message}`);
+    }
+  }
+}
+async function main() {
+  const args = parseArgs(process.argv);
+  if (args.help) {
+    console.log(USAGE);
+    process.exit(0);
+  }
+  if (args.version) {
+    console.log(VERSION);
+    process.exit(0);
+  }
+  const configPath = resolveConfigPath(args.configPath);
+  let config;
+  try {
+    config = await loadConfig(configPath);
+  } catch (err) {
+    console.error(`Error loading config: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+  if (args.check) config.check = true;
+  if (args.strict) config.strict = true;
+  let summary;
+  try {
+    summary = await build(config);
+  } catch (err) {
+    if (err instanceof Error) {
+      console.error(`
+${err.message}`);
+    } else {
+      console.error("Build failed with an unexpected error:", err);
+    }
+    process.exit(1);
+  }
+  printSummary(summary, config.check ?? false);
+  if (!summary.success) {
+    process.exit(1);
+  }
+  process.exit(0);
+}
+main().catch((err) => {
+  console.error("Unexpected error:", err);
+  process.exit(1);
+});
+//# sourceMappingURL=cli.cjs.map
+//# sourceMappingURL=cli.cjs.map