idcmd 0.0.5 → 0.0.6

package/src/cli/main.ts

@@ -4,6 +4,7 @@ import type { ParsedArgs } from "./args";
 
 import { parseArgs } from "./args";
 import { buildCommand } from "./commands/build";
+import { clientCommand } from "./commands/client";
 import { deployCommand } from "./commands/deploy";
 import { devCommand } from "./commands/dev";
 import { initCommand } from "./commands/init";
@@ -23,12 +24,16 @@ const usage = (): string =>
     "  idcmd build",
     "  idcmd preview [--port <port>]",
     "  idcmd deploy",
+    "  idcmd client <add|update> <layout|right-rail|search-page|runtime|all> [--dry-run] [--yes]",
     "",
   ].join("\n");
 
 const asStringFlag = (value: unknown): string | undefined =>
   typeof value === "string" ? value : undefined;
 
+const asBooleanFlag = (value: unknown): boolean =>
+  value === true || value === "true";
+
 const handleInit = (parsed: ParsedArgs): Promise<number> => {
   const [dir] = parsed.positionals;
   return initCommand(dir, parsed.flags);
@@ -46,8 +51,15 @@ const handlePreview = (parsed: ParsedArgs): Promise<number> => {
 
 const handleDeploy = (): Promise<number> => deployCommand();
 
+const handleClient = (parsed: ParsedArgs): Promise<number> =>
+  clientCommand(parsed.positionals, {
+    dryRun: asBooleanFlag(parsed.flags["dry-run"]),
+    yes: asBooleanFlag(parsed.flags.yes),
+  });
+
 const handlers: Record<string, (parsed: ParsedArgs) => Promise<number>> = {
   build: () => handleBuild(),
+  client: (parsed) => handleClient(parsed),
   deploy: () => handleDeploy(),
   dev: (parsed) => handleDev(parsed),
   init: (parsed) => handleInit(parsed),

package/src/cli/runtime-assets.ts

@@ -0,0 +1,92 @@
+import { joinPath } from "./path";
+
+const RUNTIME_SOURCE_DIR = joinPath("site", "client", "runtime");
+const RUNTIME_OUTPUT_DIR = joinPath("site", "public", "_idcmd");
+
+const RUNTIME_ENTRY_FILES = [
+  "live-reload.ts",
+  "llm-menu.ts",
+  "nav-prefetch.ts",
+  "right-rail-scrollspy.ts",
+] as const;
+
+const runtimeEntryPaths = (): string[] =>
+  RUNTIME_ENTRY_FILES.map((fileName) => joinPath(RUNTIME_SOURCE_DIR, fileName));
+
+const scanRuntimeEntrypoints = async (
+  entries: readonly string[]
+): Promise<{
+  existing: string[];
+  missing: string[];
+}> => {
+  const existing: string[] = [];
+  const missing: string[] = [];
+
+  for (const entry of entries) {
+    // eslint-disable-next-line no-await-in-loop
+    if (await Bun.file(entry).exists()) {
+      existing.push(entry);
+      continue;
+    }
+    missing.push(entry);
+  }
+
+  return { existing, missing };
+};
+
+const getRuntimeEntrypoints = async (): Promise<string[]> => {
+  const entries = runtimeEntryPaths();
+  const { existing, missing } = await scanRuntimeEntrypoints(entries);
+
+  if (existing.length === 0) {
+    return [];
+  }
+
+  if (missing.length > 0) {
+    throw new Error(
+      `Incomplete runtime scripts in ${RUNTIME_SOURCE_DIR}. Missing: ${missing.join(", ")}`
+    );
+  }
+
+  return existing;
+};
+
+const buildRuntimeArgs = (entrypoints: string[], watch: boolean): string[] => [
+  "bun",
+  "build",
+  ...entrypoints,
+  "--format",
+  "iife",
+  "--outdir",
+  RUNTIME_OUTPUT_DIR,
+  "--target",
+  "browser",
+  ...(watch ? ["--watch"] : []),
+];
+
+export const compileRuntimeAssetsOnce = async (): Promise<number> => {
+  const entrypoints = await getRuntimeEntrypoints();
+  if (entrypoints.length === 0) {
+    return 0;
+  }
+
+  const proc = Bun.spawn(buildRuntimeArgs(entrypoints, false), {
+    stderr: "inherit",
+    stdout: "inherit",
+  });
+  return proc.exited;
+};
+
+export const watchRuntimeAssets = async (): Promise<ReturnType<
+  typeof Bun.spawn
+> | null> => {
+  const entrypoints = await getRuntimeEntrypoints();
+  if (entrypoints.length === 0) {
+    return null;
+  }
+
+  return Bun.spawn(buildRuntimeArgs(entrypoints, true), {
+    stderr: "inherit",
+    stdout: "inherit",
+  });
+};

package/src/client/index.ts

@@ -1,7 +1,13 @@
-export type { LayoutProps } from "../render/layout";
+export type { LayoutProps, RenderLayout } from "../render/layout";
 export { renderLayout } from "../render/layout";
 
 export type { TocItem } from "../render/toc";
+export type { RightRailComponent, RightRailProps } from "../render/right-rail";
 export { RightRail } from "../render/right-rail";
 
+export type {
+  RenderSearchPageContent,
+  SearchPageProps,
+  TopPageLink,
+} from "../search/page";
 export { renderSearchPageContent } from "../search/page";

package/src/render/layout-loader.ts

@@ -1,9 +1,7 @@
-import type { LayoutProps } from "./layout";
+import type { RenderLayout } from "./layout";
 
 import { renderLayout as defaultRenderLayout } from "./layout";
 
-export type RenderLayout = (props: LayoutProps) => string;
-
 const USER_LAYOUT_PATH = "site/client/layout.tsx";
 
 const loadUserLayout = async (
@@ -44,3 +42,8 @@ export const getRenderLayout = async (): Promise<RenderLayout> => {
   cached = await tryLoadUserRenderLayout();
   return cached ?? defaultRenderLayout;
 };
+
+export const resetLayoutLoaderForTests = (): void => {
+  cached = null;
+  attempted = false;
+};

package/src/render/layout.tsx

@@ -5,6 +5,7 @@ import { render } from "preact-render-to-string";
 
 import type { NavGroup, NavItem } from "../content/navigation";
 import type { ResolvedRightRailConfig } from "../site/config";
+import type { RightRailComponent } from "./right-rail";
 import type { TocItem } from "./toc";
 
 import { RightRail } from "./right-rail";
@@ -22,10 +23,13 @@ export interface LayoutProps {
   scriptPaths?: string[];
   searchQuery?: string;
   showRightRail?: boolean;
+  rightRailComponent?: RightRailComponent;
   rightRail: ResolvedRightRailConfig;
   tocItems: TocItem[];
 }
 
+export type RenderLayout = (props: LayoutProps) => string;
+
 const Icon = ({ svg }: { svg: string }): JSX.Element => (
   <span
     class="inline-flex w-[18px] h-[18px]"
@@ -231,6 +235,7 @@ interface DocumentBodyProps {
   shouldShowRightRail: boolean;
   siteName: string;
   tocItems: TocItem[];
+  rightRailComponent: RightRailComponent;
 }
 
 const DocumentBody = ({
@@ -245,6 +250,7 @@ const DocumentBody = ({
   shouldShowRightRail,
   siteName,
   tocItems,
+  rightRailComponent: RightRailComponent,
 }: DocumentBodyProps): JSX.Element => (
   <body
     class="bg-background text-foreground font-sans"
@@ -266,7 +272,7 @@ const DocumentBody = ({
             dangerouslySetInnerHTML={{ __html: content }}
           />
           {shouldShowRightRail ? (
-            <RightRail
+            <RightRailComponent
               canonicalUrl={canonicalUrl}
               currentPath={currentPath}
               tocItems={tocItems}
@@ -299,6 +305,7 @@ const Layout = ({
   scriptPaths = [],
   searchQuery,
   showRightRail = true,
+  rightRailComponent = RightRail,
   rightRail,
   tocItems,
 }: LayoutProps): JSX.Element => {
@@ -330,10 +337,11 @@ const Layout = ({
         shouldShowRightRail={shouldShowRightRail}
         siteName={siteName}
         tocItems={tocItems}
+        rightRailComponent={rightRailComponent}
       />
     </html>
   );
 };
 
-export const renderLayout = (props: LayoutProps): string =>
+export const renderLayout: RenderLayout = (props) =>
   `<!DOCTYPE html>${render(<Layout {...props} />)}`;

package/src/render/page-renderer.ts

@@ -13,6 +13,7 @@ import { loadSiteConfig, resolveRightRailConfig } from "../site/config";
 import { resolveCanonicalUrl } from "../site/urls";
 import { getRenderLayout } from "./layout-loader";
 import { renderMarkdownToHtml } from "./markdown";
+import { getRightRail } from "./right-rail-loader";
 import { extractTocFromHtml } from "./toc";
 
 const ASSET_PREFIX = "/_idcmd";
@@ -118,7 +119,14 @@ export const renderDocument = async (options: {
   title: string;
   tocItems: ReturnType<typeof extractTocFromHtml>;
 }): Promise<string> => {
-  const renderLayout = await getRenderLayout();
+  const [renderLayout, rightRailComponent] = await Promise.all([
+    getRenderLayout(),
+    getRightRail(),
+  ]);
+  const scriptPaths = options.scriptPaths ?? [
+    `${ASSET_PREFIX}/nav-prefetch.js`,
+  ];
+
   return renderLayout({
     canonicalUrl: options.canonicalUrl,
     content: options.contentHtml,
@@ -128,7 +136,8 @@ export const renderDocument = async (options: {
     inlineCss: options.inlineCss,
     navigation: options.navigation,
     rightRail: options.rightRail,
-    scriptPaths: options.scriptPaths,
+    rightRailComponent,
+    scriptPaths,
     searchQuery: options.searchQuery,
     showRightRail: options.showRightRail,
     siteName: options.siteName,
@@ -244,6 +253,7 @@ const computeScriptPaths = (options: {
   shouldShowRightRail: boolean;
   tocItems: readonly unknown[];
 }): string[] => [
+  `${ASSET_PREFIX}/nav-prefetch.js`,
   ...(options.isDev ? [`${ASSET_PREFIX}/live-reload.js`] : []),
   ...(options.shouldShowRightRail ? [`${ASSET_PREFIX}/llm-menu.js`] : []),
   ...(options.shouldShowRightRail &&

package/src/render/right-rail-loader.ts

@@ -0,0 +1,49 @@
+import type { RightRailComponent } from "./right-rail";
+
+import { RightRail as defaultRightRail } from "./right-rail";
+
+const USER_RIGHT_RAIL_PATH = "site/client/right-rail.tsx";
+
+const loadUserRightRail = async (
+  filePath: string
+): Promise<RightRailComponent | null> => {
+  try {
+    const url = Bun.pathToFileURL(filePath);
+    const mod = (await import(url.toString())) as unknown as {
+      RightRail?: RightRailComponent;
+    };
+    return mod.RightRail ?? null;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn(
+      `[right-rail] Failed to load user right rail from ${filePath}: ${message}`
+    );
+    return null;
+  }
+};
+
+const tryLoadUserRightRail = async (): Promise<RightRailComponent | null> => {
+  const exists = await Bun.file(USER_RIGHT_RAIL_PATH).exists();
+  if (!exists) {
+    return null;
+  }
+  return loadUserRightRail(USER_RIGHT_RAIL_PATH);
+};
+
+let cached: RightRailComponent | null = null;
+let attempted = false;
+
+export const getRightRail = async (): Promise<RightRailComponent> => {
+  if (attempted) {
+    return cached ?? defaultRightRail;
+  }
+
+  attempted = true;
+  cached = await tryLoadUserRightRail();
+  return cached ?? defaultRightRail;
+};
+
+export const resetRightRailLoaderForTests = (): void => {
+  cached = null;
+  attempted = false;
+};

package/src/render/right-rail.tsx

@@ -216,17 +216,21 @@ const getPanelClass = (
     ? "fixed top-24 bottom-0 right-8 z-20 w-64 flex flex-col gap-6 min-h-0"
     : "sticky top-24 h-[calc(100vh-6rem)] flex flex-col gap-6 min-h-0";
 
+export interface RightRailProps {
+  canonicalUrl?: string;
+  currentPath: string;
+  tocItems: TocItem[];
+  rightRailConfig: ResolvedRightRailConfig;
+}
+
+export type RightRailComponent = (props: RightRailProps) => JSX.Element | null;
+
 export const RightRail = ({
   canonicalUrl,
   currentPath,
   tocItems,
   rightRailConfig,
-}: {
-  canonicalUrl?: string;
-  currentPath: string;
-  tocItems: TocItem[];
-  rightRailConfig: ResolvedRightRailConfig;
-}): JSX.Element => {
+}: RightRailProps): JSX.Element => {
   const { chatgptUrl, claudeUrl, markdownPath } = buildAskUrls({
     canonicalUrl,
     currentPath,

package/src/search/page.tsx

@@ -9,13 +9,15 @@ export interface TopPageLink {
   title: string;
 }
 
-interface SearchPageProps {
+export interface SearchPageProps {
   query: string;
   minQueryLength: number;
   results: SearchResult[];
   topPages: TopPageLink[];
 }
 
+export type RenderSearchPageContent = (props: SearchPageProps) => string;
+
 const ResultItem = ({ result }: { result: SearchResult }): JSX.Element => (
   <li class="rounded-md border border-border p-3">
     <a
@@ -92,5 +94,5 @@ const SearchPage = ({
   );
 };
 
-export const renderSearchPageContent = (props: SearchPageProps): string =>
+export const renderSearchPageContent: RenderSearchPageContent = (props) =>
   renderToString(<SearchPage {...props} />);

package/src/search/search-page-loader.ts

@@ -0,0 +1,51 @@
+import type { RenderSearchPageContent } from "./page";
+
+import { renderSearchPageContent as defaultRenderSearchPageContent } from "./page";
+
+const USER_SEARCH_PAGE_PATH = "site/client/search-page.tsx";
+
+const loadUserSearchPage = async (
+  filePath: string
+): Promise<RenderSearchPageContent | null> => {
+  try {
+    const url = Bun.pathToFileURL(filePath);
+    const mod = (await import(url.toString())) as unknown as {
+      renderSearchPageContent?: RenderSearchPageContent;
+    };
+    return mod.renderSearchPageContent ?? null;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn(
+      `[search-page] Failed to load user search page from ${filePath}: ${message}`
+    );
+    return null;
+  }
+};
+
+const tryLoadUserSearchPage =
+  async (): Promise<RenderSearchPageContent | null> => {
+    const exists = await Bun.file(USER_SEARCH_PAGE_PATH).exists();
+    if (!exists) {
+      return null;
+    }
+    return loadUserSearchPage(USER_SEARCH_PAGE_PATH);
+  };
+
+let cached: RenderSearchPageContent | null = null;
+let attempted = false;
+
+export const getRenderSearchPageContent =
+  async (): Promise<RenderSearchPageContent> => {
+    if (attempted) {
+      return cached ?? defaultRenderSearchPageContent;
+    }
+
+    attempted = true;
+    cached = await tryLoadUserSearchPage();
+    return cached ?? defaultRenderSearchPageContent;
+  };
+
+export const resetSearchPageLoaderForTests = (): void => {
+  cached = null;
+  attempted = false;
+};

package/src/search/server-page.ts

@@ -10,7 +10,7 @@ import {
 } from "../site/config";
 import { resolveCanonicalUrl } from "../site/urls";
 import { loadSearchIndex, search as runSearch } from "./index";
-import { renderSearchPageContent } from "./page";
+import { getRenderSearchPageContent } from "./search-page-loader";
 
 export interface SearchPageHandlerEnv {
   cacheHeaders: HeadersInit;
@@ -37,40 +37,74 @@ const getResults = (
     ? runSearch(index, query, scope).slice(0, env.maxResults)
     : [];
 
+const getSearchQuery = (url: URL): string =>
+  url.searchParams.get("q")?.trim() ?? "";
+
+const loadSearchPageDependencies = async (options: {
+  isDev: boolean;
+  siteConfig: Awaited<ReturnType<typeof loadSiteConfig>>;
+}): Promise<{
+  navigation: Awaited<ReturnType<typeof getNavigation>>;
+  index: Awaited<ReturnType<typeof loadSearchIndex>>;
+  renderSearchPageContent: Awaited<
+    ReturnType<typeof getRenderSearchPageContent>
+  >;
+}> => {
+  const [navigation, index, renderSearchPageContent] = await Promise.all([
+    getNavigation(options.isDev),
+    loadSearchIndex({
+      forceRefresh: options.isDev,
+      siteConfig: options.siteConfig,
+    }),
+    getRenderSearchPageContent(),
+  ]);
+
+  return { index, navigation, renderSearchPageContent };
+};
+
+const getCanonicalSearchPageUrl = (options: {
+  baseUrl?: string;
+  env: SearchPageHandlerEnv;
+  url: URL;
+}): string | undefined =>
+  resolveCanonicalUrl(
+    {
+      configuredBaseUrl: options.baseUrl,
+      isDev: options.env.isDev,
+      requestOrigin: options.url.origin,
+    },
+    "/search/"
+  );
+
 const buildSearchPageHtml = async (
   url: URL,
   env: SearchPageHandlerEnv
 ): Promise<string> => {
   const siteConfig = await loadSiteConfig();
   const scope = getSearchScope(siteConfig);
-  const query = url.searchParams.get("q")?.trim() ?? "";
+  const query = getSearchQuery(url);
   const rightRail = resolveRightRailConfig(siteConfig.rightRail);
 
-  const [navigation, index] = await Promise.all([
-    getNavigation(env.isDev),
-    loadSearchIndex({ forceRefresh: env.isDev, siteConfig }),
-  ]);
+  const { index, navigation, renderSearchPageContent } =
+    await loadSearchPageDependencies({
+      isDev: env.isDev,
+      siteConfig,
+    });
 
   const results = getResults(index, query, scope, env);
-  const topPages = getTopPages(navigation);
   const content = renderSearchPageContent({
     minQueryLength: env.minQueryLength,
     query,
     results,
-    topPages,
+    topPages: getTopPages(navigation),
   });
 
-  const canonicalUrl = resolveCanonicalUrl(
-    {
-      configuredBaseUrl: siteConfig.baseUrl,
-      isDev: env.isDev,
-      requestOrigin: url.origin,
-    },
-    "/search/"
-  );
-
   return renderDocument({
-    canonicalUrl,
+    canonicalUrl: getCanonicalSearchPageUrl({
+      baseUrl: siteConfig.baseUrl,
+      env,
+      url,
+    }),
     contentHtml: content,
     currentPath: "/search/",
     description: siteConfig.description,

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

@@ -0,0 +1,24 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  ci:
+    runs-on: ubuntu-22.04
+    env:
+      CI: true
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+      - name: Install dependencies
+        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

@@ -2,6 +2,8 @@
 
 Everything you edit lives in `site/`.
 
+This starter is intentionally opinionated for AI-friendly markdown sites.
+
 ## Quickstart
 
 ```bash
@@ -9,14 +11,35 @@ bun install
 bun run dev
 ```
 
+## CI Smoke
+
+```bash
+bun run check
+bun run smoke
+```
+
 ## Layout
 
 - `site/content/` markdown pages (`index.md` -> `/`, `about.md` -> `/about/`)
+- `site/client/` local UI implementation (`layout.tsx`, `right-rail.tsx`, `search-page.tsx`)
+- `site/client/runtime/` local browser runtime TS (`*_idcmd` scripts compile from here)
 - `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
 
+## Sync Local Client Files
+
+```bash
+idcmd client add all
+idcmd client update all --dry-run
+idcmd client update layout --yes
+idcmd client update runtime --yes
+```
+
+These commands copy the latest baseline implementations from `idcmd` into `site/client/`.
+Runtime files in `site/client/runtime/` are compiled automatically by `idcmd dev` and `idcmd build`.
+
 ## Deploy (Vercel static)
 
 ```bash

package/templates/default/package.json

@@ -7,7 +7,8 @@
     "build": "idcmd build",
     "preview": "idcmd preview",
     "deploy": "idcmd deploy",
-    "check": "ultracite check && bun run typecheck && bun run test",
+    "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-internal.ts

@@ -0,0 +1,56 @@
+interface InternalCheck {
+  description: string;
+  run: () => Promise<boolean>;
+}
+
+const fileExists = (path: string): Promise<boolean> => Bun.file(path).exists();
+
+const checks: InternalCheck[] = [
+  {
+    description: "package.json must exist at the project root",
+    run: () => fileExists("package.json"),
+  },
+  {
+    description: "site config must exist (site/site.jsonc or site.jsonc)",
+    run: async () =>
+      (await fileExists("site/site.jsonc")) || (await fileExists("site.jsonc")),
+  },
+  {
+    description:
+      "tailwind input must exist (site/styles/tailwind.css or content/styles.css)",
+    run: async () =>
+      (await fileExists("site/styles/tailwind.css")) ||
+      (await fileExists("content/styles.css")),
+  },
+];
+
+const runInternalChecks = async (): Promise<string[]> => {
+  const failures: string[] = [];
+
+  for (const check of checks) {
+    // eslint-disable-next-line no-await-in-loop
+    const ok = await check.run();
+    if (!ok) {
+      failures.push(check.description);
+    }
+  }
+
+  return failures;
+};
+
+const main = async (): Promise<number> => {
+  const failures = await runInternalChecks();
+  if (failures.length === 0) {
+    console.log("Internal checks passed.");
+    return 0;
+  }
+
+  console.error("Internal checks failed:");
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  return 1;
+};
+
+const code = await main();
+process.exit(code);