OmniRoute/tests/unit/agentSkills-generator.test.ts

/**
 * agentSkills-generator.test.ts
 *
 * Tests for src/lib/agentSkills/generator.ts
 *
 * All tests use a temporary directory so they never touch the real `skills/` folder.
 * Uses Node.js native test runner.
 */

import test from "node:test";
import assert from "node:assert/strict";
import fs from "node:fs";
import path from "node:path";
import os from "node:os";

// ── Dynamic imports (tsx/esm resolves TS imports) ────────────────────────────

const { generateAgentSkills, buildSkillMarkdown, __testing } = await import(
  "../../src/lib/agentSkills/generator.ts"
);

const { getCatalog, refreshCatalog } = await import(
  "../../src/lib/agentSkills/catalog.ts"
);

// ── Helpers ──────────────────────────────────────────────────────────────────

/** Creates an isolated tmp directory and returns its path. */
function mkTmpDir(): string {
  return fs.mkdtempSync(path.join(os.tmpdir(), "agent-skills-gen-test-"));
}

/** Cleanup a tmp directory. */
function rmTmpDir(dir: string): void {
  try {
    fs.rmSync(dir, { recursive: true, force: true });
  } catch {
    // best-effort cleanup
  }
}

/**
 * Builds a minimal sources object for tests that don't need real parsers.
 */
function emptySources() {
  return {
    openapi: { paths: new Map(), areas: new Map() },
    cliRegistry: { commands: new Map(), families: new Map() },
  };
}

// ── Dry-run: no writes ────────────────────────────────────────────────────────

test("dry-run (default) returns report without writing any files", async () => {
  const tmpDir = mkTmpDir();
  try {
    refreshCatalog();
    const report = await generateAgentSkills({
      dryRun: true,
      prune: false,
      outputDir: tmpDir,
    });

    // All 46 skills (45 canonical + ponytail external, #9058) should appear as
    // generated (would-write) since dir is empty
    assert.equal(
      report.generated.length + report.unchanged.length,
      46,
      `Expected 46 total (generated+unchanged), got generated=${report.generated.length} unchanged=${report.unchanged.length}`,
    );
    assert.equal(report.errors.length, 0, `Unexpected errors: ${JSON.stringify(report.errors)}`);

    // No files written
    const entries = fs.readdirSync(tmpDir);
    assert.equal(
      entries.length,
      0,
      `Dry-run wrote ${entries.length} entries to ${tmpDir}: ${entries.join(", ")}`,
    );
  } finally {
    rmTmpDir(tmpDir);
  }
});

test("dry-run generates report with 46 total (generated+unchanged)", async () => {
  const tmpDir = mkTmpDir();
  try {
    refreshCatalog();
    const report = await generateAgentSkills({
      dryRun: true,
      prune: false,
      outputDir: tmpDir,
    });
    const total = report.generated.length + report.unchanged.length;
    assert.equal(total, 46);
  } finally {
    rmTmpDir(tmpDir);
  }
});

// ── Apply: writes SKILL.md ─────────────────────────────────────────────────────

test("apply mode writes SKILL.md with valid frontmatter for omni-providers", async () => {
  const tmpDir = mkTmpDir();
  try {
    refreshCatalog();
    const report = await generateAgentSkills({
      dryRun: false,
      prune: false,
      outputDir: tmpDir,
      onlyIds: ["omni-providers"],
    });

    assert.equal(report.errors.length, 0, `Errors: ${JSON.stringify(report.errors)}`);
    assert.equal(report.generated.length, 1);
    assert.equal(report.generated[0], "omni-providers");

    const skillFile = path.join(tmpDir, "omni-providers", "SKILL.md");
    assert.ok(fs.existsSync(skillFile), `SKILL.md not found at ${skillFile}`);

    const content = fs.readFileSync(skillFile, "utf-8");

    // Frontmatter present
    assert.ok(content.startsWith("---\n"), "Missing frontmatter start");
    assert.ok(content.includes("name: omni-providers"), "Missing name in frontmatter");
    assert.ok(content.includes("---\n"), "Missing frontmatter end");

    // Generated comment present
    assert.ok(
      content.includes("<!-- generated by src/lib/agentSkills/generator.ts"),
      "Missing generated comment",
    );
  } finally {
    rmTmpDir(tmpDir);
  }
});

test("apply mode writes all 46 SKILL.md files when no onlyIds filter", async () => {
  const tmpDir = mkTmpDir();
  try {
    refreshCatalog();
    const report = await generateAgentSkills({
      dryRun: false,
      prune: false,
      outputDir: tmpDir,
    });

    assert.equal(report.errors.length, 0, `Errors: ${JSON.stringify(report.errors)}`);
    assert.equal(report.generated.length, 46);

    // Verify all dirs exist
    const catalog = getCatalog();
    for (const skill of catalog) {
      const skillFile = path.join(tmpDir, skill.id, "SKILL.md");
      assert.ok(fs.existsSync(skillFile), `Missing SKILL.md for ${skill.id}`);
    }
  } finally {
    rmTmpDir(tmpDir);
  }
});

test("apply mode writes SKILL.md for a CLI skill with correct structure", async () => {
  const tmpDir = mkTmpDir();
  try {
    refreshCatalog();
    const report = await generateAgentSkills({
      dryRun: false,
      prune: false,
      outputDir: tmpDir,
      onlyIds: ["cli-serve"],
    });

    assert.equal(report.errors.length, 0);
    assert.equal(report.generated.length, 1);

    const content = fs.readFileSync(path.join(tmpDir, "cli-serve", "SKILL.md"), "utf-8");
    assert.ok(content.includes("name: cli-serve"), "Missing name in frontmatter");
    assert.ok(content.includes("## Overview"), "Missing Overview section");
    assert.ok(content.includes("## Quick install"), "Missing Quick install section");
    assert.ok(content.includes("## Subcommands"), "Missing Subcommands section");
  } finally {
    rmTmpDir(tmpDir);
  }
});

test("apply mode writes SKILL.md for an API skill with correct sections", async () => {
  const tmpDir = mkTmpDir();
  try {
    refreshCatalog();
    const report = await generateAgentSkills({
      dryRun: false,
      prune: false,
      outputDir: tmpDir,
      onlyIds: ["omni-auth"],
    });

    assert.equal(report.errors.length, 0);
    const content = fs.readFileSync(path.join(tmpDir, "omni-auth", "SKILL.md"), "utf-8");
    assert.ok(content.includes("## Overview"), "Missing Overview section");
    assert.ok(content.includes("## Authentication"), "Missing Authentication section");
    assert.ok(content.includes("## Endpoints"), "Missing endpoints section");
    assert.ok(content.includes("## Payloads"), "Missing payloads section");
  } finally {
    rmTmpDir(tmpDir);
  }
});

// ── Idempotency ───────────────────────────────────────────────────────────────

test("idempotency: second apply run reports 0 generated, all unchanged", async () => {
  const tmpDir = mkTmpDir();
  try {
    refreshCatalog();

    // First run: apply
    const report1 = await generateAgentSkills({
      dryRun: false,
      prune: false,
      outputDir: tmpDir,
      onlyIds: ["omni-providers", "cli-serve"],
    });
    assert.equal(report1.generated.length, 2, "First run should generate 2 skills");

    // Second run: same options
    const report2 = await generateAgentSkills({
      dryRun: false,
      prune: false,
      outputDir: tmpDir,
      onlyIds: ["omni-providers", "cli-serve"],
    });
    assert.equal(report2.generated.length, 0, "Second run should generate 0 (already up-to-date)");
    assert.equal(report2.unchanged.length, 2, "Second run should report 2 unchanged");
  } finally {
    rmTmpDir(tmpDir);
  }
});

// ── Prune: detect orphans ─────────────────────────────────────────────────────

test("prune dry-run detects orphan dirs without deleting them", async () => {
  const tmpDir = mkTmpDir();
  try {
    refreshCatalog();

    // Create an orphan directory (not in catalog)
    const orphanDir = path.join(tmpDir, "old-orphan-skill");
    fs.mkdirSync(orphanDir, { recursive: true });
    fs.writeFileSync(path.join(orphanDir, "SKILL.md"), "# Old\n");

    const report = await generateAgentSkills({
      dryRun: true,
      prune: true,
      outputDir: tmpDir,
    });

    assert.ok(report.orphansDetected.includes("old-orphan-skill"), "Orphan not detected");
    assert.equal(report.pruned.length, 0, "Nothing should be pruned in dry-run");

    // Orphan dir still exists
    assert.ok(fs.existsSync(orphanDir), "Orphan dir was deleted in dry-run (should not happen)");
  } finally {
    rmTmpDir(tmpDir);
  }
});

test("prune apply mode deletes orphan dirs", async () => {
  const tmpDir = mkTmpDir();
  try {
    refreshCatalog();

    // Create an orphan directory
    const orphanDir = path.join(tmpDir, "old-orphan-to-delete");
    fs.mkdirSync(orphanDir, { recursive: true });
    fs.writeFileSync(path.join(orphanDir, "SKILL.md"), "# Old\n");

    const report = await generateAgentSkills({
      dryRun: false,
      prune: true,
      outputDir: tmpDir,
    });

    assert.ok(report.orphansDetected.includes("old-orphan-to-delete"), "Orphan not detected");
    assert.ok(report.pruned.includes("old-orphan-to-delete"), "Orphan not pruned");

    // Orphan dir should be gone
    assert.ok(
      !fs.existsSync(orphanDir),
      "Orphan dir was NOT deleted in apply+prune mode",
    );
  } finally {
    rmTmpDir(tmpDir);
  }
});

test("prune does not delete catalog skill dirs", async () => {
  const tmpDir = mkTmpDir();
  try {
    refreshCatalog();

    // Pre-create a valid skill dir
    const validDir = path.join(tmpDir, "omni-providers");
    fs.mkdirSync(validDir, { recursive: true });
    fs.writeFileSync(path.join(validDir, "SKILL.md"), "# Existing\n");

    // Add an orphan
    const orphanDir = path.join(tmpDir, "orphan-xyz");
    fs.mkdirSync(orphanDir, { recursive: true });

    const report = await generateAgentSkills({
      dryRun: false,
      prune: true,
      outputDir: tmpDir,
      onlyIds: [],
    });

    // omni-providers should not be in orphansDetected
    assert.ok(
      !report.orphansDetected.includes("omni-providers"),
      "Valid skill mistakenly flagged as orphan",
    );
    assert.ok(report.orphansDetected.includes("orphan-xyz"), "Orphan not detected");
  } finally {
    rmTmpDir(tmpDir);
  }
});

// ── Marker preservation ───────────────────────────────────────────────────────

test("marker preservation: custom block survives regeneration", async () => {
  const tmpDir = mkTmpDir();
  try {
    refreshCatalog();

    // First apply to create the file
    await generateAgentSkills({
      dryRun: false,
      prune: false,
      outputDir: tmpDir,
      onlyIds: ["omni-providers"],
    });

    const skillFile = path.join(tmpDir, "omni-providers", "SKILL.md");
    const originalContent = fs.readFileSync(skillFile, "utf-8");

    // Inject a custom block
    const customBlock = "<!-- skill:custom-start -->\nMy custom content here.\n<!-- skill:custom-end -->";
    const contentWithCustom = originalContent + "\n" + customBlock + "\n";
    fs.writeFileSync(skillFile, contentWithCustom, "utf-8");

    // Re-run generator — file is now different (custom block changed content)
    const report2 = await generateAgentSkills({
      dryRun: false,
      prune: false,
      outputDir: tmpDir,
      onlyIds: ["omni-providers"],
    });

    assert.equal(
      report2.errors.length,
      0,
      `Errors: ${JSON.stringify(report2.errors)}`,
    );

    const newContent = fs.readFileSync(skillFile, "utf-8");

    // Custom block should still be present
    assert.ok(
      newContent.includes("My custom content here."),
      "Custom content was lost during regeneration",
    );
    assert.ok(
      newContent.includes("<!-- skill:custom-start -->"),
      "Custom start marker missing",
    );
    assert.ok(
      newContent.includes("<!-- skill:custom-end -->"),
      "Custom end marker missing",
    );
  } finally {
    rmTmpDir(tmpDir);
  }
});

// ── buildSkillMarkdown ─────────────────────────────────────────────────────────

test("buildSkillMarkdown returns valid frontmatter + body for omni-providers", () => {
  refreshCatalog();
  const sources = emptySources();
  const result = buildSkillMarkdown("omni-providers", sources);

  assert.ok(typeof result.frontmatter === "object", "frontmatter must be an object");
  assert.equal(result.frontmatter.name, "omni-providers");
  assert.ok(result.frontmatter.description.length > 0, "description must be non-empty");
  assert.ok(typeof result.body === "string" && result.body.length > 0, "body must be a non-empty string");
});

test("buildSkillMarkdown body has no erroneously escaped characters", () => {
  refreshCatalog();
  const sources = emptySources();

  // Test several skills
  const testIds = ["omni-providers", "cli-serve", "omni-auth", "cli-health"];
  for (const id of testIds) {
    const result = buildSkillMarkdown(id, sources);

    // Check for common escape errors: \\n in rendered text, &amp;, &lt;, &gt;
    assert.ok(
      !result.body.includes("\\\\n"),
      `Skill ${id}: body contains \\\\n (double-escaped newline)`,
    );
    assert.ok(
      !result.body.includes("&amp;"),
      `Skill ${id}: body contains HTML entity &amp;`,
    );
    assert.ok(
      !result.body.includes("&lt;"),
      `Skill ${id}: body contains HTML entity &lt;`,
    );
    assert.ok(
      !result.body.includes("&gt;"),
      `Skill ${id}: body contains HTML entity &gt;`,
    );
  }
});

test("buildSkillMarkdown throws for unknown skillId", () => {
  refreshCatalog();
  const sources = emptySources();

  assert.throws(
    () => buildSkillMarkdown("non-existent-skill", sources),
    /non-existent-skill/,
    "Should throw with skill ID in message",
  );
});

test("buildSkillMarkdown API skill body contains expected sections", () => {
  refreshCatalog();
  const sources = emptySources();
  const result = buildSkillMarkdown("omni-cache", sources);

  assert.ok(result.body.includes("## Overview"), "Missing Overview section");
  assert.ok(result.body.includes("## Authentication"), "Missing Authentication section");
  assert.ok(result.body.includes("## Endpoints"), "Missing Endpoints section");
  assert.ok(result.body.includes("## Payloads"), "Missing Payloads section");
});

test("buildSkillMarkdown CLI skill body contains expected sections", () => {
  refreshCatalog();
  const sources = emptySources();
  const result = buildSkillMarkdown("cli-health", sources);

  assert.ok(result.body.includes("## Overview"), "Missing Overview section");
  assert.ok(result.body.includes("## Quick install"), "Missing Quick install section");
  assert.ok(result.body.includes("## Subcommands"), "Missing Subcommands section");
});

test("buildSkillMarkdown description is at most 2000 chars", () => {
  refreshCatalog();
  const catalog = getCatalog();
  const sources = emptySources();

  for (const skill of catalog) {
    const result = buildSkillMarkdown(skill.id, sources);
    assert.ok(
      result.frontmatter.description.length <= 2000,
      `Skill ${skill.id}: description too long (${result.frontmatter.description.length} > 2000)`,
    );
  }
});

// ── onlyIds filter ────────────────────────────────────────────────────────────

test("onlyIds filter limits generation to specified IDs", async () => {
  const tmpDir = mkTmpDir();
  try {
    refreshCatalog();
    const report = await generateAgentSkills({
      dryRun: false,
      prune: false,
      outputDir: tmpDir,
      onlyIds: ["omni-providers", "cli-serve"],
    });

    assert.equal(report.generated.length, 2);
    assert.ok(report.generated.includes("omni-providers"));
    assert.ok(report.generated.includes("cli-serve"));

    // Only 2 dirs created
    const entries = fs.readdirSync(tmpDir);
    assert.equal(entries.length, 2, `Expected 2 dirs, got: ${entries.join(", ")}`);
  } finally {
    rmTmpDir(tmpDir);
  }
});

// ── Generated comment ─────────────────────────────────────────────────────────

test("generated SKILL.md contains the mandatory generated comment", async () => {
  const tmpDir = mkTmpDir();
  try {
    refreshCatalog();
    await generateAgentSkills({
      dryRun: false,
      prune: false,
      outputDir: tmpDir,
      onlyIds: ["omni-providers"],
    });

    const content = fs.readFileSync(path.join(tmpDir, "omni-providers", "SKILL.md"), "utf-8");
    assert.ok(
      content.includes("<!-- generated by src/lib/agentSkills/generator.ts; manual edits will be overwritten -->"),
      "Missing mandatory generated comment",
    );
  } finally {
    rmTmpDir(tmpDir);
  }
});

// ── Report shape ──────────────────────────────────────────────────────────────

test("report has all required fields with correct types", async () => {
  const tmpDir = mkTmpDir();
  try {
    refreshCatalog();
    const report = await generateAgentSkills({
      dryRun: true,
      prune: false,
      outputDir: tmpDir,
    });

    assert.ok(Array.isArray(report.generated), "generated must be an array");
    assert.ok(Array.isArray(report.unchanged), "unchanged must be an array");
    assert.ok(Array.isArray(report.pruned), "pruned must be an array");
    assert.ok(Array.isArray(report.orphansDetected), "orphansDetected must be an array");
    assert.ok(Array.isArray(report.errors), "errors must be an array");
  } finally {
    rmTmpDir(tmpDir);
  }
});

// ── serializeFrontmatter escaping (js/incomplete-sanitization regression) ──────

test("serializeFrontmatter escapes backslashes before quotes → valid round-trippable YAML", async () => {
  const { parse } = await import("yaml");
  const fm = {
    name: 'name with "quote"',
    description: 'line1\nline2: path C:\\Users\\x with "q" and trailing \\',
  };
  const block = __testing.serializeFrontmatter(fm);
  // Strip the --- fences and parse the inner YAML; broken escaping (e.g. an
  // unescaped trailing backslash that escapes the closing quote) would throw or
  // corrupt the value here.
  const inner = block.replace(/^---\n/, "").replace(/---\n?$/, "");
  const parsed = parse(inner) as { name: string; description: string };
  assert.equal(parsed.name, fm.name, "name must round-trip through YAML unchanged");
  assert.equal(
    parsed.description,
    fm.description,
    "description with backslashes + quotes + newline must round-trip exactly"
  );
});