@geminix/gxpm 0.1.0

package/core/converters/converter.ts

@@ -0,0 +1,93 @@
+import type { Converter, ConvertOptions, SkillDocument, SkillFrontmatter, SkillSection } from "../contracts/converter";
+import type { HostConfig } from "../contracts/host";
+import { getHostConfig } from "../../hosts";
+
+function filterFrontmatter(fm: SkillFrontmatter, host: HostConfig): SkillFrontmatter {
+  if (host.frontmatter.mode === "preserve") {
+    return { ...fm };
+  }
+
+  const allowed = new Set(host.frontmatter.keys);
+  const filtered: SkillFrontmatter = {};
+  for (const [key, value] of Object.entries(fm)) {
+    if (allowed.has(key)) {
+      filtered[key] = value;
+    }
+  }
+  return filtered;
+}
+
+function buildPreamble(host: HostConfig): string {
+  const lines: string[] = [];
+  lines.push("## Host Preamble");
+  lines.push("");
+  lines.push(`Target host: ${host.displayName}.`);
+  lines.push("");
+  lines.push("```bash");
+
+  if (host.usesEnvVars) {
+    lines.push('GXPM_ROOT="${GXPM_ROOT:-$PWD}"');
+    lines.push(`GXPM_STATE_DIR="\${GXPM_STATE_DIR:-$GXPM_ROOT/.gxpm}"`);
+    lines.push("export GXPM_ROOT GXPM_STATE_DIR");
+  } else {
+    lines.push('GXPM_ROOT="${GXPM_ROOT:-$PWD}"');
+    lines.push("export GXPM_ROOT");
+  }
+
+  lines.push("```");
+  return lines.join("\n");
+}
+
+function injectPreambleSections(sections: SkillSection[], host: HostConfig): SkillSection[] {
+  // Find the first heading after frontmatter (usually # Title)
+  // Insert preamble right after it, before the next section.
+  const preamble: SkillSection = {
+    type: "raw",
+    content: buildPreamble(host),
+  };
+
+  if (sections.length === 0) {
+    return [preamble];
+  }
+
+  // Insert after the first heading if present, otherwise at top
+  let insertIndex = 0;
+  for (let i = 0; i < sections.length; i++) {
+    if (sections[i].type === "heading") {
+      insertIndex = i + 1;
+      break;
+    }
+  }
+
+  const result = [...sections];
+  result.splice(insertIndex, 0, preamble);
+  return result;
+}
+
+export class HostConverter implements Converter {
+  convert(doc: SkillDocument, options: ConvertOptions): SkillDocument {
+    const host = getHostConfig(options.hostName);
+
+    // 1. Filter frontmatter
+    const frontmatter = filterFrontmatter(doc.frontmatter, host);
+
+    // 2. Inject host preamble into body sections
+    let body = injectPreambleSections(doc.body, host);
+
+    // 3. If templateVars include injected sections (like artifact commands),
+    //    they are already resolved as raw blocks by the template renderer.
+    //    We keep them as-is.
+
+    // 4. Preserve managed blocks (they travel with the document)
+    const managedBlocks = doc.managedBlocks.map((b) => ({ ...b }));
+
+    return {
+      frontmatter,
+      body,
+      managedBlocks,
+      raw: doc.raw,
+    };
+  }
+}
+
+export { filterFrontmatter, buildPreamble };

package/core/converters/index.ts

@@ -0,0 +1,8 @@
+// Multi-platform skill converter pipeline.
+// Re-exports the parser, converter, writer, and template renderer.
+
+export { SkillParser } from "./parser";
+export { HostConverter, filterFrontmatter, buildPreamble } from "./converter";
+export { SkillWriter, serializeFrontmatter, serializeBody, wrapManagedBlock } from "./writer";
+export { renderTemplate, applyTemplateVars } from "./template-renderer";
+export { parseManagedBlocks, mergeManagedBlocks } from "./managed-artifact";

package/core/converters/managed-artifact.ts

@@ -0,0 +1,119 @@
+import type { ManagedBlock } from "../contracts/converter";
+
+const MANAGED_BEGIN_RE = /<!--\s*BEGIN\s+MANAGED:(\S+)\s*-->/g;
+const MANAGED_END_RE = /<!--\s*END\s+MANAGED:(\S+)\s*-->/g;
+
+interface BlockRange {
+  id: string;
+  start: number; // index of BEGIN marker start
+  end: number; // index of END marker end
+  content: string; // content between markers
+}
+
+function findManagedRanges(text: string): BlockRange[] {
+  const ranges: BlockRange[] = [];
+  const beginMatches = Array.from(text.matchAll(MANAGED_BEGIN_RE));
+
+  for (const beginMatch of beginMatches) {
+    const id = beginMatch[1];
+    const startIndex = beginMatch.index;
+    const afterBegin = beginMatch.index + beginMatch[0].length;
+
+    const endRe = new RegExp(`<!--\\s*END\\s+MANAGED:${id}\\s*-->`, "g");
+    endRe.lastIndex = afterBegin;
+    const endMatch = endRe.exec(text);
+    if (!endMatch) {
+      throw new Error(`Unclosed managed block: ${id} at index ${startIndex}`);
+    }
+
+    const content = text.slice(afterBegin, endMatch.index);
+    ranges.push({
+      id,
+      start: startIndex,
+      end: endMatch.index + endMatch[0].length,
+      content,
+    });
+  }
+
+  return ranges;
+}
+
+/**
+ * Parse managed blocks from existing content.
+ */
+export function parseManagedBlocks(text: string): ManagedBlock[] {
+  const ranges = findManagedRanges(text);
+  return ranges.map((r) => ({ id: r.id, content: r.content }));
+}
+
+/**
+ * Merge user-managed blocks from existing content into newly generated content.
+ *
+ * Strategy:
+ * - New managed blocks replace old ones with the same ID.
+ * - Old managed blocks that no longer exist in the new content are removed.
+ * - Non-managed content in the existing file is preserved entirely.
+ *
+ * This is achieved by extracting all managed blocks from the new content,
+ * then overlaying them onto the existing content by ID.
+ *
+ * Actually, simpler: the generated content already has the new managed blocks.
+ * We want to preserve any non-managed parts of the existing content that are
+ * OUTSIDE managed blocks, but since the entire file is generated, this is only
+ * relevant for partial-generation scenarios.
+ *
+ * For SKILL.md generation, the simplest safe approach:
+ * - Extract old managed blocks from existing.
+ * - Extract new managed blocks from generated.
+ * - Build a merged document where:
+ *   - The non-managed skeleton comes from the GENERATED content (source of truth)
+ *   - Any managed block present in BOTH old and new keeps the NEW version
+ *   - Any managed block ONLY in old is dropped (it was generated before)
+ *   - Any managed block ONLY in new is added
+ *
+ * If the user wants to preserve arbitrary non-managed edits, they should not
+ * edit an AUTO-GENERATED file. The managed-block system is for allowing
+ * intentional extension points.
+ */
+export function mergeManagedBlocks(existingContent: string, generatedContent: string): string {
+  const existingRanges = findManagedRanges(existingContent);
+  const generatedRanges = findManagedRanges(generatedContent);
+
+  if (existingRanges.length === 0) {
+    // No existing managed blocks: return generated as-is
+    return generatedContent;
+  }
+
+  if (generatedRanges.length === 0) {
+    // Generated has no managed blocks: return generated as-is
+    return generatedContent;
+  }
+
+  // Build a map of generated blocks by ID
+  const generatedById = new Map<string, BlockRange>();
+  for (const r of generatedRanges) {
+    generatedById.set(r.id, r);
+  }
+
+  // Start from the generated content, but for each managed block that also
+  // existed in the old content, we use the NEW content (source of truth).
+  // For any non-managed user edits between old blocks... we can't safely preserve
+  // them because the skeleton may have changed. So we just return generated.
+
+  // However, if the user added custom content OUTSIDE managed blocks in the old
+  // file, we might want to append it. That's too complex and error-prone.
+  // The contract is: edit .tmpl, not .md.
+
+  // One useful feature: if the generated block has a special sentinel
+  // "<!-- MANAGED-PRESERVE -->", we could keep old content. But let's keep it simple.
+
+  return generatedContent;
+}
+
+/**
+ * A stricter merge that preserves user content outside managed blocks
+ * only if the generated skeleton hasn't changed. This is a future enhancement.
+ */
+export function mergeManagedBlocksStrict(existingContent: string, generatedContent: string): string {
+  return mergeManagedBlocks(existingContent, generatedContent);
+}

package/core/converters/parser.ts

@@ -0,0 +1,159 @@
+import type { ManagedBlock, ParseOptions, Parser, SkillDocument, SkillFrontmatter, SkillSection } from "../contracts/converter";
+
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?/;
+const MANAGED_BEGIN_RE = /<!--\s*BEGIN\s+MANAGED:(\S+)\s*-->/gi;
+
+function parseFrontmatter(source: string): { frontmatter: SkillFrontmatter; bodyStart: number } {
+  const match = source.match(FRONTMATTER_RE);
+  if (!match) {
+    return { frontmatter: {}, bodyStart: 0 };
+  }
+
+  const fm: SkillFrontmatter = {};
+  const lines = match[1].split("\n");
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const colonIndex = trimmed.indexOf(":");
+    if (colonIndex < 0) continue;
+    const key = trimmed.slice(0, colonIndex).trim();
+    const rawValue = trimmed.slice(colonIndex + 1).trim();
+    if (rawValue === "true") {
+      fm[key] = true;
+    } else if (rawValue === "false") {
+      fm[key] = false;
+    } else if (/^-?\d+$/.test(rawValue)) {
+      fm[key] = Number(rawValue);
+    } else {
+      fm[key] = rawValue;
+    }
+  }
+
+  return { frontmatter: fm, bodyStart: match[0].length };
+}
+
+function splitSections(body: string): SkillSection[] {
+  const sections: SkillSection[] = [];
+  const lines = body.split("\n");
+  let buffer: string[] = [];
+  let inCodeBlock = false;
+  let codeLang = "";
+
+  function flush() {
+    if (buffer.length === 0) return;
+    const content = buffer.join("\n");
+    if (content.trim().length === 0) {
+      buffer = [];
+      return;
+    }
+
+    const firstLine = buffer[0];
+    if (firstLine.startsWith("#")) {
+      const level = firstLine.match(/^#+/)?.[0].length ?? 1;
+      sections.push({ type: "heading", content, level });
+    } else if (firstLine.startsWith("```")) {
+      sections.push({ type: "code", content, lang: codeLang });
+    } else if (firstLine.startsWith(">")) {
+      sections.push({ type: "blockquote", content });
+    } else if (/^\s*[-*+]|^\s*\d+\./.test(firstLine)) {
+      sections.push({ type: "list", content });
+    } else if (firstLine.startsWith("<") || firstLine.startsWith("<!--")) {
+      sections.push({ type: "html", content });
+    } else {
+      sections.push({ type: "paragraph", content });
+    }
+    buffer = [];
+  }
+
+  for (const line of lines) {
+    if (line.startsWith("```")) {
+      if (inCodeBlock) {
+        buffer.push(line);
+        flush();
+        inCodeBlock = false;
+        codeLang = "";
+        continue;
+      }
+      flush();
+      inCodeBlock = true;
+      codeLang = line.slice(3).trim();
+      buffer.push(line);
+      continue;
+    }
+
+    if (inCodeBlock) {
+      buffer.push(line);
+      continue;
+    }
+
+    if (line.startsWith("#")) {
+      flush();
+      buffer.push(line);
+      continue;
+    }
+
+    if (line.trim() === "") {
+      flush();
+      continue;
+    }
+
+    buffer.push(line);
+  }
+
+  flush();
+  return sections;
+}
+
+function extractManagedBlocks(body: string): { blocks: ManagedBlock[]; cleanedBody: string } {
+  const blocks: ManagedBlock[] = [];
+  let cleaned = body;
+
+  let offset = 0;
+  while (true) {
+    const beginMatch = MANAGED_BEGIN_RE.exec(body);
+    if (!beginMatch) break;
+
+    const blockId = beginMatch[1];
+    const startIndex = beginMatch.index;
+    const endRe = new RegExp(`<!--\\s*END\\s+MANAGED:${blockId}\\s*-->`, "i");
+    const afterBegin = body.slice(startIndex + beginMatch[0].length);
+    const endMatch = endRe.exec(afterBegin);
+    if (!endMatch) {
+      throw new Error(`Unclosed managed block: ${blockId} at index ${startIndex}`);
+    }
+
+    const contentStart = startIndex + beginMatch[0].length;
+    const contentEnd = contentStart + endMatch.index;
+    const content = body.slice(contentStart, contentEnd);
+    blocks.push({ id: blockId, content });
+
+    const blockEnd = contentEnd + endMatch[0].length;
+    cleaned = cleaned.slice(0, startIndex - offset) + cleaned.slice(blockEnd - offset);
+    offset += blockEnd - startIndex;
+  }
+
+  return { blocks, cleanedBody: cleaned };
+}
+
+export class SkillParser implements Parser {
+  parse(source: string, options?: ParseOptions): SkillDocument {
+    const { frontmatter, bodyStart } = parseFrontmatter(source);
+    let body = source.slice(bodyStart);
+
+    let managedBlocks: ManagedBlock[] = [];
+    if (options?.extractManagedBlocks) {
+      const extracted = extractManagedBlocks(body);
+      managedBlocks = extracted.blocks;
+      body = extracted.cleanedBody;
+    }
+
+    const sections = splitSections(body);
+
+    return {
+      frontmatter,
+      body: sections,
+      managedBlocks,
+      raw: source,
+    };
+  }
+}

package/core/converters/template-renderer.ts

@@ -0,0 +1,35 @@
+import type { SkillDocument } from "../contracts/converter";
+
+export interface TemplateVars {
+  [key: string]: string | Record<string, string>;
+}
+
+/**
+ * Render {{VAR}} and {{REFERENCE:name}} placeholders in a raw skill source.
+ * This operates on raw strings BEFORE parsing, preserving the existing
+ * gen-skill-docs behavior but extracted into a dedicated module.
+ */
+export function renderTemplate(source: string, vars: TemplateVars): string {
+  let result = source;
+  for (const [key, value] of Object.entries(vars)) {
+    if (typeof value === "string") {
+      result = result.replaceAll(`{{${key}}}`, value);
+    } else if (key === "references" && typeof value === "object" && value !== null) {
+      for (const [refName, refContent] of Object.entries(value)) {
+        result = result.replaceAll(`{{REFERENCE:${refName}}}`, refContent as string);
+      }
+    }
+  }
+  return result;
+}
+
+/**
+ * Apply template variables to a SkillDocument by re-rendering its raw source.
+ * This is a convenience for the existing pipeline where template vars are
+ * resolved before parsing.
+ */
+export function applyTemplateVars(doc: SkillDocument, vars: TemplateVars): SkillDocument {
+  const rendered = renderTemplate(doc.raw, vars);
+  // Return a document with updated raw; caller can re-parse if needed.
+  return { ...doc, raw: rendered };
+}

package/core/converters/writer.ts

@@ -0,0 +1,61 @@
+import type { ManagedBlock, SkillDocument, SkillFrontmatter, SkillSection, TargetWriter, WriteOptions } from "../contracts/converter";
+import { mergeManagedBlocks } from "./managed-artifact";
+
+function serializeFrontmatter(fm: SkillFrontmatter): string {
+  const entries = Object.entries(fm).filter(([, v]) => v !== undefined);
+  if (entries.length === 0) return "";
+  const lines = entries.map(([k, v]) => {
+    if (typeof v === "boolean") return `${k}: ${v}`;
+    if (typeof v === "number") return `${k}: ${v}`;
+    return `${k}: ${v}`;
+  });
+  return `---\n${lines.join("\n")}\n---\n`;
+}
+
+function serializeSection(section: SkillSection): string {
+  return section.content;
+}
+
+function serializeBody(sections: SkillSection[]): string {
+  return sections.map(serializeSection).join("\n\n");
+}
+
+function wrapManagedBlock(block: ManagedBlock): string {
+  return `<!-- BEGIN MANAGED:${block.id} -->\n${block.content}\n<!-- END MANAGED:${block.id} -->`;
+}
+
+export class SkillWriter implements TargetWriter {
+  write(doc: SkillDocument, options?: WriteOptions): string {
+    // 1. Build generated content
+    const fm = serializeFrontmatter(doc.frontmatter);
+    const body = serializeBody(doc.body);
+
+    let managedBody = body;
+    if (doc.managedBlocks.length > 0) {
+      const blocksText = doc.managedBlocks.map(wrapManagedBlock).join("\n\n");
+      managedBody = `${body}\n\n${blocksText}`;
+    }
+
+    let generated = fm ? `${fm}\n${managedBody}` : managedBody;
+
+    if (options?.generatedMark) {
+      const fmMatch = generated.match(/^---\n[\s\S]*?\n---\n?/);
+      if (fmMatch) {
+        const head = fmMatch[0].trimEnd();
+        const rest = generated.slice(fmMatch[0].length).replace(/^\n+/, "");
+        generated = `${head}\n${options.generatedMark}\n\n${rest}`;
+      } else {
+        generated = `${options.generatedMark}\n\n${generated}`;
+      }
+    }
+
+    // 2. If existing content provided, merge managed blocks
+    if (options?.existingContent) {
+      generated = mergeManagedBlocks(options.existingContent, generated);
+    }
+
+    return generated;
+  }
+}
+
+export { serializeFrontmatter, serializeBody, wrapManagedBlock };