/*
This module provides HTML comment hints embedded in generated documentation
and plugin artifacts to mark them as machine-generated.
*/

import type { CliProgram } from "../core/types.ts";

/** YAML frontmatter block at the start of markdown files. */
export const MARKDOWN_FRONTMATTER_RE = /^---\r?\n[\s\S]*?\r?\n---\r?\n/;

/** HTML comment marking argsbarg-generated markdown. */
export function generatedFileHtmlComment(source: string): string {
  return `<!-- Generated by ${source}; do not edit. -->\n\n`;
}

/** Prepends a hint, or inserts after frontmatter when requested. */
export function insertGeneratedHint(content: string, hint: string, options?: { afterFrontmatter?: boolean }): string {
  if (options?.afterFrontmatter) {
    const match = content.match(MARKDOWN_FRONTMATTER_RE);
    if (match) {
      return `${match[0]}${hint}${content.slice(match[0].length)}`;
    }
  }
  return `${hint}${content}`;
}

/** Hint for `mcp bundle` plugin skill output. */
export function skillBundleHint(program: CliProgram): string {
  return generatedFileHtmlComment(`${program.key} mcp bundle`);
}

/** Applies bundle hint to plugin SKILL.md (after frontmatter). */
export function applyPluginSkillHint(program: CliProgram, skillMd: string): string {
  return insertGeneratedHint(skillMd, skillBundleHint(program), { afterFrontmatter: true });
}