idcmd 0.0.1 → 0.0.3

package/src/server.ts

@@ -0,0 +1,234 @@
+import type { Server } from "bun";
+
+import { expandMarkdownForAgent } from "./content/components/expand";
+import { generateLlmsTxt } from "./content/llms";
+import { getMarkdownFile } from "./content/store";
+import { getProjectPaths } from "./project/paths";
+import { renderMarkdownPage } from "./render/page-renderer";
+import { handleSearchRequest } from "./search/api";
+import { handleSearchPageRequest } from "./search/server-page";
+import { handleRobotsTxt, handleSitemapXml } from "./seo/server";
+import {
+  createHtmlCacheHeaders,
+  createStaticCacheHeaders,
+} from "./server/headers";
+import { createLiveReload } from "./server/live-reload";
+import { serveStaticFile } from "./server/static";
+import { handleUserRouteRequest } from "./server/user-routes";
+import {
+  getRedirectForCanonicalHtmlPath,
+  isFileLikePathname,
+  toCanonicalHtmlPathname,
+} from "./site/url-policy";
+
+type ServerInstance = Server<undefined>;
+
+const project = await getProjectPaths();
+const PUBLIC_DIR = project.publicDir;
+const DIST_DIR = project.distDir;
+const isDev = process.env.NODE_ENV !== "production";
+const LIVE_RELOAD_POLL_MS = 250;
+const MIN_SEARCH_QUERY_LENGTH = 2;
+const MAX_SEARCH_RESULTS = 50;
+
+const cacheHeaders = createHtmlCacheHeaders(isDev);
+const staticCacheHeaders = createStaticCacheHeaders(isDev);
+
+const withQueryString = (pathname: string, search: string): string =>
+  search ? `${pathname}${search}` : pathname;
+
+const createRedirectResponse = (pathname: string, url: URL): Response =>
+  new Response(null, {
+    headers: {
+      Location: withQueryString(pathname, url.search),
+      ...(isDev ? { "Cache-Control": "no-cache" } : {}),
+    },
+    status: 308,
+  });
+
+const liveReload = createLiveReload({
+  isDev,
+  pollMs: LIVE_RELOAD_POLL_MS,
+  websocketPath: `${project.assetPrefix}/live-reload`,
+});
+
+if (isDev) {
+  try {
+    await liveReload.startWatcher();
+  } catch (error) {
+    console.warn("[live-reload] Watcher failed", error);
+  }
+}
+
+const handleLlmsTxt = async (path: string): Promise<Response | undefined> => {
+  if (path !== "/llms.txt") {
+    return undefined;
+  }
+
+  const llmsTxt = await generateLlmsTxt();
+  return new Response(llmsTxt, {
+    headers: {
+      "Content-Type": "text/plain; charset=utf-8",
+      ...staticCacheHeaders,
+    },
+  });
+};
+
+const handleMarkdownRequest = async (
+  path: string
+): Promise<Response | undefined> => {
+  if (!path.endsWith(".md")) {
+    return undefined;
+  }
+
+  const isRaw = path.endsWith(".raw.md");
+  const slug = isRaw ? path.slice(1, -".raw.md".length) : path.slice(1, -3);
+  const markdown = await getMarkdownFile(slug);
+
+  if (!markdown) {
+    return new Response("Not Found", {
+      headers: { "Content-Type": "text/plain" },
+      status: 404,
+    });
+  }
+
+  const expanded = isRaw
+    ? markdown
+    : await expandMarkdownForAgent(markdown, {
+        currentPath: slug === "index" ? "/" : `/${slug}/`,
+        instanceId: `${slug}:md`,
+        isDev,
+        slug,
+      });
+
+  return new Response(expanded, {
+    headers: {
+      "Content-Type": "text/markdown; charset=utf-8",
+      ...staticCacheHeaders,
+    },
+    status: 200,
+  });
+};
+
+const createNotFoundResponse = async (url: URL): Promise<Response> => {
+  const notFoundMarkdown = await getMarkdownFile("404");
+  if (notFoundMarkdown) {
+    const canonicalPathname = toCanonicalHtmlPathname(url.pathname);
+    const html = await renderMarkdownPage(notFoundMarkdown, {
+      currentPath: canonicalPathname,
+      isDev,
+      requestOrigin: url.origin,
+      searchQuery: url.searchParams.get("q") ?? undefined,
+    });
+    return new Response(html, {
+      headers: cacheHeaders,
+      status: 404,
+    });
+  }
+
+  return new Response("Not Found", {
+    headers: { "Content-Type": "text/plain; charset=utf-8" },
+    status: 404,
+  });
+};
+
+const handlePageRequest = async (url: URL): Promise<Response> => {
+  const canonicalPathname = toCanonicalHtmlPathname(url.pathname);
+  const slug =
+    canonicalPathname === "/" ? "index" : canonicalPathname.slice(1, -1);
+  const markdown = await getMarkdownFile(slug);
+
+  if (!markdown) {
+    return createNotFoundResponse(url);
+  }
+
+  const html = await renderMarkdownPage(markdown, {
+    currentPath: canonicalPathname,
+    isDev,
+    requestOrigin: url.origin,
+  });
+
+  return new Response(html, { headers: cacheHeaders, status: 200 });
+};
+
+const maybeHandleCanonicalRedirect = (url: URL): Response | undefined => {
+  const { pathname } = url;
+
+  if (
+    pathname === "/__live-reload" ||
+    pathname === `${project.assetPrefix}/live-reload` ||
+    pathname.startsWith("/api/")
+  ) {
+    return undefined;
+  }
+
+  if (isFileLikePathname(pathname)) {
+    return undefined;
+  }
+
+  const redirectPathname = getRedirectForCanonicalHtmlPath(pathname);
+  if (!redirectPathname) {
+    return undefined;
+  }
+
+  return createRedirectResponse(redirectPathname, url);
+};
+
+const handleRequest = async (
+  req: Request,
+  server: ServerInstance
+): Promise<Response | undefined> => {
+  const url = new URL(req.url);
+  const path = url.pathname;
+
+  const liveReloadUpgrade = liveReload.maybeHandleUpgrade(req, server, path);
+  if (liveReloadUpgrade === "handled") {
+    return undefined;
+  }
+
+  const seoEnv = { distDir: DIST_DIR, isDev, staticCacheHeaders };
+  const searchPageEnv = {
+    cacheHeaders,
+    isDev,
+    maxResults: MAX_SEARCH_RESULTS,
+    minQueryLength: MIN_SEARCH_QUERY_LENGTH,
+  };
+  const staticEnv = {
+    distDir: DIST_DIR,
+    isDev,
+    publicDir: PUBLIC_DIR,
+    staticCacheHeaders,
+  };
+  const userRoutesEnv = { isDev, routesDir: project.routesDir };
+
+  return (
+    liveReloadUpgrade ??
+    (await handleLlmsTxt(path)) ??
+    (await handleRobotsTxt(url, seoEnv)) ??
+    (await handleSitemapXml(url, seoEnv)) ??
+    (await handleSearchRequest(url)) ??
+    (await handleUserRouteRequest(url, req, userRoutesEnv)) ??
+    (await serveStaticFile(path, staticEnv)) ??
+    (await handleMarkdownRequest(path)) ??
+    (await (maybeHandleCanonicalRedirect(url) ??
+      handleSearchPageRequest(url, searchPageEnv))) ??
+    (await handlePageRequest(url))
+  );
+};
+
+const server = Bun.serve({
+  fetch(req, serverInstance) {
+    return handleRequest(req, serverInstance);
+  },
+
+  port: process.env.PORT || 4000,
+
+  websocket: liveReload.websocket,
+});
+
+console.log(`Server running at http://localhost:${server.port}`);
+if (isDev) {
+  console.log(
+    "Live reload enabled - editing .md files will refresh the browser"
+  );
+}

package/src/site/config.ts

@@ -0,0 +1,244 @@
+import { ZodError, z } from "zod";
+
+export const SearchScopeSchema = z.enum([
+  "full",
+  "title",
+  "title_and_description",
+]);
+export type SearchScope = z.infer<typeof SearchScopeSchema>;
+
+export const RightRailVisibleFromSchema = z.enum([
+  "xl",
+  "lg",
+  "md",
+  "always",
+  "never",
+]);
+export type RightRailVisibleFrom = z.infer<typeof RightRailVisibleFromSchema>;
+
+export const ScrollSpyUpdateHashSchema = z.enum(["never", "replace", "push"]);
+export type ScrollSpyUpdateHash = z.infer<typeof ScrollSpyUpdateHashSchema>;
+
+export const TocLevelSchema = z.union([
+  z.literal(1),
+  z.literal(2),
+  z.literal(3),
+  z.literal(4),
+  z.literal(5),
+  z.literal(6),
+]);
+export type TocLevel = z.infer<typeof TocLevelSchema>;
+
+export const RightRailScrollSpyConfigSchema = z
+  .object({
+    centerActiveItem: z.boolean().optional(),
+    enabled: z.boolean().optional(),
+    updateHash: ScrollSpyUpdateHashSchema.optional(),
+  })
+  .strict();
+export type RightRailScrollSpyConfig = z.infer<
+  typeof RightRailScrollSpyConfigSchema
+>;
+
+export const RightRailConfigSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    placement: z.enum(["content", "viewport"]).optional(),
+    scrollSpy: RightRailScrollSpyConfigSchema.optional(),
+    smoothScroll: z.boolean().optional(),
+    tocLevels: z.array(TocLevelSchema).optional(),
+    visibleFrom: RightRailVisibleFromSchema.optional(),
+  })
+  .strict();
+export type RightRailConfig = z.infer<typeof RightRailConfigSchema>;
+
+export const GroupConfigSchema = z
+  .object({
+    id: z.string().min(1),
+    label: z.string().min(1),
+    order: z.number().int(),
+  })
+  .strict();
+export type GroupConfig = z.infer<typeof GroupConfigSchema>;
+
+export const SiteConfigSchema = z
+  .object({
+    baseUrl: z.string().url().optional(),
+    description: z.string(),
+    groups: z.array(GroupConfigSchema).optional(),
+    name: z.string().min(1),
+    rightRail: RightRailConfigSchema.optional(),
+    search: z
+      .object({
+        scope: SearchScopeSchema.optional(),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict();
+export type SiteConfig = z.infer<typeof SiteConfigSchema>;
+
+export interface ResolvedRightRailConfig {
+  enabled: boolean;
+  visibleFrom: RightRailVisibleFrom;
+  placement: "content" | "viewport";
+  tocLevels: readonly TocLevel[];
+  smoothScroll: boolean;
+  scrollSpy: {
+    enabled: boolean;
+    centerActiveItem: boolean;
+    updateHash: ScrollSpyUpdateHash;
+  };
+}
+
+const LEGACY_SITE_CONFIG_PATH = "site.jsonc";
+const NEW_SITE_CONFIG_PATH = "site/site.jsonc";
+const LOCALHOST_HOSTNAMES = new Set(["localhost", "127.0.0.1", "::1"]);
+
+const DEFAULT_RIGHT_RAIL_CONFIG: ResolvedRightRailConfig = {
+  enabled: true,
+  placement: "content",
+  scrollSpy: {
+    centerActiveItem: true,
+    enabled: true,
+    updateHash: "never",
+  },
+  smoothScroll: false,
+  tocLevels: [2, 3],
+  visibleFrom: "xl",
+} as const;
+
+export const resolveRightRailConfig = (
+  config?: RightRailConfig
+): ResolvedRightRailConfig => ({
+  enabled: config?.enabled ?? DEFAULT_RIGHT_RAIL_CONFIG.enabled,
+  placement: config?.placement ?? DEFAULT_RIGHT_RAIL_CONFIG.placement,
+  scrollSpy: {
+    centerActiveItem:
+      config?.scrollSpy?.centerActiveItem ??
+      DEFAULT_RIGHT_RAIL_CONFIG.scrollSpy.centerActiveItem,
+    enabled:
+      config?.scrollSpy?.enabled ?? DEFAULT_RIGHT_RAIL_CONFIG.scrollSpy.enabled,
+    updateHash:
+      config?.scrollSpy?.updateHash ??
+      DEFAULT_RIGHT_RAIL_CONFIG.scrollSpy.updateHash,
+  },
+  smoothScroll: config?.smoothScroll ?? DEFAULT_RIGHT_RAIL_CONFIG.smoothScroll,
+  tocLevels: [...(config?.tocLevels ?? DEFAULT_RIGHT_RAIL_CONFIG.tocLevels)],
+  visibleFrom: config?.visibleFrom ?? DEFAULT_RIGHT_RAIL_CONFIG.visibleFrom,
+});
+
+const isLocalhostBaseUrl = (baseUrl: string): boolean => {
+  try {
+    const url = new URL(baseUrl);
+    return LOCALHOST_HOSTNAMES.has(url.hostname);
+  } catch {
+    return false;
+  }
+};
+
+const normalizeBaseUrl = (baseUrl: string): string | undefined => {
+  try {
+    const url = new URL(baseUrl);
+    // Canonicalize to origin (strip path/query/hash).
+    return url.origin;
+  } catch {
+    return undefined;
+  }
+};
+
+const resolveBaseUrlFromEnv = (): string | undefined => {
+  const explicit = process.env.SITE_BASE_URL;
+  if (explicit) {
+    return normalizeBaseUrl(explicit);
+  }
+
+  // Vercel provides hostnames without protocol.
+  const vercelUrl =
+    process.env.VERCEL_URL ??
+    process.env.VERCEL_PROJECT_PRODUCTION_URL ??
+    process.env.VERCEL_BRANCH_URL;
+
+  if (vercelUrl) {
+    return normalizeBaseUrl(`https://${vercelUrl}`);
+  }
+
+  return undefined;
+};
+
+const resolveBaseUrl = (baseUrl: string | undefined): string | undefined => {
+  const normalizedConfigUrl = baseUrl ? normalizeBaseUrl(baseUrl) : undefined;
+  const envUrl = resolveBaseUrlFromEnv();
+
+  // If config is set to localhost (common for dev), prefer env-derived URL when available.
+  if (normalizedConfigUrl && !isLocalhostBaseUrl(normalizedConfigUrl)) {
+    return normalizedConfigUrl;
+  }
+
+  return envUrl ?? normalizedConfigUrl;
+};
+
+const formatZodIssuePath = (path: readonly (string | number)[]): string =>
+  path.length === 0 ? "(root)" : path.join(".");
+
+const formatSiteConfigZodError = (
+  configPath: string,
+  error: ZodError
+): string => {
+  const lines = error.issues.map(
+    (issue) => `${formatZodIssuePath(issue.path)}: ${issue.message}`
+  );
+  return `${configPath} validation failed:\n${lines.join("\n")}`;
+};
+
+const DEFAULT_SITE_CONFIG: SiteConfig = { description: "", name: "idcmd" };
+
+const parseSiteConfigJsonc = (configPath: string, text: string): unknown => {
+  try {
+    return Bun.JSONC.parse(text) as unknown;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to parse ${configPath} as JSONC: ${message}`, {
+      cause: error,
+    });
+  }
+};
+
+const parseSiteConfigUnknown = (
+  configPath: string,
+  raw: unknown
+): SiteConfig => {
+  try {
+    return SiteConfigSchema.parse(raw);
+  } catch (error) {
+    if (error instanceof ZodError) {
+      throw new TypeError(formatSiteConfigZodError(configPath, error), {
+        cause: error,
+      });
+    }
+    throw error;
+  }
+};
+
+const resolveSiteConfigPath = async (): Promise<string> => {
+  if (await Bun.file(NEW_SITE_CONFIG_PATH).exists()) {
+    return NEW_SITE_CONFIG_PATH;
+  }
+  return LEGACY_SITE_CONFIG_PATH;
+};
+
+export const loadSiteConfig = async (): Promise<SiteConfig> => {
+  const configPath = await resolveSiteConfigPath();
+  const file = Bun.file(configPath);
+  if (!(await file.exists())) {
+    return DEFAULT_SITE_CONFIG;
+  }
+
+  const text = await file.text();
+  const raw = parseSiteConfigJsonc(configPath, text);
+  const parsed = parseSiteConfigUnknown(configPath, raw);
+  return { ...parsed, baseUrl: resolveBaseUrl(parsed.baseUrl) };
+};
+
+export const getSearchScope = (siteConfig: SiteConfig): SearchScope =>
+  siteConfig.search?.scope ?? "full";

package/src/site/url-policy.ts

@@ -0,0 +1,60 @@
+const ensureLeadingSlash = (pathname: string): string =>
+  pathname.startsWith("/") ? pathname : `/${pathname}`;
+
+const collapseSlashes = (pathname: string): string =>
+  pathname.replaceAll(/\/{2,}/g, "/");
+
+const trimTrailingSlash = (pathname: string): string =>
+  pathname !== "/" && pathname.endsWith("/") ? pathname.slice(0, -1) : pathname;
+
+const lastSegment = (pathname: string): string => {
+  const trimmed = trimTrailingSlash(pathname);
+  const index = trimmed.lastIndexOf("/");
+  return index === -1 ? trimmed : trimmed.slice(index + 1);
+};
+
+export const isFileLikePathname = (pathname: string): boolean => {
+  const normalized = collapseSlashes(ensureLeadingSlash(pathname));
+  const segment = lastSegment(normalized);
+
+  // Treat any last-path segment with an extension as file-like.
+  // Examples: /styles.css, /robots.txt, /index.md
+  const dotIndex = segment.lastIndexOf(".");
+  return dotIndex > 0 && dotIndex < segment.length - 1;
+};
+
+const stripIndexSegment = (pathname: string): string => {
+  if (pathname === "/index") {
+    return "/";
+  }
+  if (pathname.startsWith("/index/")) {
+    return `/${pathname.slice("/index/".length)}`;
+  }
+  return pathname;
+};
+
+export const toCanonicalHtmlPathname = (pathname: string): string => {
+  const normalized = collapseSlashes(ensureLeadingSlash(pathname));
+  if (isFileLikePathname(normalized)) {
+    return normalized;
+  }
+
+  const withoutIndex = stripIndexSegment(trimTrailingSlash(normalized));
+  if (withoutIndex === "/") {
+    return "/";
+  }
+
+  return withoutIndex.endsWith("/") ? withoutIndex : `${withoutIndex}/`;
+};
+
+export const getRedirectForCanonicalHtmlPath = (
+  pathname: string
+): string | null => {
+  const normalized = collapseSlashes(ensureLeadingSlash(pathname));
+  if (isFileLikePathname(normalized)) {
+    return null;
+  }
+
+  const canonical = toCanonicalHtmlPathname(normalized);
+  return canonical === normalized ? null : canonical;
+};

package/src/site/urls.ts

@@ -0,0 +1,46 @@
+export const resolveAbsoluteUrl = (
+  baseUrl: string | undefined,
+  pathname: string
+): string | undefined => {
+  if (!baseUrl) {
+    return undefined;
+  }
+
+  // `new URL()` handles joining and normalization.
+  return new URL(pathname, baseUrl).toString();
+};
+
+export interface CanonicalUrlContext {
+  /**
+   * If true, prefer the request origin for canonicals so localhost doesn't emit
+   * production URLs during development.
+   */
+  isDev: boolean;
+  /**
+   * Origin of the current request (ex: "http://localhost:4000").
+   * Optional so build-time callers can omit it.
+   */
+  requestOrigin?: string;
+  /**
+   * Configured canonical base URL (typically `siteConfig.baseUrl`).
+   */
+  configuredBaseUrl?: string;
+}
+
+export const resolveCanonicalBaseUrl = (
+  context: CanonicalUrlContext
+): string | undefined => {
+  const { configuredBaseUrl, isDev, requestOrigin } = context;
+
+  if (isDev) {
+    return requestOrigin;
+  }
+
+  return configuredBaseUrl ?? requestOrigin;
+};
+
+export const resolveCanonicalUrl = (
+  context: CanonicalUrlContext,
+  pathname: string
+): string | undefined =>
+  resolveAbsoluteUrl(resolveCanonicalBaseUrl(context), pathname);

package/templates/default/README.md

@@ -0,0 +1,26 @@
+# **IDCMD_SITE_NAME**
+
+Everything you edit lives in `site/`.
+
+## Quickstart
+
+```bash
+bun install
+bun run dev
+```
+
+## Layout
+
+- `site/content/` markdown pages (`index.md` -> `/`, `about.md` -> `/about/`)
+- `site/styles/tailwind.css` Tailwind entrypoint (compiled to `site/public/styles.css`)
+- `site/public/` static assets
+- `site/server/routes/` file-based server routes (dev/server-host only)
+- `site/site.jsonc` site configuration
+
+## Deploy (Vercel static)
+
+```bash
+bun run build
+```
+
+This produces a static `dist/` directory for Vercel.

package/templates/default/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "__IDCMD_PACKAGE_NAME__",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "idcmd dev --port __IDCMD_DEV_PORT__",
+    "build": "idcmd build",
+    "preview": "idcmd preview",
+    "deploy": "idcmd deploy",
+    "check": "ultracite check && bun run typecheck && bun run test",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "fix": "ultracite fix"
+  },
+  "dependencies": {
+    "idcmd": "__IDCMD_IDCMD_VERSION__"
+  },
+  "devDependencies": {
+    "@tailwindcss/cli": "^4.1.18",
+    "@types/bun": "latest",
+    "@typescript/native-preview": "latest",
+    "lefthook": "^2.1.0",
+    "oxfmt": "^0.28.0",
+    "oxlint": "^1.43.0",
+    "tailwindcss": "^4.1.18",
+    "typescript": "^5",
+    "ultracite": "7.1.4"
+  }
+}

package/templates/default/site/client/layout.tsx

@@ -0,0 +1,2 @@
+export { renderLayout } from "idcmd/client";
+export type { LayoutProps } from "idcmd/client";

package/templates/default/site/client/right-rail.tsx

@@ -0,0 +1 @@
+export { RightRail } from "idcmd/client";

package/templates/default/site/client/search-page.tsx

@@ -0,0 +1 @@
+export { renderSearchPageContent } from "idcmd/client";

package/templates/default/site/content/404.md

@@ -0,0 +1,8 @@
+---
+title: Not Found
+hidden: true
+---
+
+# Not Found
+
+The page you are looking for does not exist.

package/templates/default/site/content/about.md

@@ -0,0 +1,10 @@
+---
+title: About
+group: main
+order: 2
+icon: info
+---
+
+# About
+
+This site is generated by `idcmd`.

package/templates/default/site/content/index.md

@@ -0,0 +1,10 @@
+---
+title: Home
+group: main
+order: 1
+icon: home
+---
+
+# **IDCMD_SITE_NAME**
+
+Edit markdown in `site/content/`.

package/templates/default/site/icons/file.svg

@@ -0,0 +1 @@
+<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>

package/templates/default/site/icons/home.svg

@@ -0,0 +1 @@
+<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="m3 9 9-7 9 7v11a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"/><polyline points="9 22 9 12 15 12 15 22"/></svg>

package/templates/default/site/icons/info.svg

@@ -0,0 +1 @@
+<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"><circle cx="12" cy="12" r="10"/><path d="M12 16v-4"/><path d="M12 8h.01"/></svg>