@baybreezy/docd 0.0.1

package/modules/prose-component-meta.ts

@@ -0,0 +1,150 @@
+import { resolve as resolvePath } from "node:path";
+
+import { addTemplate, createResolver, defineNuxtModule, logger, updateTemplates } from "@nuxt/kit";
+
+import {
+  appendComponentApiBlocks,
+  builtInComponentApiItems,
+  isBuiltInProseDocFile,
+  projectComponentApiConfig,
+  warnForMissingComponentPaths,
+  withAutoTitles,
+} from "../utils/component-api-content";
+import { discoverProjectComponentApiPaths } from "../utils/component-api-discovery";
+import {
+  EMPTY_PROSE_COMPONENT_META_MANIFEST,
+  generateProseComponentMeta,
+  readGeneratedProseComponentMeta,
+  resolveProseComponentPaths,
+} from "../utils/generate-prose-component-meta";
+
+const log = logger.withTag("Docd");
+
+function normalizeFsPath(path: string) {
+  return path.replace(/\\/g, "/");
+}
+
+export default defineNuxtModule({
+  meta: {
+    name: "docd:prose-component-meta",
+  },
+  async setup(_, nuxt) {
+    const resolver = createResolver(import.meta.url);
+    const layerRoot = resolver.resolve("..");
+    const { componentsDir, outputFile, cacheDir } = resolveProseComponentPaths({
+      rootDir: nuxt.options.rootDir,
+      layerRoot,
+    });
+    const contentDir = resolvePath(nuxt.options.rootDir, "content");
+    let watchedProjectComponentFiles = new Set<string>();
+
+    let manifest = readGeneratedProseComponentMeta(outputFile);
+    if (!Object.keys(manifest.components).length) {
+      manifest = EMPTY_PROSE_COMPONENT_META_MANIFEST;
+    }
+
+    const manifestTemplate = addTemplate({
+      filename: "docd/prose-component-meta.mjs",
+      write: true,
+      getContents: () => `export default ${JSON.stringify(manifest, null, 2)};\n`,
+    });
+
+    async function regenerate() {
+      const discovery = await discoverProjectComponentApiPaths({
+        rootDir: nuxt.options.rootDir,
+        layerRoot,
+        contentDir,
+      });
+
+      watchedProjectComponentFiles = new Set(
+        discovery.components.map((component) => normalizeFsPath(component.absolutePath))
+      );
+
+      manifest = await generateProseComponentMeta({
+        rootDir: nuxt.options.rootDir,
+        layerRoot,
+        componentsDir,
+        outputFile,
+        cache: true,
+        cacheDir,
+        additionalComponents: discovery.components,
+      });
+
+      await updateTemplates({
+        filter: (template) => template.filename === manifestTemplate.filename,
+      });
+    }
+
+    await regenerate();
+
+    nuxt.hook("content:file:afterParse", async (event) => {
+      const context = {
+        rootDir: nuxt.options.rootDir,
+        layerRoot,
+        warn: (message: string) => log.warn(message),
+      };
+
+      if (isBuiltInProseDocFile(event.content)) {
+        const { heading, items, explicit } = builtInComponentApiItems(event.content, context);
+
+        if (!items.length) {
+          return;
+        }
+
+        if (explicit) {
+          warnForMissingComponentPaths(event.content, items, context);
+        }
+
+        event.content = await appendComponentApiBlocks(event.content, items, heading);
+        return;
+      }
+
+      const componentApi = projectComponentApiConfig(event.content);
+
+      if (!componentApi || componentApi === false) {
+        return;
+      }
+
+      if (!componentApi.hasExplicitComponents) {
+        log.warn(
+          `The componentApi config in ${typeof event.content.id === "string" ? event.content.id : "this page"} must declare a path or components array.`
+        );
+        return;
+      }
+
+      const items = withAutoTitles(componentApi.components);
+      warnForMissingComponentPaths(event.content, items, context);
+      event.content = await appendComponentApiBlocks(event.content, items, componentApi.heading);
+    });
+
+    nuxt.hook("builder:watch", async (_event, changedPath) => {
+      const normalizedComponentsDir = normalizeFsPath(componentsDir);
+      const normalizedContentDir = normalizeFsPath(contentDir);
+      const candidates = [
+        normalizeFsPath(changedPath),
+        normalizeFsPath(resolvePath(nuxt.options.rootDir, changedPath)),
+        normalizeFsPath(resolvePath(layerRoot, changedPath)),
+      ];
+
+      const matchesProseComponent = candidates.some(
+        (candidate) => candidate.endsWith(".vue") && candidate.startsWith(normalizedComponentsDir)
+      );
+      const matchesWatchedProjectComponent = candidates.some((candidate) =>
+        watchedProjectComponentFiles.has(candidate)
+      );
+      const matchesContentFrontmatter = candidates.some(
+        (candidate) => candidate.endsWith(".md") && candidate.startsWith(normalizedContentDir)
+      );
+
+      if (!matchesProseComponent && !matchesWatchedProjectComponent && !matchesContentFrontmatter) {
+        return;
+      }
+
+      try {
+        await regenerate();
+      } catch (error) {
+        log.error(`Failed to refresh prose component metadata: ${String(error)}`);
+      }
+    });
+  },
+});

package/modules/routing.ts

@@ -0,0 +1,22 @@
+import { createResolver, defineNuxtModule, extendPages } from "@nuxt/kit";
+
+import { landingPageExists } from "../utils/pages";
+
+export default defineNuxtModule({
+  meta: {
+    name: "docd:routing",
+  },
+  setup(_options, nuxt) {
+    const { resolve } = createResolver(import.meta.url);
+
+    if (!landingPageExists(nuxt.options.rootDir)) {
+      extendPages((pages) => {
+        pages.push({
+          name: "index",
+          path: "/",
+          file: resolve("../app/templates/landing.vue"),
+        });
+      });
+    }
+  },
+});

package/modules/skills/index.ts

@@ -0,0 +1,167 @@
+import { existsSync } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import {
+  addPrerenderRoutes,
+  addServerHandler,
+  createResolver,
+  defineNuxtModule,
+  logger,
+} from "@nuxt/kit";
+import { defu } from "defu";
+import type { NitroConfig } from "nitropack";
+import { parse as parseYaml } from "yaml";
+
+interface SkillEntry {
+  name: string;
+  description: string;
+  files: string[];
+}
+
+export interface SkillsModuleOptions {
+  dir?: string;
+}
+
+const SKILL_NAME_REGEX = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+const MAX_NAME_LENGTH = 64;
+
+const log = logger.withTag("Docd");
+
+const defaults: Required<SkillsModuleOptions> = {
+  dir: "skills",
+};
+
+export default defineNuxtModule<SkillsModuleOptions>({
+  meta: {
+    name: "docd:skills",
+  },
+  async setup(_inlineOptions, nuxt) {
+    const options = defu(
+      (nuxt.options as unknown as { docd?: { skills?: SkillsModuleOptions } }).docd?.skills,
+      defaults
+    ) as Required<SkillsModuleOptions>;
+
+    const skillsDir = join(nuxt.options.rootDir, options.dir);
+    if (!existsSync(skillsDir)) return;
+
+    const catalog = await scanSkills(skillsDir);
+    if (!catalog.length) return;
+
+    log.info(
+      `Found ${catalog.length} agent skill${catalog.length > 1 ? "s" : ""}: ${catalog.map((s) => s.name).join(", ")}`
+    );
+
+    nuxt.options.runtimeConfig.skills = { catalog };
+
+    const { resolve } = createResolver(import.meta.url);
+
+    const onNitroConfig = nuxt.hook as (
+      name: "nitro:config",
+      cb: (nitroConfig: NitroConfig) => void
+    ) => void;
+    onNitroConfig("nitro:config", (nitroConfig) => {
+      nitroConfig.serverAssets ||= [];
+      nitroConfig.serverAssets.push({ baseName: "skills", dir: skillsDir });
+    });
+
+    const prerenderRoutes = ["/.well-known/skills/index.json"];
+    for (const skill of catalog) {
+      for (const file of skill.files) {
+        prerenderRoutes.push(`/.well-known/skills/${skill.name}/${file}`);
+      }
+    }
+    addPrerenderRoutes(prerenderRoutes);
+
+    addServerHandler({
+      route: "/.well-known/skills/index.json",
+      handler: resolve("./runtime/server/routes/skills-index"),
+    });
+
+    addServerHandler({
+      route: "/.well-known/skills/**",
+      handler: resolve("./runtime/server/routes/skills-files"),
+    });
+  },
+});
+
+function parseFrontmatter(content: string): { name?: string; description?: string } | null {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match?.[1]) return null;
+  try {
+    return parseYaml(match[1]);
+  } catch {
+    return null;
+  }
+}
+
+function validateSkillName(name: string, dirName: string): boolean {
+  if (name.length > MAX_NAME_LENGTH) {
+    log.warn(`Skill "${name}" exceeds ${MAX_NAME_LENGTH} character limit`);
+    return false;
+  }
+  if (!SKILL_NAME_REGEX.test(name) || name.includes("--")) {
+    log.warn(`Skill name "${name}" does not match the Agent Skills naming spec`);
+    return false;
+  }
+  if (name !== dirName) {
+    log.warn(`Skill name "${name}" does not match directory name "${dirName}"`);
+    return false;
+  }
+  return true;
+}
+
+async function listFilesRecursively(dir: string, base: string = ""): Promise<string[]> {
+  const files: string[] = [];
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const relPath = base ? `${base}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      files.push(...(await listFilesRecursively(join(dir, entry.name), relPath)));
+    } else {
+      files.push(relPath);
+    }
+  }
+  return files;
+}
+
+async function scanSkills(skillsDir: string): Promise<SkillEntry[]> {
+  const catalog: SkillEntry[] = [];
+  const entries = await readdir(skillsDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+
+    const skillDir = join(skillsDir, entry.name);
+    const skillMdPath = join(skillDir, "SKILL.md");
+
+    if (!existsSync(skillMdPath)) continue;
+
+    const content = await readFile(skillMdPath, "utf-8");
+    const frontmatter = parseFrontmatter(content);
+
+    if (!frontmatter?.description) {
+      log.warn(`Skipping skill "${entry.name}": missing description in SKILL.md frontmatter`);
+      continue;
+    }
+
+    const name = frontmatter.name || entry.name;
+    if (!validateSkillName(name, entry.name)) continue;
+
+    const allFiles = await listFilesRecursively(skillDir);
+    const files = allFiles.filter((f) => !f.split("/").some((s) => s.startsWith(".")));
+    const sortedFiles = ["SKILL.md", ...files.filter((f) => f !== "SKILL.md")];
+
+    catalog.push({ name, description: frontmatter.description, files: sortedFiles });
+  }
+
+  return catalog;
+}
+
+declare module "nuxt/schema" {
+  interface RuntimeConfig {
+    skills: {
+      catalog: SkillEntry[];
+    };
+  }
+}

package/modules/skills/runtime/server/routes/skills-files.ts

@@ -0,0 +1,49 @@
+const CONTENT_TYPES: Record<string, string> = {
+  ".md": "text/markdown; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".yaml": "text/yaml; charset=utf-8",
+  ".yml": "text/yaml; charset=utf-8",
+  ".txt": "text/plain; charset=utf-8",
+  ".py": "text/plain; charset=utf-8",
+  ".sh": "text/plain; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".ts": "text/plain; charset=utf-8",
+};
+
+function getContentType(path: string): string {
+  const ext = path.slice(path.lastIndexOf("."));
+  return CONTENT_TYPES[ext] || "application/octet-stream";
+}
+
+export default defineEventHandler(async (event) => {
+  const url = getRequestURL(event);
+  const prefix = "/.well-known/skills/";
+  const idx = url.pathname.indexOf(prefix);
+  if (idx === -1) {
+    throw createError({ statusCode: 404, statusMessage: "Not Found" });
+  }
+
+  const filePath = decodeURIComponent(url.pathname.slice(idx + prefix.length));
+
+  if (!filePath || filePath.includes("..")) {
+    throw createError({ statusCode: 400, statusMessage: "Bad Request" });
+  }
+
+  const { skills } = useRuntimeConfig(event);
+  const skillName = filePath.split("/")[0];
+  if (!skills.catalog.some((s: { name: string }) => s.name === skillName)) {
+    throw createError({ statusCode: 404, statusMessage: "Not Found" });
+  }
+
+  const storage = useStorage("assets:skills");
+  const content = await storage.getItemRaw<string>(filePath);
+
+  if (!content) {
+    throw createError({ statusCode: 404, statusMessage: "Not Found" });
+  }
+
+  setResponseHeader(event, "content-type", getContentType(filePath));
+  setResponseHeader(event, "cache-control", "public, max-age=3600");
+
+  return content;
+});

package/modules/skills/runtime/server/routes/skills-index.ts

@@ -0,0 +1,8 @@
+export default defineEventHandler((event) => {
+  const { skills } = useRuntimeConfig(event);
+
+  setResponseHeader(event, "content-type", "application/json");
+  setResponseHeader(event, "cache-control", "public, max-age=3600");
+
+  return { skills: skills.catalog };
+});

package/nuxt.config.ts

@@ -0,0 +1,96 @@
+import { createResolver } from "@nuxt/kit";
+import tailwindcss from "@tailwindcss/vite";
+import type { BundledLanguage } from "shiki";
+
+const resolver = createResolver(import.meta.url);
+
+const langs: BundledLanguage[] = [
+  "json",
+  "js",
+  "ts",
+  "css",
+  "html",
+  "md",
+  "yaml",
+  "vue",
+  "vue-html",
+  "bash",
+  "sh",
+  "typescript",
+  "javascript",
+  "svelte",
+  "tsx",
+  "jsx",
+  "prisma",
+  "sql",
+  "docker",
+  "dockerfile",
+  "python",
+];
+
+export default defineNuxtConfig({
+  devtools: { enabled: true },
+  compatibilityDate: "latest",
+  modules: [
+    "@nuxtjs/robots",
+    "@nuxt/content",
+    "@nuxtjs/mdc",
+    "@nuxt/fonts",
+    "@nuxt/icon",
+    "@nuxt/image",
+    "reka-ui/nuxt",
+    "@nuxtjs/color-mode",
+    "motion-v/nuxt",
+    "@vueuse/nuxt",
+    "nuxt-gtag",
+    "nuxt-llms",
+    "@nuxtjs/robots",
+    "@nuxtjs/mcp-toolkit",
+    "nuxt-og-image",
+    "@morev/vue-transitions/nuxt",
+    "vue-sonner/nuxt",
+    resolver.resolve("./modules/routing"),
+    resolver.resolve("./modules/config"),
+    resolver.resolve("./modules/custom-icons"),
+    resolver.resolve("./modules/prose-component-meta"),
+    resolver.resolve("./modules/skills"),
+    resolver.resolve("./modules/markdown-rewrite"),
+  ],
+
+  mdc: {
+    highlight: { langs, noApiRoute: false },
+  },
+
+  content: {
+    build: {
+      markdown: {
+        toc: { depth: 4, searchDepth: 4 },
+        highlight: { langs },
+      },
+    },
+    experimental: { sqliteConnector: "native" },
+  },
+
+  imports: {
+    imports: [
+      { from: "tailwind-variants", name: "tv" },
+      { from: "tailwind-variants", name: "VariantProps", type: true },
+      { from: "vue-sonner", name: "toast", as: "useSonner" },
+    ],
+  },
+
+  icon: {
+    clientBundle: { scan: true, sizeLimitKb: 0 },
+    mode: "svg",
+    class: "shrink-0",
+    fetchTimeout: 2000,
+    serverBundle: "local",
+  },
+  css: [
+    resolver.resolve("./app/assets/css/tailwind.css"),
+    resolver.resolve("./app/assets/css/theme.css"),
+  ],
+  vite: {
+    plugins: [tailwindcss()],
+  },
+});