idcmd 0.0.4 → 0.0.6

package/src/cli/commands/init.ts

@@ -1,10 +1,10 @@
-import { copyDir, isDirEmpty, replaceInFile } from "../fs";
+import { copyDir, ensureDir, isDirEmpty, replaceInFile } from "../fs";
 import {
   normalizeOptionalString,
   parsePort,
   toPackageName,
 } from "../normalize";
-import { basename, joinPath } from "../path";
+import { basename, dirname, joinPath } from "../path";
 import { promptOptionalText, promptText } from "../prompt";
 import { run } from "../run";
 import { readPackageVersion } from "../version";
@@ -23,6 +23,60 @@ export interface InitFlags {
 const resolveTemplateDir = (): string =>
   joinPath(import.meta.dir, "..", "..", "..", "templates", "default");
 
+const TEMPLATE_DOTPATHS = [".gitignore", ".github/workflows/ci.yml"];
+const DEFAULT_OXLINT_CONFIG = `{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "extends": [
+    "./node_modules/ultracite/config/oxlint/core/.oxlintrc.json",
+    "./node_modules/ultracite/config/oxlint/react/.oxlintrc.json"
+  ],
+  "rules": {
+    "jest/require-hook": "off"
+  },
+  "overrides": [
+    {
+      "files": [
+        "**/*.test.ts",
+        "**/*.test.tsx",
+        "**/*.test.js",
+        "**/*.test.jsx",
+        "**/*.spec.ts",
+        "**/*.spec.tsx",
+        "**/*.spec.js",
+        "**/*.spec.jsx"
+      ],
+      "rules": {
+        "jest/require-hook": "error"
+      }
+    }
+  ]
+}
+`;
+const DEFAULT_OXFMT_CONFIG = `// Ultracite oxfmt Configuration
+// https://oxc.rs/docs/guide/usage/formatter/config-file-reference.html
+{
+  "$schema": "./node_modules/oxfmt/configuration_schema.json",
+  "printWidth": 80,
+  "tabWidth": 2,
+  "useTabs": false,
+  "semi": true,
+  "singleQuote": false,
+  "quoteProps": "as-needed",
+  "jsxSingleQuote": false,
+  "trailingComma": "es5",
+  "bracketSpacing": true,
+  "bracketSameLine": false,
+  "arrowParens": "always",
+  "endOfLine": "lf",
+  "experimentalSortPackageJson": true,
+  "experimentalSortImports": {
+    "ignoreCase": true,
+    "newlinesBetween": true,
+    "order": "asc",
+  },
+}
+`;
+
 const commentOutBaseUrl = (text: string): string =>
   text.replace(
     '"baseUrl": "__IDCMD_SITE_BASE_URL__",',
@@ -56,6 +110,11 @@ const fillPackageJson = (args: {
     .replaceAll("__IDCMD_IDCMD_VERSION__", `^${args.idcmdVersion}`)
     .replaceAll("__IDCMD_DEV_PORT__", String(args.port));
 
+const fillReadme = (args: { siteName: string; text: string }): string =>
+  args.text
+    .replaceAll("__IDCMD_SITE_NAME__", args.siteName)
+    .replaceAll("IDCMD_SITE_NAME", args.siteName);
+
 interface InitDefaults {
   defaultPort: number;
   defaultSiteName: string;
@@ -105,6 +164,31 @@ const readInitInputs = async (
 const scaffoldFromTemplate = async (targetDir: string): Promise<void> => {
   const templateDir = resolveTemplateDir();
   await copyDir(templateDir, targetDir);
+  await copyTemplateDotpaths({ targetDir, templateDir });
+  await writeDefaultLintConfigs(targetDir);
+};
+
+const copyTemplateDotpaths = async (args: {
+  targetDir: string;
+  templateDir: string;
+}): Promise<void> => {
+  for (const relativePath of TEMPLATE_DOTPATHS) {
+    const srcPath = joinPath(args.templateDir, relativePath);
+    if (!(await Bun.file(srcPath).exists())) {
+      continue;
+    }
+    const dstPath = joinPath(args.targetDir, relativePath);
+    // Hidden paths are not copied by glob scan; explicitly create parent dirs.
+    // eslint-disable-next-line no-await-in-loop
+    await ensureDir(dirname(dstPath));
+    // eslint-disable-next-line no-await-in-loop
+    await Bun.write(dstPath, Bun.file(srcPath));
+  }
+};
+
+const writeDefaultLintConfigs = async (targetDir: string): Promise<void> => {
+  await Bun.write(joinPath(targetDir, ".oxlintrc.json"), DEFAULT_OXLINT_CONFIG);
+  await Bun.write(joinPath(targetDir, ".oxfmtrc.jsonc"), DEFAULT_OXFMT_CONFIG);
 };
 
 const applySubstitutions = async (args: {
@@ -133,6 +217,13 @@ const applySubstitutions = async (args: {
       text,
     })
   );
+
+  await replaceInFile(joinPath(args.targetDir, "README.md"), (text) =>
+    fillReadme({
+      siteName: args.siteName,
+      text,
+    })
+  );
 };
 
 const maybeInitGit = async (

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