idcmd 0.0.10 → 0.0.12

package/src/site/config.ts

@@ -1,5 +1,9 @@
 import { ZodError, z } from "zod";
 
+import type { CacheConfig } from "./cache";
+
+import { CacheConfigSchema } from "./cache";
+
 export const SearchScopeSchema = z.enum([
   "full",
   "title",
@@ -64,6 +68,7 @@ export type GroupConfig = z.infer<typeof GroupConfigSchema>;
 export const SiteConfigSchema = z
   .object({
     baseUrl: z.string().url().optional(),
+    cache: CacheConfigSchema.optional(),
     description: z.string(),
     groups: z.array(GroupConfigSchema).optional(),
     name: z.string().min(1),
@@ -146,12 +151,31 @@ const normalizeBaseUrl = (baseUrl: string): string | undefined => {
   }
 };
 
-const resolveBaseUrlFromEnv = (): string | undefined => {
+const resolveExplicitBaseUrlFromEnv = (): string | undefined => {
   const explicit = process.env.SITE_BASE_URL;
   if (explicit) {
     return normalizeBaseUrl(explicit);
   }
+  return undefined;
+};
+
+const resolveRailwayBaseUrlFromEnv = (): string | undefined => {
+  const railwayDomain = process.env.RAILWAY_PUBLIC_DOMAIN;
+  if (railwayDomain) {
+    return normalizeBaseUrl(`https://${railwayDomain}`);
+  }
+  return undefined;
+};
+
+const resolveFlyBaseUrlFromEnv = (): string | undefined => {
+  const flyApp = process.env.FLY_APP_NAME;
+  if (flyApp) {
+    return normalizeBaseUrl(`https://${flyApp}.fly.dev`);
+  }
+  return undefined;
+};
 
+const resolveVercelBaseUrlFromEnv = (): string | undefined => {
   // Vercel provides hostnames without protocol.
   const vercelUrl =
     process.env.VERCEL_URL ??
@@ -161,10 +185,15 @@ const resolveBaseUrlFromEnv = (): string | undefined => {
   if (vercelUrl) {
     return normalizeBaseUrl(`https://${vercelUrl}`);
   }
-
   return undefined;
 };
 
+const resolveBaseUrlFromEnv = (): string | undefined =>
+  resolveExplicitBaseUrlFromEnv() ??
+  resolveRailwayBaseUrlFromEnv() ??
+  resolveFlyBaseUrlFromEnv() ??
+  resolveVercelBaseUrlFromEnv();
+
 const resolveBaseUrl = (baseUrl: string | undefined): string | undefined => {
   const normalizedConfigUrl = baseUrl ? normalizeBaseUrl(baseUrl) : undefined;
   const envUrl = resolveBaseUrlFromEnv();
@@ -190,7 +219,11 @@ const formatSiteConfigZodError = (
   return `${configPath} validation failed:\n${lines.join("\n")}`;
 };
 
-const DEFAULT_SITE_CONFIG: SiteConfig = { description: "", name: "idcmd" };
+const DEFAULT_SITE_CONFIG: SiteConfig = {
+  cache: { preset: "static" },
+  description: "",
+  name: "idcmd",
+};
 
 const parseSiteConfigJsonc = (configPath: string, text: string): unknown => {
   try {
@@ -229,8 +262,17 @@ export const loadSiteConfig = async (): Promise<SiteConfig> => {
   const text = await file.text();
   const raw = parseSiteConfigJsonc(configPath, text);
   const parsed = parseSiteConfigUnknown(configPath, raw);
-  return { ...parsed, baseUrl: resolveBaseUrl(parsed.baseUrl) };
+  return {
+    ...parsed,
+    baseUrl: resolveBaseUrl(parsed.baseUrl),
+    cache: resolveCacheConfig(parsed.cache),
+  };
 };
 
 export const getSearchScope = (siteConfig: SiteConfig): SearchScope =>
   siteConfig.search?.scope ?? "full";
+
+const resolveCacheConfig = (cache: CacheConfig | undefined): CacheConfig => ({
+  html: cache?.html,
+  preset: cache?.preset ?? "static",
+});

package/templates/default/.github/workflows/ci.yml

@@ -19,6 +19,3 @@ jobs:
         run: bun install
       - name: Run checks
         run: bun run check
-      - name: Run smoke
-        timeout-minutes: 15
-        run: bun run smoke

package/templates/default/README.md

@@ -11,11 +11,10 @@ bun install
 bun run dev
 ```
 
-## CI Smoke
+## Validation
 
 ```bash
 bun run check
-bun run smoke
 ```
 
 ## Layout
@@ -43,10 +42,12 @@ idcmd client update runtime --yes
 These commands copy the latest baseline implementations from `idcmd` into `src/ui/` and `src/runtime/`.
 Runtime files in `src/runtime/` are compiled automatically by `idcmd dev` and `idcmd build`.
 
-## Deploy (Vercel static)
+## Deploy
 
 ```bash
-bun run build
+idcmd deploy --vercel
+idcmd deploy --fly
+idcmd deploy --railway
 ```
 
-This produces a static `public/` directory for Vercel.
+Use one provider flag at a time to generate deployment files.

package/templates/default/package.json

@@ -8,7 +8,6 @@
     "preview": "idcmd preview",
     "deploy": "idcmd deploy",
     "check": "bun run scripts/check.ts",
-    "smoke": "bun run scripts/smoke.ts",
     "test": "bun test",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "fix": "ultracite fix"

package/templates/default/scripts/check.ts

@@ -32,7 +32,6 @@ const LINT_TARGETS = [
   "README.md",
   "package.json",
   "tsconfig.json",
-  "vercel.json",
   ".oxlintrc.json",
   ".oxfmtrc.jsonc",
   "scripts",

package/templates/default/site.jsonc

@@ -1,6 +1,16 @@
 {
   "name": "__IDCMD_SITE_NAME__",
   "description": "__IDCMD_SITE_DESCRIPTION__",
+  "cache": {
+    // "fresh" | "balanced" | "static"
+    "preset": "static",
+
+    // Optional HTML edge cache overrides
+    // "html": {
+    //   "sMaxAgeSeconds": 60,
+    //   "staleWhileRevalidateSeconds": 3600,
+    // },
+  },
   "baseUrl": "__IDCMD_SITE_BASE_URL__",
   "groups": [{ "id": "main", "label": "Navigation", "order": 1 }],
   "search": {

package/templates/default/src/server.ts

@@ -1,4 +1,4 @@
 // Optional: this file is here as the obvious place to put server-side code.
-// V1 runs the built-in idcmd server; add custom endpoints via `src/routes/**`.
+// Runs the built-in idcmd server; add custom endpoints via `src/routes/**`.
 
 export const serverPlaceholder = true;

package/templates/default/src/ui/layout.tsx

@@ -1,18 +1,15 @@
-import type { LayoutProps } from "idcmd/client";
-/* eslint-disable react/no-danger */
-import type { JSX } from "preact";
+/* eslint-disable react/jsx-key */
 
-import { render } from "preact-render-to-string";
+import type { LayoutProps } from "idcmd/client";
 
 import { RightRail } from "./right-rail";
 
 type NavItem = LayoutProps["navigation"][number]["items"][number];
 
+const escapeText = (value: string): string => Bun.escapeHTML(value);
+
 const Icon = ({ svg }: { svg: string }): JSX.Element => (
-  <span
-    class="inline-flex h-[18px] w-[18px]"
-    dangerouslySetInnerHTML={{ __html: svg }}
-  />
+  <span class="inline-flex h-[18px] w-[18px]">{svg}</span>
 );
 
 const isActiveLink = (item: NavItem, currentPath: string): boolean =>
@@ -36,19 +33,18 @@ const Sidebar = ({
         data-prefetch="hover"
       >
         <span class="text-muted-foreground">~/</span>
-        {siteName}
+        {escapeText(siteName)}
       </a>
     </div>
     <div class="sidebar-content">
       {navigation.map((group) => (
-        <div key={group.id} class="py-2">
+        <div class="py-2">
           <p class="px-3 py-2 text-xs font-semibold uppercase tracking-wider text-muted-foreground">
-            {group.label}
+            {escapeText(group.label)}
           </p>
           <nav class="space-y-1">
             {group.items.map((item) => (
               <a
-                key={item.href}
                 href={item.href}
                 data-prefetch="hover"
                 class={`flex items-center gap-3 px-3 py-1.5 text-sm transition-colors hover:text-sidebar-foreground ${
@@ -58,7 +54,7 @@ const Sidebar = ({
                 }`}
               >
                 <Icon svg={item.iconSvg} />
-                <span>{item.title}</span>
+                <span>{escapeText(item.title)}</span>
               </a>
             ))}
           </nav>
@@ -74,19 +70,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>
@@ -108,7 +105,7 @@ const TopNavbar = ({
           data-prefetch="hover"
         >
           <span class="text-muted-foreground">~/</span>
-          {siteName}
+          {escapeText(siteName)}
         </a>
         <div class="not-prose ml-auto w-full max-w-xs">
           <SearchForm query={query} />
@@ -170,14 +167,16 @@ const Layout = ({
       <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"
@@ -208,8 +207,10 @@ const Layout = ({
                 class={`prose min-w-0 flex-1${
                   currentPath === "/" ? " prose-home" : ""
                 }`}
-                dangerouslySetInnerHTML={{ __html: content }}
-              />
+              >
+                {/* content is pre-rendered markdown HTML */}
+                {content}
+              </article>
               {shouldShowRightRail ? (
                 <RightRail
                   canonicalUrl={canonicalUrl}
@@ -221,12 +222,12 @@ const Layout = ({
             </div>
           </main>
           <footer class="site-footer">
-            Built with Preact SSR + Tailwind &nbsp;|&nbsp; Zero JavaScript on
+            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>
     </html>
@@ -234,4 +235,4 @@ const Layout = ({
 };
 
 export const renderLayout = (props: LayoutProps): string =>
-  `<!DOCTYPE html>${render(<Layout {...props} />)}`;
+  `<!DOCTYPE html>${<Layout {...props} />}`;

package/templates/default/src/ui/right-rail.tsx

@@ -1,5 +1,8 @@
+/* eslint-disable react/jsx-key */
+
 import type { RightRailProps } from "idcmd/client";
-import type { JSX } from "preact";
+
+const escapeText = (value: string): string => Bun.escapeHTML(value);
 
 const CaretDownIcon = (): JSX.Element => (
   <svg
@@ -173,13 +176,13 @@ const OnThisPage = ({
       <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/templates/default/src/ui/search-page.tsx

@@ -1,7 +1,8 @@
+/* eslint-disable react/jsx-key */
+
 import type { SearchPageProps } from "idcmd/client";
-import type { JSX } from "preact";
 
-import { render as renderToString } from "preact-render-to-string";
+const escapeText = (value: string): string => Bun.escapeHTML(value);
 
 const ResultItem = ({
   result,
@@ -13,9 +14,11 @@ const ResultItem = ({
       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>
 );
 
@@ -33,12 +36,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>
           ))}
@@ -63,8 +66,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">
@@ -75,7 +78,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}
@@ -84,4 +87,4 @@ const SearchPage = ({
 };
 
 export const renderSearchPageContent = (props: SearchPageProps): string =>
-  renderToString(<SearchPage {...props} />);
+  `${<SearchPage {...props} />}`;

package/templates/default/tsconfig.json

@@ -1,7 +1,7 @@
 {
   "compilerOptions": {
     "jsx": "react-jsx",
-    "jsxImportSource": "preact",
+    "jsxImportSource": "@kitajs/html",
     "lib": ["ESNext", "DOM", "DOM.Iterable"],
     "target": "ESNext",
     "module": "Preserve",

package/templates/default/scripts/smoke.ts

@@ -1,223 +0,0 @@
-interface CommandResult {
-  code: number;
-  stderr: string;
-  stdout: string;
-}
-
-const BASE_URL = process.env.IDCMD_SMOKE_BASE_URL ?? "http://127.0.0.1:4000";
-const CURL_MAX_TIME_SECONDS = "5";
-const READY_TIMEOUT_MS = 60_000;
-const READY_INTERVAL_MS = 500;
-const SHUTDOWN_TIMEOUT_MS = 5000;
-
-const delay = (ms: number): Promise<void> => Bun.sleep(ms);
-
-const runCommand = async (command: string[]): Promise<CommandResult> => {
-  const proc = Bun.spawn(command, {
-    cwd: process.cwd(),
-    stderr: "pipe",
-    stdout: "pipe",
-  });
-  const [stdout, stderr, code] = await Promise.all([
-    new Response(proc.stdout).text(),
-    new Response(proc.stderr).text(),
-    proc.exited,
-  ]);
-  return { code, stderr, stdout };
-};
-
-const runCurl = (path: string): Promise<CommandResult> =>
-  runCommand([
-    "curl",
-    "-fsS",
-    "--max-time",
-    CURL_MAX_TIME_SECONDS,
-    `${BASE_URL}${path}`,
-  ]);
-
-const assertCommandOk = (label: string, result: CommandResult): void => {
-  if (result.code === 0) {
-    return;
-  }
-  throw new Error(
-    [
-      `${label} failed with exit code ${String(result.code)}.`,
-      "stdout:",
-      result.stdout.trim() || "(empty)",
-      "stderr:",
-      result.stderr.trim() || "(empty)",
-    ].join("\n")
-  );
-};
-
-const expectIncludes = (args: {
-  haystack: string;
-  label: string;
-  needle: string;
-}): void => {
-  if (args.haystack.includes(args.needle)) {
-    return;
-  }
-  throw new Error(`Expected ${args.label} to include ${args.needle}.`);
-};
-
-const waitForReady = async (): Promise<void> => {
-  const startedAt = Date.now();
-  let lastFailure = "(no attempts yet)";
-
-  while (Date.now() - startedAt < READY_TIMEOUT_MS) {
-    const ready = await runCurl("/");
-    if (ready.code === 0) {
-      return;
-    }
-    lastFailure = ready.stderr.trim() || ready.stdout.trim() || "curl failed";
-    await delay(READY_INTERVAL_MS);
-  }
-
-  throw new Error(
-    `dev server did not become ready within ${String(
-      READY_TIMEOUT_MS
-    )}ms. Last curl failure: ${lastFailure}`
-  );
-};
-
-const shutdownDev = async (
-  proc: ReturnType<typeof Bun.spawn>
-): Promise<void> => {
-  try {
-    proc.kill("SIGTERM");
-  } catch {
-    return;
-  }
-
-  const didExit = await Promise.race([
-    proc.exited.then(() => true),
-    delay(SHUTDOWN_TIMEOUT_MS).then(() => false),
-  ]);
-  if (!didExit) {
-    try {
-      proc.kill("SIGKILL");
-    } catch {
-      // ignore
-    }
-    await proc.exited;
-  }
-};
-
-const assertHomeResponse = async (): Promise<void> => {
-  const home = await runCurl("/");
-  assertCommandOk("curl /", home);
-  expectIncludes({ haystack: home.stdout, label: "/", needle: "<html" });
-};
-
-const assertAboutResponse = async (): Promise<void> => {
-  const about = await runCurl("/about/");
-  assertCommandOk("curl /about/", about);
-  if (!about.stdout.includes("# About") && !about.stdout.includes(">About<")) {
-    throw new Error("Expected /about/ response to include About heading.");
-  }
-};
-
-const assertLlmsResponse = async (): Promise<void> => {
-  const llms = await runCurl("/llms.txt");
-  assertCommandOk("curl /llms.txt", llms);
-  if (llms.stdout.trim().length === 0 || !llms.stdout.includes("about.md")) {
-    throw new Error("Expected /llms.txt to be non-empty and include about.md.");
-  }
-};
-
-const assertApiResponse = async (): Promise<void> => {
-  const api = await runCurl("/api/hello");
-  assertCommandOk("curl /api/hello", api);
-  const payload = JSON.parse(api.stdout) as { message?: string; ok?: boolean };
-  if (payload.ok !== true || payload.message !== "Hello from idcmd route!") {
-    throw new Error("Expected /api/hello payload to match template route.");
-  }
-};
-
-const runSmokeChecks = async (): Promise<void> => {
-  await assertHomeResponse();
-  await assertAboutResponse();
-  await assertLlmsResponse();
-  await assertApiResponse();
-};
-
-const runProjectCheck = async (): Promise<void> => {
-  const check = await runCommand([process.execPath, "run", "check"]);
-  assertCommandOk("bun run check", check);
-};
-
-const startDev = (): {
-  devProc: ReturnType<typeof Bun.spawn>;
-  devStderr: Promise<string>;
-  devStdout: Promise<string>;
-} => {
-  const devProc = Bun.spawn([process.execPath, "run", "dev"], {
-    cwd: process.cwd(),
-    stderr: "pipe",
-    stdout: "pipe",
-  });
-  return {
-    devProc,
-    devStderr: new Response(devProc.stderr).text(),
-    devStdout: new Response(devProc.stdout).text(),
-  };
-};
-
-const logDevFailure = async (args: {
-  error: unknown;
-  stderr: Promise<string>;
-  stdout: Promise<string>;
-}): Promise<void> => {
-  const [stdout, stderr] = await Promise.all([args.stdout, args.stderr]);
-  const message =
-    args.error instanceof Error ? args.error.message : String(args.error);
-  console.error(message);
-  console.error("dev stdout:");
-  console.error(stdout.trim() || "(empty)");
-  console.error("dev stderr:");
-  console.error(stderr.trim() || "(empty)");
-};
-
-const toErrorMessage = (error: unknown): string => {
-  if (error instanceof Error) {
-    return error.message;
-  }
-  return String(error);
-};
-
-const runDevSmokeFlow = async (): Promise<number> => {
-  const { devProc, devStderr, devStdout } = startDev();
-
-  try {
-    await waitForReady();
-    await runSmokeChecks();
-  } catch (error) {
-    await logDevFailure({ error, stderr: devStderr, stdout: devStdout });
-    return 1;
-  } finally {
-    await shutdownDev(devProc);
-  }
-  return 0;
-};
-
-const runPostDevCheck = async (): Promise<number> => {
-  try {
-    await runProjectCheck();
-    return 0;
-  } catch (error) {
-    console.error(toErrorMessage(error));
-    return 1;
-  }
-};
-
-const main = async (): Promise<number> => {
-  const smokeCode = await runDevSmokeFlow();
-  if (smokeCode !== 0) {
-    return smokeCode;
-  }
-  return runPostDevCheck();
-};
-
-const code = await main();
-process.exit(code);

package/templates/default/vercel.json

@@ -1,7 +0,0 @@
-{
-  "$schema": "https://openapi.vercel.sh/vercel.json",
-  "buildCommand": "bun run build",
-  "outputDirectory": "public",
-  "installCommand": "bun install",
-  "bunVersion": "1.x"
-}