idcmd 0.0.10 → 0.0.12

package/src/cli/provider.ts

@@ -0,0 +1,36 @@
+export type Provider = "none" | "vercel" | "fly" | "railway";
+export type DeployProvider = Exclude<Provider, "none">;
+
+export interface ProviderFlags {
+  fly?: boolean;
+  railway?: boolean;
+  vercel?: boolean;
+}
+
+const DEPLOY_PROVIDERS: readonly DeployProvider[] = [
+  "vercel",
+  "fly",
+  "railway",
+];
+
+const isFlagEnabled = (value: boolean | undefined): boolean => value === true;
+
+const selectedProviders = (flags: ProviderFlags): DeployProvider[] =>
+  DEPLOY_PROVIDERS.filter((provider) => isFlagEnabled(flags[provider]));
+
+const formatProviderFlags = (providers: readonly DeployProvider[]): string =>
+  providers.map((provider) => `--${provider}`).join(" ");
+
+export const resolveProviderFromFlags = (flags: ProviderFlags): Provider => {
+  const selected = selectedProviders(flags);
+  if (selected.length > 1) {
+    throw new Error(
+      `Choose exactly one provider. Received ${formatProviderFlags(selected)}.`
+    );
+  }
+  return selected[0] ?? "none";
+};
+
+export const isDeployProvider = (
+  provider: Provider
+): provider is DeployProvider => provider !== "none";

package/src/render/layout.tsx

@@ -1,7 +1,4 @@
-/* eslint-disable react/no-danger */
-import type { JSX } from "preact";
-
-import { render } from "preact-render-to-string";
+/* eslint-disable react/jsx-key */
 
 import type { NavGroup, NavItem } from "../content/navigation";
 import type { ResolvedRightRailConfig } from "../site/config";
@@ -10,6 +7,8 @@ import type { TocItem } from "./toc";
 
 import { RightRail } from "./right-rail";
 
+const escapeText = (value: string): string => Bun.escapeHTML(value);
+
 export interface LayoutProps {
   title: string;
   siteName: string;
@@ -31,10 +30,7 @@ export interface LayoutProps {
 export type RenderLayout = (props: LayoutProps) => string;
 
 const Icon = ({ svg }: { svg: string }): JSX.Element => (
-  <span
-    class="inline-flex w-[18px] h-[18px]"
-    dangerouslySetInnerHTML={{ __html: svg }}
-  />
+  <span class="inline-flex w-[18px] h-[18px]">{svg}</span>
 );
 
 const isActiveLink = (item: NavItem, currentPath: string): boolean =>
@@ -59,7 +55,7 @@ const NavLink = ({
       class={`flex items-center gap-3 px-3 py-1.5 text-sm hover:text-sidebar-foreground transition-colors ${activeClass}`}
     >
       <Icon svg={item.iconSvg} />
-      <span>{item.title}</span>
+      <span>{escapeText(item.title)}</span>
     </a>
   );
 };
@@ -73,11 +69,11 @@ const NavGroupComponent = ({
 }): JSX.Element => (
   <div class="py-2">
     <div class="px-3 py-2 text-xs font-semibold text-muted-foreground uppercase tracking-wider">
-      {group.label}
+      {escapeText(group.label)}
     </div>
     <nav class="space-y-1">
       {group.items.map((item) => (
-        <NavLink key={item.href} item={item} currentPath={currentPath} />
+        <NavLink item={item} currentPath={currentPath} />
       ))}
     </nav>
   </div>
@@ -100,16 +96,12 @@ const Sidebar = ({
         data-prefetch="hover"
       >
         <span class="text-muted-foreground">~/</span>
-        {siteName}
+        {escapeText(siteName)}
       </a>
     </div>
     <div class="sidebar-content">
       {navigation.map((group) => (
-        <NavGroupComponent
-          key={group.id}
-          group={group}
-          currentPath={currentPath}
-        />
+        <NavGroupComponent group={group} currentPath={currentPath} />
       ))}
     </div>
   </aside>
@@ -121,19 +113,20 @@ const SearchForm = ({ query }: { query?: string }): JSX.Element => (
     action="/search/"
     class="flex w-full items-center"
     role="search"
-    noValidate
+    novalidate
   >
-    <label htmlFor="site-search" class="sr-only">
+    {/* eslint-disable-next-line jsx-a11y/label-has-associated-control */}
+    <label for="site-search" class="sr-only">
       Search pages
     </label>
     <input
       id="site-search"
       name="q"
       type="search"
-      autoComplete="off"
+      autocomplete="off"
       spellcheck={false}
       placeholder="Search..."
-      defaultValue={query ?? ""}
+      value={escapeText(query ?? "")}
       class="w-full border-b border-input bg-transparent px-1 py-1.5 text-sm placeholder:text-muted-foreground focus:border-foreground focus:outline-none transition-colors"
     />
   </form>
@@ -155,7 +148,7 @@ const TopNavbar = ({
           data-prefetch="hover"
         >
           <span class="text-muted-foreground">~/</span>
-          {siteName}
+          {escapeText(siteName)}
         </a>
         <div class="not-prose w-full max-w-xs ml-auto">
           <SearchForm query={query} />
@@ -183,14 +176,16 @@ const DocumentHead = ({
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>{title}</title>
-    {description ? <meta name="description" content={description} /> : null}
+    <title>{escapeText(title)}</title>
+    {description ? (
+      <meta name="description" content={escapeText(description)} />
+    ) : null}
     {canonicalUrl ? <link rel="canonical" href={canonicalUrl} /> : null}
     <link rel="preconnect" href="https://fonts.googleapis.com" />
     <link
       rel="preconnect"
       href="https://fonts.gstatic.com"
-      crossOrigin="anonymous"
+      crossorigin="anonymous"
     />
     <link
       href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:ital,wght@0,100..800;1,100..800&display=swap"
@@ -269,8 +264,10 @@ const DocumentBody = ({
         <div class="mx-auto flex w-full max-w-6xl items-start gap-10">
           <article
             class={`prose min-w-0 flex-1${currentPath === "/" ? " prose-home" : ""}`}
-            dangerouslySetInnerHTML={{ __html: content }}
-          />
+          >
+            {/* content is pre-rendered markdown HTML */}
+            {content}
+          </article>
           {shouldShowRightRail ? (
             <RightRailComponent
               canonicalUrl={canonicalUrl}
@@ -282,12 +279,12 @@ const DocumentBody = ({
         </div>
       </main>
       <footer class="site-footer">
-        Built with Preact SSR + Tailwind &nbsp;|&nbsp; Zero JavaScript on
-        content pages
+        Built with idcmd SSR + Tailwind &nbsp;|&nbsp; Zero JavaScript on content
+        pages
       </footer>
     </div>
     {scriptPaths.map((scriptPath) => (
-      <script key={scriptPath} defer src={scriptPath} />
+      <script defer src={scriptPath} />
     ))}
   </body>
 );
@@ -344,4 +341,4 @@ const Layout = ({
 };
 
 export const renderLayout: RenderLayout = (props) =>
-  `<!DOCTYPE html>${render(<Layout {...props} />)}`;
+  `<!DOCTYPE html>${<Layout {...props} />}`;

package/src/render/right-rail.tsx

@@ -1,8 +1,10 @@
-import type { JSX } from "preact";
+/* eslint-disable react/jsx-key */
 
 import type { ResolvedRightRailConfig } from "../site/config";
 import type { TocItem } from "./toc";
 
+const escapeText = (value: string): string => Bun.escapeHTML(value);
+
 const CaretDownIcon = (): JSX.Element => (
   <svg
     width="16"
@@ -171,13 +173,13 @@ const OnThisPage = ({ items }: { items: TocItem[] }): JSX.Element => (
       <div class="toc-scroll min-h-0 flex-1" data-toc-scroll-container="1">
         <ul class="space-y-2 text-sm text-muted-foreground">
           {items.map((item) => (
-            <li key={item.id} class={item.level >= 3 ? "pl-3" : ""}>
+            <li class={item.level >= 3 ? "pl-3" : ""}>
               <a
                 href={`#${encodeURIComponent(item.id)}`}
                 class="hover:text-foreground"
                 data-toc-link="1"
               >
-                {item.text}
+                {escapeText(item.text)}
               </a>
             </li>
           ))}

package/src/search/index.ts

@@ -11,19 +11,16 @@ import {
   slugFromContentFile,
 } from "../content/paths";
 
-export const SEARCH_INDEX_VERSION = 1 as const;
-
-export interface SearchIndexDocumentV1 {
+export interface SearchIndexDocument {
   url: string;
   title: string;
   description: string;
   body: string;
 }
 
-export interface SearchIndexV1 {
-  version: typeof SEARCH_INDEX_VERSION;
+export interface SearchIndex {
   generatedAt: string;
-  documents: SearchIndexDocumentV1[];
+  documents: SearchIndexDocument[];
 }
 
 const SEARCH_INDEX_PATH = "public/search-index.json";
@@ -67,7 +64,7 @@ const isEligibleDocument = (
   hidden: boolean | undefined
 ): boolean => !hidden && slug !== "404";
 
-const sortDocuments = (documents: SearchIndexDocumentV1[]): void => {
+const sortDocuments = (documents: SearchIndexDocument[]): void => {
   documents.sort((a, b) => {
     if (a.url === "/") {
       return -1;
@@ -84,7 +81,7 @@ const buildDocumentFromFile = async (
   bodyMaxChars: number,
   contentDir: string,
   siteConfig: SiteConfig
-): Promise<SearchIndexDocumentV1 | null> => {
+): Promise<SearchIndexDocument | null> => {
   const slug = slugFromContentFile(file);
   const markdown = await Bun.file(`${contentDir}/${file}`).text();
   const parsed = parseFrontmatter(markdown);
@@ -117,11 +114,11 @@ export interface GenerateSearchIndexOptions {
 
 export const generateSearchIndexFromContent = async (
   options: GenerateSearchIndexOptions
-): Promise<SearchIndexV1> => {
+): Promise<SearchIndex> => {
   const { bodyMaxChars = DEFAULT_BODY_MAX_CHARS, siteConfig } = options;
   const generatedAt = options.generatedAt ?? new Date().toISOString();
 
-  const documents: SearchIndexDocumentV1[] = [];
+  const documents: SearchIndexDocument[] = [];
   const contentDir = await getContentDir();
 
   for await (const file of scanContentFiles()) {
@@ -141,13 +138,12 @@ export const generateSearchIndexFromContent = async (
   return {
     documents,
     generatedAt,
-    version: SEARCH_INDEX_VERSION,
   };
 };
 
-const isSearchIndexDocumentV1 = (
+const isSearchIndexDocument = (
   value: unknown
-): value is SearchIndexDocumentV1 => {
+): value is SearchIndexDocument => {
   if (!value || typeof value !== "object") {
     return false;
   }
@@ -161,28 +157,27 @@ const isSearchIndexDocumentV1 = (
   );
 };
 
-const isSearchIndexV1 = (value: unknown): value is SearchIndexV1 => {
+const isSearchIndex = (value: unknown): value is SearchIndex => {
   if (!value || typeof value !== "object") {
     return false;
   }
 
   const record = value as Record<string, unknown>;
   return (
-    record.version === SEARCH_INDEX_VERSION &&
     isNonEmptyString(record.generatedAt) &&
     Array.isArray(record.documents) &&
-    record.documents.every((doc) => isSearchIndexDocumentV1(doc))
+    record.documents.every((doc) => isSearchIndexDocument(doc))
   );
 };
 
-let indexCache: SearchIndexV1 | null = null;
+let indexCache: SearchIndex | null = null;
 
 export interface LoadSearchIndexOptions {
   forceRefresh?: boolean;
   siteConfig: SiteConfig;
 }
 
-const tryLoadSearchIndexFromDisk = async (): Promise<SearchIndexV1 | null> => {
+const tryLoadSearchIndexFromDisk = async (): Promise<SearchIndex | null> => {
   const file = Bun.file(SEARCH_INDEX_PATH);
   if (!(await file.exists())) {
     return null;
@@ -190,7 +185,7 @@ const tryLoadSearchIndexFromDisk = async (): Promise<SearchIndexV1 | null> => {
 
   try {
     const parsed = (await file.json()) as unknown;
-    return isSearchIndexV1(parsed) ? parsed : null;
+    return isSearchIndex(parsed) ? parsed : null;
   } catch {
     return null;
   }
@@ -198,7 +193,7 @@ const tryLoadSearchIndexFromDisk = async (): Promise<SearchIndexV1 | null> => {
 
 export const loadSearchIndex = async (
   options: LoadSearchIndexOptions
-): Promise<SearchIndexV1> => {
+): Promise<SearchIndex> => {
   const { forceRefresh = false, siteConfig } = options;
   if (indexCache && !forceRefresh) {
     return indexCache;
@@ -216,7 +211,7 @@ export const loadSearchIndex = async (
 };
 
 const getScopeHaystack = (
-  document: SearchIndexDocumentV1,
+  document: SearchIndexDocument,
   scope: SearchScope
 ): string => {
   if (scope === "title") {
@@ -231,7 +226,7 @@ const getScopeHaystack = (
 };
 
 const matchesAllTokens = (
-  document: SearchIndexDocumentV1,
+  document: SearchIndexDocument,
   tokens: readonly string[],
   scope: SearchScope
 ): boolean => {
@@ -239,14 +234,14 @@ const matchesAllTokens = (
   return tokens.every((token) => haystack.includes(token));
 };
 
-const toSearchResult = (document: SearchIndexDocumentV1): SearchResult => ({
+const toSearchResult = (document: SearchIndexDocument): SearchResult => ({
   description: document.description,
   slug: document.url,
   title: document.title,
 });
 
 export const search = (
-  index: SearchIndexV1,
+  index: SearchIndex,
   query: string,
   scope: SearchScope
 ): SearchResult[] => {

package/src/search/page.tsx

@@ -1,9 +1,9 @@
-import type { JSX } from "preact";
-
-import { render as renderToString } from "preact-render-to-string";
+/* eslint-disable react/jsx-key */
 
 import type { SearchResult } from "./contract";
 
+const escapeText = (value: string): string => Bun.escapeHTML(value);
+
 export interface TopPageLink {
   href: string;
   title: string;
@@ -24,9 +24,11 @@ const ResultItem = ({ result }: { result: SearchResult }): JSX.Element => (
       href={result.slug}
       class="font-medium underline decoration-border underline-offset-4"
     >
-      {result.title}
+      {escapeText(result.title)}
     </a>
-    <p class="mt-1 text-sm text-muted-foreground">{result.description}</p>
+    <p class="mt-1 text-sm text-muted-foreground">
+      {escapeText(result.description)}
+    </p>
   </li>
 );
 
@@ -44,12 +46,12 @@ const EmptyState = ({
         <p class="mt-4 font-medium text-foreground">Popular pages</p>
         <ul class="mt-2 space-y-1">
           {topPages.map((page) => (
-            <li key={page.href}>
+            <li>
               <a
                 href={page.href}
                 class="underline decoration-border underline-offset-4"
               >
-                {page.title}
+                {escapeText(page.title)}
               </a>
             </li>
           ))}
@@ -74,8 +76,8 @@ const SearchPage = ({
       {showResults ? (
         <p class="mt-2 text-sm text-muted-foreground">
           {results.length === 0
-            ? `No matches for "${trimmed}".`
-            : `Found ${results.length} result(s) for "${trimmed}".`}
+            ? `No matches for "${escapeText(trimmed)}".`
+            : `Found ${results.length} result(s) for "${escapeText(trimmed)}".`}
         </p>
       ) : (
         <div class="mt-2">
@@ -86,7 +88,7 @@ const SearchPage = ({
       {showResults ? (
         <ul class="mt-4 space-y-2">
           {results.map((result) => (
-            <ResultItem key={result.slug} result={result} />
+            <ResultItem result={result} />
           ))}
         </ul>
       ) : null}
@@ -95,4 +97,4 @@ const SearchPage = ({
 };
 
 export const renderSearchPageContent: RenderSearchPageContent = (props) =>
-  renderToString(<SearchPage {...props} />);
+  `${<SearchPage {...props} />}`;

package/src/server/headers.ts

@@ -1,10 +1,29 @@
-export const createHtmlCacheHeaders = (isDev: boolean): HeadersInit => ({
+import type { ResolvedCachePolicy } from "../site/cache";
+
+const combineCacheControl = (args: {
+  browserCacheControl: string;
+  edgeCacheControl: string | null;
+}): string =>
+  args.edgeCacheControl
+    ? `${args.browserCacheControl}, ${args.edgeCacheControl}`
+    : args.browserCacheControl;
+
+export const createHtmlCacheHeaders = (
+  isDev: boolean,
+  cachePolicy: ResolvedCachePolicy
+): HeadersInit => ({
   "Cache-Control": isDev
     ? "no-cache"
-    : "s-maxage=60, stale-while-revalidate=3600",
+    : combineCacheControl({
+        browserCacheControl: cachePolicy.html.browserCacheControl,
+        edgeCacheControl: cachePolicy.html.edgeCacheControl,
+      }),
   "Content-Type": "text/html; charset=utf-8",
 });
 
-export const createStaticCacheHeaders = (isDev: boolean): HeadersInit => ({
-  "Cache-Control": isDev ? "no-cache" : "public, max-age=31536000, immutable",
+export const createStaticCacheHeaders = (
+  isDev: boolean,
+  cachePolicy: ResolvedCachePolicy
+): HeadersInit => ({
+  "Cache-Control": isDev ? "no-cache" : cachePolicy.static.cacheControl,
 });

package/src/server/user-routes.ts

@@ -141,7 +141,7 @@ const loadOneRoute = async (
   const pathname = pathnameFromRouteRelativePath(relativeFile);
   if (hasUnsupportedDynamicSegment(pathname)) {
     throw new Error(
-      `Unsupported dynamic route segment in ${routesDir}/${relativeFile} (computed pathname: ${pathname}). V1 does not support [param] or :param routes.`
+      `Unsupported dynamic route segment in ${routesDir}/${relativeFile} (computed pathname: ${pathname}). Dynamic [param] and :param routes are not supported.`
     );
   }
 

package/src/server.ts

@@ -15,6 +15,8 @@ import {
 import { createLiveReload } from "./server/live-reload";
 import { serveStaticFile } from "./server/static";
 import { handleUserRouteRequest } from "./server/user-routes";
+import { resolveCachePolicy } from "./site/cache";
+import { loadSiteConfig } from "./site/config";
 import {
   getRedirectForCanonicalHtmlPath,
   isFileLikePathname,
@@ -30,9 +32,12 @@ 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 HEALTHCHECK_PATH = "/health";
 
-const cacheHeaders = createHtmlCacheHeaders(isDev);
-const staticCacheHeaders = createStaticCacheHeaders(isDev);
+const siteConfig = await loadSiteConfig();
+const cachePolicy = resolveCachePolicy(siteConfig.cache);
+const cacheHeaders = createHtmlCacheHeaders(isDev, cachePolicy);
+const staticCacheHeaders = createStaticCacheHeaders(isDev, cachePolicy);
 
 const withQueryString = (pathname: string, search: string): string =>
   search ? `${pathname}${search}` : pathname;
@@ -74,6 +79,20 @@ const handleLlmsTxt = async (path: string): Promise<Response | undefined> => {
   });
 };
 
+const handleHealthRequest = (path: string): Response | undefined => {
+  if (path !== HEALTHCHECK_PATH) {
+    return undefined;
+  }
+
+  return new Response("ok", {
+    headers: {
+      "Cache-Control": "no-cache",
+      "Content-Type": "text/plain; charset=utf-8",
+    },
+    status: 200,
+  });
+};
+
 const handleMarkdownRequest = async (
   path: string
 ): Promise<Response | undefined> => {
@@ -202,6 +221,7 @@ const handleRequest = async (
 
   return (
     liveReloadUpgrade ??
+    handleHealthRequest(path) ??
     (await handleLlmsTxt(path)) ??
     (await handleRobotsTxt(url, seoEnv)) ??
     (await handleSitemapXml(url, seoEnv)) ??

package/src/site/cache.ts

@@ -0,0 +1,108 @@
+import { z } from "zod";
+
+const MAX_EDGE_CACHE_SECONDS = 7 * 24 * 60 * 60;
+const MAX_STALE_SECONDS = 30 * 24 * 60 * 60;
+
+const HTML_REVALIDATE_CACHE_CONTROL = "public, max-age=0, must-revalidate";
+const STATIC_REVALIDATE_CACHE_CONTROL = "public, max-age=0, must-revalidate";
+const STATIC_IMMUTABLE_CACHE_CONTROL = "public, max-age=31536000, immutable";
+const NO_STORE_CACHE_CONTROL = "no-store";
+
+export const CachePresetSchema = z.enum(["fresh", "balanced", "static"]);
+export type CachePreset = z.infer<typeof CachePresetSchema>;
+
+export const CacheHtmlConfigSchema = z
+  .object({
+    sMaxAgeSeconds: z
+      .number()
+      .int()
+      .min(0)
+      .max(MAX_EDGE_CACHE_SECONDS)
+      .optional(),
+    staleWhileRevalidateSeconds: z
+      .number()
+      .int()
+      .min(0)
+      .max(MAX_STALE_SECONDS)
+      .optional(),
+  })
+  .strict();
+export type CacheHtmlConfig = z.infer<typeof CacheHtmlConfigSchema>;
+
+export const CacheConfigSchema = z
+  .object({
+    html: CacheHtmlConfigSchema.optional(),
+    preset: CachePresetSchema.optional(),
+  })
+  .strict();
+export type CacheConfig = z.infer<typeof CacheConfigSchema>;
+
+export interface ResolvedCachePolicy {
+  html: {
+    browserCacheControl: string;
+    edgeCacheControl: string | null;
+  };
+  preset: CachePreset;
+  static: {
+    cacheControl: string;
+  };
+}
+
+interface HtmlEdgePolicy {
+  sMaxAgeSeconds: number;
+  staleWhileRevalidateSeconds: number;
+}
+
+const DEFAULT_HTML_EDGE_POLICY: HtmlEdgePolicy = {
+  sMaxAgeSeconds: 60,
+  staleWhileRevalidateSeconds: 3600,
+};
+const DEFAULT_PRESET: CachePreset = "static";
+
+const formatEdgeCacheControl = (policy: HtmlEdgePolicy): string =>
+  `s-maxage=${String(policy.sMaxAgeSeconds)}, stale-while-revalidate=${String(policy.staleWhileRevalidateSeconds)}`;
+
+const resolveHtmlEdgePolicy = (
+  config: CacheConfig | undefined
+): HtmlEdgePolicy => ({
+  sMaxAgeSeconds:
+    config?.html?.sMaxAgeSeconds ?? DEFAULT_HTML_EDGE_POLICY.sMaxAgeSeconds,
+  staleWhileRevalidateSeconds:
+    config?.html?.staleWhileRevalidateSeconds ??
+    DEFAULT_HTML_EDGE_POLICY.staleWhileRevalidateSeconds,
+});
+
+const resolvePreset = (config: CacheConfig | undefined): CachePreset =>
+  config?.preset ?? DEFAULT_PRESET;
+
+export const resolveCachePolicy = (
+  config?: CacheConfig
+): ResolvedCachePolicy => {
+  const preset = resolvePreset(config);
+
+  if (preset === "fresh") {
+    return {
+      html: {
+        browserCacheControl: NO_STORE_CACHE_CONTROL,
+        edgeCacheControl: null,
+      },
+      preset,
+      static: { cacheControl: NO_STORE_CACHE_CONTROL },
+    };
+  }
+
+  const edgePolicy = resolveHtmlEdgePolicy(config);
+  return {
+    html: {
+      browserCacheControl: HTML_REVALIDATE_CACHE_CONTROL,
+      edgeCacheControl: formatEdgeCacheControl(edgePolicy),
+    },
+    preset,
+    static: {
+      cacheControl:
+        preset === "static"
+          ? STATIC_IMMUTABLE_CACHE_CONTROL
+          : STATIC_REVALIDATE_CACHE_CONTROL,
+    },
+  };
+};