idcmd 0.0.1 → 0.0.3

package/src/content/components/install-tabs.ts

@@ -0,0 +1,120 @@
+import { z } from "zod";
+
+import type { DocComponent, DocComponentContext } from "./types";
+
+export interface InstallTabsProps {
+  dev?: boolean;
+  pkg: string;
+}
+
+const schema = z
+  .object({
+    dev: z.boolean().optional(),
+    pkg: z.string().min(1),
+  })
+  .strict() satisfies z.ZodType<InstallTabsProps>;
+
+const escapeHtml = (value: string): string =>
+  value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+
+type PackageManager = "npm" | "pnpm" | "bun" | "yarn";
+
+const PACKAGE_MANAGERS: readonly PackageManager[] = [
+  "npm",
+  "pnpm",
+  "bun",
+  "yarn",
+] as const;
+
+const buildInstallCommand = (options: {
+  dev: boolean;
+  pkg: string;
+  pm: PackageManager;
+}): string => {
+  const devFlag = options.dev;
+  const { pkg } = options;
+
+  switch (options.pm) {
+    case "npm": {
+      return devFlag ? `npm i -D ${pkg}` : `npm i ${pkg}`;
+    }
+    case "pnpm": {
+      return devFlag ? `pnpm add -D ${pkg}` : `pnpm add ${pkg}`;
+    }
+    case "bun": {
+      return devFlag ? `bun add -d ${pkg}` : `bun add ${pkg}`;
+    }
+    case "yarn": {
+      return devFlag ? `yarn add -D ${pkg}` : `yarn add ${pkg}`;
+    }
+    default: {
+      const exhaustiveCheck: never = options.pm;
+      throw new Error(`Unknown package manager: ${exhaustiveCheck}`);
+    }
+  }
+};
+
+const buildTabSegmentHtml = (options: {
+  code: string;
+  defaultPm: PackageManager;
+  idPrefix: string;
+  pm: PackageManager;
+}): string => {
+  const inputId = `${options.idPrefix}-${options.pm}`;
+  const checkedAttr = options.pm === options.defaultPm ? " checked" : "";
+
+  return [
+    `<input class="code-tabs__input" type="radio" name="${options.idPrefix}" id="${inputId}"${checkedAttr} />`,
+    `<label class="code-tabs__label" for="${inputId}" data-pm="${options.pm}">${options.pm}</label>`,
+    '<div class="code-tabs__panel">',
+    `<pre><code class="language-bash">${escapeHtml(options.code)}</code></pre>`,
+    "</div>",
+  ].join("");
+};
+
+const renderInstallTabsHtml = (
+  props: InstallTabsProps,
+  ctx: DocComponentContext
+): string => {
+  const dev = props.dev ?? false;
+  const pkg = props.pkg.trim();
+
+  const idPrefix = `install-tabs-${ctx.instanceId}`;
+
+  const defaultPm: PackageManager = "npm";
+
+  const segments = PACKAGE_MANAGERS.map((pm) => {
+    const code = buildInstallCommand({ dev, pkg, pm });
+    return buildTabSegmentHtml({ code, defaultPm, idPrefix, pm });
+  }).join("");
+
+  return [
+    '<div class="code-tabs" data-code-tabs="install" data-doc-component="InstallTabs">',
+    segments,
+    "</div>",
+  ].join("");
+};
+
+const renderInstallTabsMarkdown = (props: InstallTabsProps): string => {
+  const dev = props.dev ?? false;
+  const pkg = props.pkg.trim();
+
+  const blocks = PACKAGE_MANAGERS.map((pm) => {
+    const command = buildInstallCommand({ dev, pkg, pm });
+    return [`### ${pm}`, "", "```sh", command, "```", ""].join("\n");
+  });
+
+  return blocks.join("\n");
+};
+
+export const InstallTabs: DocComponent<InstallTabsProps> = {
+  name: "InstallTabs",
+  renderHtml: renderInstallTabsHtml,
+  renderMarkdown: (props) => renderInstallTabsMarkdown(props),
+  schema,
+};

package/src/content/components/registry.ts

@@ -0,0 +1,12 @@
+import type { DocComponent } from "./types";
+
+import { InstallTabs } from "./install-tabs";
+
+type AnyDocComponent = DocComponent<unknown>;
+
+const COMPONENTS: Record<string, AnyDocComponent> = {
+  InstallTabs: InstallTabs as unknown as AnyDocComponent,
+};
+
+export const getDocComponent = (name: string): AnyDocComponent | undefined =>
+  COMPONENTS[name];

package/src/content/components/types.ts

@@ -0,0 +1,21 @@
+import type { ZodType } from "zod";
+
+export interface DocComponentContext {
+  currentPath: string;
+  instanceId: string;
+  isDev: boolean;
+  slug: string;
+}
+
+export interface DocComponent<Props> {
+  name: string;
+  schema: ZodType<Props>;
+  renderHtml: (
+    props: Props,
+    ctx: DocComponentContext
+  ) => string | Promise<string>;
+  renderMarkdown: (
+    props: Props,
+    ctx: DocComponentContext
+  ) => string | Promise<string>;
+}

package/src/content/frontmatter.ts

@@ -0,0 +1,89 @@
+/**
+ * Frontmatter parsing utility
+ * Extracts YAML frontmatter from markdown files since Bun.markdown.html()
+ * doesn't handle it natively (renders it as HTML instead of stripping it).
+ */
+
+export interface PageMeta {
+  title?: string;
+  description?: string;
+  icon?: string;
+  group?: string;
+  order?: number;
+  hidden?: boolean;
+}
+
+export interface ParsedMarkdown {
+  frontmatter: PageMeta;
+  content: string;
+}
+
+/**
+ * Parse YAML frontmatter from markdown content.
+ * Frontmatter must be at the very start of the file, delimited by `---`.
+ *
+ * @example
+ * ```markdown
+ * ---
+ * title: My Page
+ * icon: home
+ * group: main
+ * order: 1
+ * ---
+ * # Content here
+ * ```
+ */
+const getFrontmatterBlock = (
+  trimmed: string
+): { yamlBlock: string; content: string } | null => {
+  if (!trimmed.startsWith("---")) {
+    return null;
+  }
+
+  const endIndex = trimmed.indexOf("---", 3);
+  if (endIndex === -1) {
+    return null;
+  }
+
+  return {
+    content: trimmed.slice(endIndex + 3).trimStart(),
+    yamlBlock: trimmed.slice(3, endIndex).trim(),
+  };
+};
+
+const parseYamlFrontmatter = (yamlBlock: string): PageMeta => {
+  try {
+    const parsed = Bun.YAML.parse(yamlBlock);
+    if (parsed && typeof parsed === "object") {
+      return parsed as PageMeta;
+    }
+  } catch (error) {
+    console.warn("Failed to parse frontmatter YAML:", error);
+  }
+
+  return {};
+};
+
+export const parseFrontmatter = (markdown: string): ParsedMarkdown => {
+  const trimmed = markdown.trimStart();
+  const block = getFrontmatterBlock(trimmed);
+
+  if (!block) {
+    return {
+      content: markdown,
+      frontmatter: {},
+    };
+  }
+
+  return {
+    content: block.content,
+    frontmatter: parseYamlFrontmatter(block.yamlBlock),
+  };
+};
+
+/**
+ * Extract title from markdown content (first h1 heading).
+ * Used as fallback when frontmatter doesn't specify a title.
+ */
+export const extractTitleFromContent = (markdown: string): string | undefined =>
+  markdown.match(/^#\s+(.+)$/m)?.[1];

package/src/content/icons.ts

@@ -0,0 +1,78 @@
+import { getProjectPaths } from "../project/paths";
+
+const FALLBACK_ICON_NAME = "file";
+const FALLBACK_ICON_SVG = `<svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z"/><path d="M14 2v4a2 2 0 0 0 2 2h4"/></svg>`;
+
+const iconFileCache = new Map<string, Promise<string | undefined>>();
+
+const readSvgFile = async (path: string): Promise<string | undefined> => {
+  const file = Bun.file(path);
+  if (!(await file.exists())) {
+    return undefined;
+  }
+  return file.text();
+};
+
+const getCachedSvgFile = (path: string): Promise<string | undefined> => {
+  const cached = iconFileCache.get(path);
+  if (cached) {
+    return cached;
+  }
+
+  const pending = readSvgFile(path);
+  iconFileCache.set(path, pending);
+  return pending;
+};
+
+const getNamedIconPath = async (name: string): Promise<string> => {
+  const { iconsDir } = await getProjectPaths();
+  return `${iconsDir}/${name}.svg`;
+};
+
+const loadCustomIcon = async (
+  slug: string,
+  iconPath: string
+): Promise<string | undefined> => {
+  const { contentDir } = await getProjectPaths();
+  const resolvedPath = `${contentDir}/${slug}/${iconPath.slice(2)}`;
+  const svg = await getCachedSvgFile(resolvedPath);
+  if (!svg) {
+    console.warn(`Custom icon not found: ${resolvedPath}`);
+  }
+  return svg;
+};
+
+const getFallbackIcon = async (): Promise<string> => {
+  const svg = await getCachedSvgFile(
+    await getNamedIconPath(FALLBACK_ICON_NAME)
+  );
+  return svg ?? FALLBACK_ICON_SVG;
+};
+
+/**
+ * Resolve an icon specification to SVG content.
+ * - "./icon.svg" -> loads from content/<slug>/icon.svg
+ * - "home" -> loads from icons/home.svg
+ * - Falls back to icons/file.svg (or built-in fallback SVG)
+ */
+export const resolveIconSvg = async (
+  slug: string,
+  icon: string | undefined
+): Promise<string> => {
+  if (!icon) {
+    return getFallbackIcon();
+  }
+
+  if (icon.startsWith("./")) {
+    const customSvg = await loadCustomIcon(slug, icon);
+    return customSvg ?? (await getFallbackIcon());
+  }
+
+  const namedSvg = await getCachedSvgFile(await getNamedIconPath(icon));
+  if (namedSvg) {
+    return namedSvg;
+  }
+
+  console.warn(`Icon "${icon}" not found in icons/ folder for ${slug}`);
+  return getFallbackIcon();
+};

package/src/content/llms.ts

@@ -0,0 +1,93 @@
+import type { SiteConfig } from "../site/config";
+
+import { loadSiteConfig } from "../site/config";
+import { parseFrontmatter } from "./frontmatter";
+import { derivePageMetaFromParsed } from "./meta";
+import {
+  getContentDir,
+  pageSlugFromContentSlug,
+  scanContentFiles,
+  slugFromContentFile,
+} from "./paths";
+
+interface LlmsPage {
+  description: string;
+  slug: string;
+  title: string;
+}
+
+const sortPages = (pages: LlmsPage[]): LlmsPage[] =>
+  pages.toSorted((a, b) => {
+    if (a.slug === "") {
+      return -1;
+    }
+    if (b.slug === "") {
+      return 1;
+    }
+    return a.title.localeCompare(b.title);
+  });
+
+const buildLlmsPage = async (
+  file: string,
+  contentDir: string,
+  siteConfig: SiteConfig
+): Promise<LlmsPage | null> => {
+  const markdown = await Bun.file(`${contentDir}/${file}`).text();
+  const parsed = parseFrontmatter(markdown);
+
+  if (parsed.frontmatter.hidden) {
+    return null;
+  }
+
+  const slug = slugFromContentFile(file);
+  const meta = derivePageMetaFromParsed(parsed, {
+    fallbackTitle: slug,
+    siteDefaultDescription: siteConfig.description,
+  });
+
+  return {
+    description: meta.description,
+    slug: pageSlugFromContentSlug(slug),
+    title: meta.title,
+  };
+};
+
+const buildLlmsPages = async (siteConfig: SiteConfig): Promise<LlmsPage[]> => {
+  const pages: LlmsPage[] = [];
+  const contentDir = await getContentDir();
+
+  for await (const file of scanContentFiles()) {
+    const page = await buildLlmsPage(file, contentDir, siteConfig);
+    if (page) {
+      pages.push(page);
+    }
+  }
+
+  return pages;
+};
+
+const formatLlmsTxt = (siteConfig: SiteConfig, pages: LlmsPage[]): string => {
+  const lines = [
+    `# ${siteConfig.name}`,
+    "",
+    `> ${siteConfig.description}`,
+    "",
+    "## Pages",
+    "",
+  ];
+
+  for (const page of pages) {
+    const mdFile = page.slug === "" ? "index.md" : `${page.slug}.md`;
+    lines.push(`- [${page.title}](/${mdFile}): ${page.description}`);
+  }
+
+  return `${lines.join("\n")}\n`;
+};
+
+export const generateLlmsTxt = async (): Promise<string> => {
+  const siteConfig = await loadSiteConfig();
+  const pages = await buildLlmsPages(siteConfig);
+  const sortedPages = sortPages(pages);
+
+  return formatLlmsTxt(siteConfig, sortedPages);
+};

package/src/content/meta.ts

@@ -0,0 +1,92 @@
+import type { ParsedMarkdown } from "./frontmatter";
+
+import { extractTitleFromContent } from "./frontmatter";
+
+const stripInlineMarkdown = (text: string): string =>
+  text
+    // Images: ![alt](url) -> alt
+    .replaceAll(/!\[([^\]]*)\]\([^)]+\)/g, "$1")
+    // Links: [text](url) -> text
+    .replaceAll(/\[([^\]]+)\]\([^)]+\)/g, "$1")
+    // Inline code: `code` -> code
+    .replaceAll(/`([^`]+)`/g, "$1")
+    // Emphasis markers
+    .replaceAll(/[*_~]+/g, "")
+    .trim();
+
+const extractDescriptionFromContent = (content: string): string | undefined => {
+  const lines = content.split("\n");
+  const titleIndex = lines.findIndex((line) => /^#\s+/.test(line));
+
+  const startIndex = titleIndex === -1 ? 0 : titleIndex + 1;
+  const firstMeaningfulLine = lines
+    .slice(startIndex)
+    .find(
+      (line) => line.trim().length > 0 && !line.trimStart().startsWith("#")
+    );
+
+  const cleaned = firstMeaningfulLine
+    ? stripInlineMarkdown(firstMeaningfulLine)
+    : undefined;
+
+  return cleaned && cleaned.length > 0 ? cleaned : undefined;
+};
+
+export interface DeriveTitleOptions {
+  fallbackTitle: string;
+  titleOverride?: string;
+}
+
+export const deriveTitleFromParsed = (
+  parsed: ParsedMarkdown,
+  options: DeriveTitleOptions
+): string => {
+  const override = options.titleOverride?.trim();
+  if (override) {
+    return override;
+  }
+
+  return (
+    parsed.frontmatter.title ??
+    extractTitleFromContent(parsed.content) ??
+    options.fallbackTitle
+  );
+};
+
+export interface DeriveDescriptionOptions {
+  siteDefaultDescription: string;
+}
+
+export const deriveDescriptionFromParsed = (
+  parsed: ParsedMarkdown,
+  options: DeriveDescriptionOptions
+): string => {
+  const frontmatterDescription = parsed.frontmatter.description?.trim();
+  if (frontmatterDescription) {
+    return frontmatterDescription;
+  }
+
+  const extracted = extractDescriptionFromContent(parsed.content);
+  if (extracted) {
+    return extracted;
+  }
+
+  const fallback = options.siteDefaultDescription.trim();
+  return fallback.length > 0 ? fallback : "No description available.";
+};
+
+export interface DerivePageMetaOptions
+  extends DeriveTitleOptions, DeriveDescriptionOptions {}
+
+export const derivePageMetaFromParsed = (
+  parsed: ParsedMarkdown,
+  options: DerivePageMetaOptions
+): { title: string; description: string } => ({
+  description: deriveDescriptionFromParsed(parsed, {
+    siteDefaultDescription: options.siteDefaultDescription,
+  }),
+  title: deriveTitleFromParsed(parsed, {
+    fallbackTitle: options.fallbackTitle,
+    titleOverride: options.titleOverride,
+  }),
+});

package/src/content/navigation.ts

@@ -0,0 +1,154 @@
+/**
+ * Navigation discovery utility
+ * Scans content folders and builds navigation structure from frontmatter.
+ */
+
+import type { GroupConfig } from "../site/config";
+import type { PageMeta } from "./frontmatter";
+
+import { loadSiteConfig } from "../site/config";
+import { parseFrontmatter, extractTitleFromContent } from "./frontmatter";
+import { resolveIconSvg } from "./icons";
+import { getContentDir, scanContentFiles, slugFromContentFile } from "./paths";
+
+export interface NavItem {
+  title: string;
+  href: string;
+  // SVG content for the icon
+  iconSvg: string;
+  order: number;
+}
+
+export interface NavGroup {
+  id: string;
+  label: string;
+  order: number;
+  items: NavItem[];
+}
+
+const buildGroupsMap = (groups: GroupConfig[]): Map<string, NavGroup> => {
+  const groupsMap = new Map<string, NavGroup>();
+  for (const group of groups) {
+    groupsMap.set(group.id, {
+      id: group.id,
+      items: [],
+      label: group.label,
+      order: group.order,
+    });
+  }
+  return groupsMap;
+};
+
+const createDefaultGroup = (): NavGroup => ({
+  id: "_default",
+  items: [],
+  label: "Pages",
+  order: 999,
+});
+
+const createGroupFromId = (groupId: string): NavGroup => ({
+  id: groupId,
+  items: [],
+  label: groupId.charAt(0).toUpperCase() + groupId.slice(1),
+  order: 100,
+});
+
+const buildNavItem = async (
+  slug: string,
+  frontmatter: PageMeta,
+  content: string
+): Promise<NavItem> => {
+  const title = frontmatter.title ?? extractTitleFromContent(content) ?? slug;
+  const href = slug === "index" ? "/" : `/${slug}/`;
+  const iconSvg = await resolveIconSvg(slug, frontmatter.icon);
+
+  return {
+    href,
+    iconSvg,
+    order: frontmatter.order ?? 100,
+    title,
+  };
+};
+
+const addNavItemToGroups = (
+  groupsMap: Map<string, NavGroup>,
+  defaultGroup: NavGroup,
+  navItem: NavItem,
+  groupId: string | undefined
+): void => {
+  if (!groupId) {
+    defaultGroup.items.push(navItem);
+    return;
+  }
+
+  const existingGroup = groupsMap.get(groupId);
+  if (existingGroup) {
+    existingGroup.items.push(navItem);
+    return;
+  }
+
+  const createdGroup = createGroupFromId(groupId);
+  createdGroup.items.push(navItem);
+  groupsMap.set(groupId, createdGroup);
+};
+
+const addFileToNavigation = async (
+  file: string,
+  groupsMap: Map<string, NavGroup>,
+  defaultGroup: NavGroup,
+  contentDir: string
+): Promise<void> => {
+  const slug = slugFromContentFile(file);
+  const markdown = await Bun.file(`${contentDir}/${file}`).text();
+  const { frontmatter, content } = parseFrontmatter(markdown);
+
+  if (frontmatter.hidden) {
+    return;
+  }
+
+  const navItem = await buildNavItem(slug, frontmatter, content);
+  addNavItemToGroups(groupsMap, defaultGroup, navItem, frontmatter.group);
+};
+
+const finalizeGroups = (
+  groupsMap: Map<string, NavGroup>,
+  defaultGroup: NavGroup
+): NavGroup[] => {
+  if (defaultGroup.items.length > 0) {
+    groupsMap.set(defaultGroup.id, defaultGroup);
+  }
+
+  const groups = [...groupsMap.values()]
+    .filter((group) => group.items.length > 0)
+    .toSorted((a, b) => a.order - b.order);
+
+  for (const group of groups) {
+    group.items.sort((a, b) => a.order - b.order);
+  }
+
+  return groups;
+};
+
+/**
+ * Discover all pages and build navigation structure.
+ * Reads frontmatter from each content file to determine:
+ * - Title (falls back to h1)
+ * - Icon (loaded from icons/ folder or custom path)
+ * - Group (for sidebar sections)
+ * - Order (sort order within group)
+ */
+export const discoverNavigation = async (): Promise<NavGroup[]> => {
+  const siteConfig = await loadSiteConfig();
+  const contentDir = await getContentDir();
+
+  // Map of group ID -> NavGroup
+  const groupsMap = buildGroupsMap(siteConfig.groups ?? []);
+  const defaultGroup = createDefaultGroup();
+
+  // Scan all content files
+  for await (const file of scanContentFiles()) {
+    await addFileToNavigation(file, groupsMap, defaultGroup, contentDir);
+  }
+
+  return finalizeGroups(groupsMap, defaultGroup);
+};

package/src/content/paths.ts

@@ -0,0 +1,34 @@
+import { getProjectPaths } from "../project/paths";
+
+const flatContentGlob = new Bun.Glob("*.md");
+
+export const getContentDir = async (): Promise<string> => {
+  const paths = await getProjectPaths();
+  return paths.contentDir;
+};
+
+export const getMarkdownFilePath = async (slug: string): Promise<string> =>
+  `${await getContentDir()}/${slug}.md`;
+
+export const slugFromContentFile = (file: string): string => {
+  if (file.endsWith(".md")) {
+    return file.slice(0, -".md".length);
+  }
+
+  return file;
+};
+
+export const scanContentFiles =
+  async function* scanContentFiles(): AsyncGenerator<string> {
+    const { contentDir } = await getProjectPaths();
+    // `content/<slug>.md`
+    for await (const file of flatContentGlob.scan(contentDir)) {
+      yield file;
+    }
+  };
+
+export const pageSlugFromContentSlug = (slug: string): string =>
+  slug === "index" ? "" : slug;
+
+export const pagePathFromContentSlug = (slug: string): string =>
+  slug === "index" ? "/" : `/${slug}/`;

package/src/content/store.ts

@@ -0,0 +1,10 @@
+import { getMarkdownFilePath } from "./paths";
+
+export const getMarkdownFile = async (slug: string): Promise<string | null> => {
+  const filePath = await getMarkdownFilePath(slug);
+  const file = Bun.file(filePath);
+  if (await file.exists()) {
+    return file.text();
+  }
+  return null;
+};