idcmd 0.0.4 → 0.0.6

package/README.md

@@ -19,16 +19,33 @@ idcmd dev          # tailwind watch + SSR dev server
 idcmd build        # static dist/
 idcmd preview      # serve dist/ locally
 idcmd deploy       # build + validate Vercel static deploy config
+idcmd client ...   # add/update local site/client implementations
 ```
 
 ## Layout (V1)
 
 - `site/content/<slug>.md` -> `/<slug>/` (`index.md` -> `/`)
+- `site/client/*` is local source code (you own and edit these files)
+- `site/client/runtime/*.ts` is local browser runtime code (compiled to `site/public/_idcmd/*.js`)
 - `site/styles/tailwind.css` -> `site/public/styles.css` (dev) / `dist/styles.css` (build)
 - `site/public/` static assets
 - `site/server/routes/**` file-based server routes (dev/server-host only)
 - `site/site.jsonc` site config
 
+## Syncing Local Client Code
+
+Use these commands to pull baseline UI implementations into your project:
+
+```bash
+idcmd client add all
+idcmd client update all --dry-run
+idcmd client update layout --yes
+idcmd client update runtime --yes
+```
+
+`add` creates missing files. `update` overwrites changed files and requires `--yes` unless `--dry-run` is used.
+Runtime files in `site/client/runtime/` are compiled automatically by `idcmd dev` and `idcmd build`.
+
 ## Example: Add A Page
 
 Create `site/content/hello.md`:
@@ -63,6 +80,7 @@ It responds at `/api/hello`.
 `tickets/ROADMAP.md` is the source of truth. For V1, we explicitly target:
 
 - Content routes ship `0` bytes of JavaScript by default (both SSR output and built HTML).
+- Content routes ship a small, opinionated JavaScript runtime by default (prefetch + optional right-rail behavior).
 - Search index size `<= 5 MB` for `<= 2,000` pages.
 - Build completes in `<= 60s` for `<= 2,000` pages on a typical laptop.
 
@@ -90,8 +108,9 @@ It responds at `/api/hello`.
 
 ### JS policy
 
-- Content routes ship `0` bytes of JavaScript by default.
-- Allowed scripts:
+- Content routes ship lightweight runtime scripts by default.
+- Script behavior:
+  - Always: `/_idcmd/nav-prefetch.js`
   - Dev only: `/_idcmd/live-reload.js`
-  - Optional: `/_idcmd/right-rail-scrollspy.js` only when scrollspy is enabled and the computed TOC is non-empty
-- Search page is SSR-only by default (no client JS).
+  - Right rail enabled: `/_idcmd/llm-menu.js`
+  - Right rail scrollspy enabled with non-empty TOC: `/_idcmd/right-rail-scrollspy.js`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "idcmd",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "repository": {
     "type": "git",
     "url": "https://github.com/rustydotwtf/idcmd"
@@ -28,7 +28,7 @@
     "build": "bun run build:css && bun src/build.ts",
     "preview": "bunx serve dist",
     "start": "bun src/server.ts",
-    "check": "ultracite check && bun run typecheck && bun run test",
+    "check": "bun run scripts/check.ts",
     "test": "bun test",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "fix": "ultracite fix",

package/src/build.ts

@@ -5,7 +5,7 @@ import { scanContentFiles, slugFromContentFile } from "./content/paths";
 import { getProjectPaths } from "./project/paths";
 import { renderDocument, renderMarkdownPage } from "./render/page-renderer";
 import { generateSearchIndexFromContent } from "./search/index";
-import { renderSearchPageContent } from "./search/page";
+import { getRenderSearchPageContent } from "./search/search-page-loader";
 import {
   collectSitemapPagesFromContent,
   generateRobotsTxt,
@@ -100,13 +100,14 @@ const cssSource = await resolveCssSource();
 const inlineCss = cssSource ? await Bun.file(cssSource).text() : undefined;
 const cssPath = inlineCss ? undefined : "/styles.css";
 
-const renderStaticSearchPage = (): Promise<string> => {
+const renderStaticSearchPage = async (): Promise<string> => {
+  const renderSearchPage = await getRenderSearchPageContent();
   const topPages = navigation
     .flatMap((group) => group.items)
     .slice(0, 8)
     .map((item) => ({ href: item.href, title: item.title }));
 
-  const contentHtml = renderSearchPageContent({
+  const contentHtml = renderSearchPage({
     minQueryLength: MIN_SEARCH_QUERY_LENGTH,
     query: "",
     results: [],

package/src/cli/commands/build.ts

@@ -1,3 +1,5 @@
+import { compileRuntimeAssetsOnce } from "../runtime-assets";
+
 const findTailwindInput = async (): Promise<string> => {
   const candidates = ["site/styles/tailwind.css", "content/styles.css"];
   for (const path of candidates) {
@@ -16,6 +18,11 @@ const idcmdBuildEntry = (): string =>
   Bun.fileURLToPath(new URL("../../build.ts", import.meta.url));
 
 export const buildCommand = async (): Promise<number> => {
+  const runtimeCode = await compileRuntimeAssetsOnce();
+  if (runtimeCode !== 0) {
+    return runtimeCode;
+  }
+
   const tailwindInput = await findTailwindInput();
 
   const cssProc = Bun.spawn(

package/src/cli/commands/client.ts

@@ -0,0 +1,317 @@
+import { ensureDir } from "../fs";
+import { dirname, joinPath } from "../path";
+
+const TEMPLATE_CLIENT_DIR = joinPath(
+  import.meta.dir,
+  "..",
+  "..",
+  "..",
+  "templates",
+  "default",
+  "site",
+  "client"
+);
+const TEMPLATE_RUNTIME_DIR = joinPath(TEMPLATE_CLIENT_DIR, "runtime");
+
+const SITE_CLIENT_DIR = joinPath("site", "client");
+const SITE_RUNTIME_DIR = joinPath(SITE_CLIENT_DIR, "runtime");
+const SITE_CONFIG_PATH = joinPath("site", "site.jsonc");
+
+const CLIENT_PARTS = [
+  "layout",
+  "right-rail",
+  "search-page",
+  "runtime",
+] as const;
+type ClientPart = (typeof CLIENT_PARTS)[number];
+type ClientAction = "add" | "update";
+
+const RUNTIME_FILES = [
+  "live-reload.ts",
+  "llm-menu.ts",
+  "nav-prefetch.ts",
+  "right-rail-scrollspy.ts",
+] as const;
+
+interface ClientFileSpec {
+  fileName: string;
+  targetPath: string;
+  templatePath: string;
+}
+
+export interface ClientFlags {
+  dryRun?: boolean;
+  yes?: boolean;
+}
+
+interface ParsedClientArgs {
+  action: ClientAction;
+  parts: ClientPart[];
+}
+
+interface FilePlan {
+  fileName: string;
+  nextText: string;
+  part: ClientPart;
+  reason: string;
+  shouldWrite: boolean;
+  targetPath: string;
+}
+
+const getFileSpecsForPart = (part: ClientPart): ClientFileSpec[] => {
+  if (part === "layout") {
+    return [
+      {
+        fileName: "layout.tsx",
+        targetPath: joinPath(SITE_CLIENT_DIR, "layout.tsx"),
+        templatePath: joinPath(TEMPLATE_CLIENT_DIR, "layout.tsx"),
+      },
+    ];
+  }
+
+  if (part === "right-rail") {
+    return [
+      {
+        fileName: "right-rail.tsx",
+        targetPath: joinPath(SITE_CLIENT_DIR, "right-rail.tsx"),
+        templatePath: joinPath(TEMPLATE_CLIENT_DIR, "right-rail.tsx"),
+      },
+    ];
+  }
+
+  if (part === "search-page") {
+    return [
+      {
+        fileName: "search-page.tsx",
+        targetPath: joinPath(SITE_CLIENT_DIR, "search-page.tsx"),
+        templatePath: joinPath(TEMPLATE_CLIENT_DIR, "search-page.tsx"),
+      },
+    ];
+  }
+
+  return RUNTIME_FILES.map((fileName) => ({
+    fileName,
+    targetPath: joinPath(SITE_RUNTIME_DIR, fileName),
+    templatePath: joinPath(TEMPLATE_RUNTIME_DIR, fileName),
+  }));
+};
+
+const isClientAction = (value: string): value is ClientAction =>
+  value === "add" || value === "update";
+
+const isClientPart = (value: string): value is ClientPart =>
+  CLIENT_PARTS.includes(value as ClientPart);
+
+const parseClientPart = (value: string | undefined): ClientPart[] => {
+  if (!value || value === "all") {
+    return [...CLIENT_PARTS];
+  }
+
+  if (!isClientPart(value)) {
+    throw new Error(
+      `Unknown client part: ${value}. Expected one of ${CLIENT_PARTS.join(", ")} or all.`
+    );
+  }
+
+  return [value];
+};
+
+const parseClientArgs = (positionals: string[]): ParsedClientArgs => {
+  const [actionRaw, partRaw] = positionals;
+  if (!actionRaw || !isClientAction(actionRaw)) {
+    throw new Error(
+      "Usage: idcmd client <add|update> <layout|right-rail|search-page|runtime|all> [--dry-run] [--yes]"
+    );
+  }
+
+  return {
+    action: actionRaw,
+    parts: parseClientPart(partRaw),
+  };
+};
+
+const ensureSiteLayout = async (): Promise<void> => {
+  if (!(await Bun.file(SITE_CONFIG_PATH).exists())) {
+    throw new Error(
+      `Could not find ${SITE_CONFIG_PATH}. Run this command from an idcmd site project root.`
+    );
+  }
+};
+
+const readTemplateFile = async (spec: ClientFileSpec): Promise<string> => {
+  const file = Bun.file(spec.templatePath);
+  if (!(await file.exists())) {
+    throw new Error(`Missing template file: ${spec.templatePath}`);
+  }
+  return file.text();
+};
+
+const classifyAddPlan = async (
+  part: ClientPart,
+  spec: ClientFileSpec,
+  nextText: string
+): Promise<FilePlan> => {
+  const exists = await Bun.file(spec.targetPath).exists();
+
+  return {
+    fileName: spec.fileName,
+    nextText,
+    part,
+    reason: exists ? "exists" : "missing",
+    shouldWrite: !exists,
+    targetPath: spec.targetPath,
+  };
+};
+
+const classifyUpdatePlan = async (
+  part: ClientPart,
+  spec: ClientFileSpec,
+  nextText: string
+): Promise<FilePlan> => {
+  const file = Bun.file(spec.targetPath);
+
+  if (!(await file.exists())) {
+    return {
+      fileName: spec.fileName,
+      nextText,
+      part,
+      reason: "missing",
+      shouldWrite: false,
+      targetPath: spec.targetPath,
+    };
+  }
+
+  const currentText = await file.text();
+  const isUpToDate = currentText === nextText;
+
+  return {
+    fileName: spec.fileName,
+    nextText,
+    part,
+    reason: isUpToDate ? "up-to-date" : "changed",
+    shouldWrite: !isUpToDate,
+    targetPath: spec.targetPath,
+  };
+};
+
+const buildPlan = async (args: ParsedClientArgs): Promise<FilePlan[]> => {
+  const entries: FilePlan[] = [];
+  for (const part of args.parts) {
+    const files = getFileSpecsForPart(part);
+    for (const file of files) {
+      // eslint-disable-next-line no-await-in-loop
+      const nextText = await readTemplateFile(file);
+      // eslint-disable-next-line no-await-in-loop
+      const item =
+        args.action === "add"
+          ? await classifyAddPlan(part, file, nextText)
+          : await classifyUpdatePlan(part, file, nextText);
+      entries.push(item);
+    }
+  }
+  return entries;
+};
+
+const getWriteLabel = (action: ClientAction): "create" | "update" =>
+  action === "add" ? "create" : "update";
+
+const getSkipReason = (action: ClientAction, item: FilePlan): string => {
+  if (action === "add") {
+    return item.reason;
+  }
+
+  return item.reason === "missing"
+    ? `missing; run: idcmd client add ${item.part}`
+    : item.reason;
+};
+
+const formatPlanLine = (action: ClientAction, item: FilePlan): string => {
+  if (item.shouldWrite) {
+    return `[${getWriteLabel(action)}] ${item.targetPath}`;
+  }
+
+  return `[skip] ${item.targetPath} (${getSkipReason(action, item)})`;
+};
+
+const printPlan = (action: ClientAction, plan: FilePlan[]): void => {
+  for (const item of plan) {
+    console.log(formatPlanLine(action, item));
+  }
+};
+
+const ensureUpdateConfirmed = (
+  flags: ClientFlags,
+  plan: FilePlan[],
+  action: ClientAction
+): void => {
+  if (action !== "update") {
+    return;
+  }
+
+  if (flags.dryRun) {
+    return;
+  }
+
+  const pending = plan.some((item) => item.shouldWrite);
+  if (pending && !flags.yes) {
+    throw new Error(
+      "Refusing to overwrite client files without --yes. Re-run with: idcmd client update <part> --yes"
+    );
+  }
+};
+
+const applyPlan = async (plan: FilePlan[]): Promise<void> => {
+  for (const item of plan) {
+    if (!item.shouldWrite) {
+      continue;
+    }
+
+    // eslint-disable-next-line no-await-in-loop
+    await ensureDir(dirname(item.targetPath));
+    // eslint-disable-next-line no-await-in-loop
+    await Bun.write(item.targetPath, item.nextText);
+  }
+};
+
+const printDryRunFooter = (plan: FilePlan[]): void => {
+  const count = plan.filter((item) => item.shouldWrite).length;
+  console.log(`[dry-run] ${count} file(s) would change.`);
+};
+
+const printAppliedFooter = (plan: FilePlan[]): void => {
+  const count = plan.filter((item) => item.shouldWrite).length;
+  console.log(`Applied ${count} change(s).`);
+};
+
+const maybeHandleDryRun = (flags: ClientFlags, plan: FilePlan[]): boolean => {
+  if (!flags.dryRun) {
+    return false;
+  }
+
+  printDryRunFooter(plan);
+  return true;
+};
+
+const applyPlanWithSummary = async (plan: FilePlan[]): Promise<void> => {
+  await applyPlan(plan);
+  printAppliedFooter(plan);
+};
+
+export const clientCommand = async (
+  positionals: string[],
+  flags: ClientFlags
+): Promise<number> => {
+  await ensureSiteLayout();
+  const parsed = parseClientArgs(positionals);
+  const plan = await buildPlan(parsed);
+
+  printPlan(parsed.action, plan);
+  ensureUpdateConfirmed(flags, plan, parsed.action);
+
+  if (maybeHandleDryRun(flags, plan)) {
+    return 0;
+  }
+
+  await applyPlanWithSummary(plan);
+  return 0;
+};

package/src/cli/commands/dev.ts

@@ -1,4 +1,8 @@
 import { parsePort } from "../normalize";
+import {
+  compileRuntimeAssetsOnce,
+  watchRuntimeAssets,
+} from "../runtime-assets";
 
 const DEFAULT_PORT = 4000;
 
@@ -33,12 +37,11 @@ const installSignalHandlers = (shutdown: () => void): void => {
   process.on("SIGTERM", shutdown);
 };
 
-export const devCommand = async (flags: DevFlags): Promise<number> => {
-  const port = parsePort(flags.port, DEFAULT_PORT);
-  const tailwindInput = await findTailwindInput();
-  const tailwindOutput = await resolveTailwindOutput();
-
-  const cssProc = Bun.spawn(
+const spawnCssProcess = (
+  tailwindInput: string,
+  tailwindOutput: string
+): ReturnType<typeof Bun.spawn> =>
+  Bun.spawn(
     [
       "bunx",
       "@tailwindcss/cli",
@@ -46,35 +49,97 @@ export const devCommand = async (flags: DevFlags): Promise<number> => {
       tailwindInput,
       "-o",
       tailwindOutput,
-      "--watch",
+      // Tailwind v4 exits watch mode when stdin is closed unless `always` is specified.
+      "--watch=always",
     ],
     { stderr: "inherit", stdout: "inherit" }
   );
 
-  const serverProc = Bun.spawn(["bun", "--hot", idcmdServerEntry()], {
+const spawnServerProcess = (port: number): ReturnType<typeof Bun.spawn> =>
+  Bun.spawn(["bun", "--hot", idcmdServerEntry()], {
     env: { ...process.env, NODE_ENV: "development", PORT: String(port) },
     stderr: "inherit",
     stdout: "inherit",
   });
 
-  const shutdown = (): void => {
-    try {
-      cssProc.kill("SIGTERM");
-    } catch {
-      // ignore
-    }
-    try {
-      serverProc.kill("SIGTERM");
-    } catch {
-      // ignore
-    }
+const ensureRuntimeAssetsReady = async (): Promise<{
+  runtimeProc: ReturnType<typeof Bun.spawn> | null;
+  runtimeSetupCode: number;
+}> => {
+  const runtimeCode = await compileRuntimeAssetsOnce();
+  if (runtimeCode !== 0) {
+    return { runtimeProc: null, runtimeSetupCode: runtimeCode };
+  }
+
+  return {
+    runtimeProc: await watchRuntimeAssets(),
+    runtimeSetupCode: 0,
   };
+};
 
-  installSignalHandlers(shutdown);
+const killProcess = (proc: ReturnType<typeof Bun.spawn> | null): void => {
+  if (!proc) {
+    return;
+  }
+  try {
+    proc.kill("SIGTERM");
+  } catch {
+    // ignore
+  }
+};
 
-  const [cssExit, serverExit] = await Promise.all([
-    cssProc.exited,
-    serverProc.exited,
+const resolveDevExitCode = (args: {
+  cssExit: number;
+  runtimeExit: number;
+  serverExit: number;
+}): number => {
+  if (args.serverExit !== 0) {
+    return args.serverExit;
+  }
+  if (args.cssExit !== 0) {
+    return args.cssExit;
+  }
+  return args.runtimeExit;
+};
+
+const installDevSignalHandlers = (args: {
+  cssProc: ReturnType<typeof Bun.spawn>;
+  runtimeProc: ReturnType<typeof Bun.spawn> | null;
+  serverProc: ReturnType<typeof Bun.spawn>;
+}): void => {
+  installSignalHandlers(() => {
+    killProcess(args.cssProc);
+    killProcess(args.serverProc);
+    killProcess(args.runtimeProc);
+  });
+};
+
+const waitForDevExit = async (args: {
+  cssProc: ReturnType<typeof Bun.spawn>;
+  runtimeProc: ReturnType<typeof Bun.spawn> | null;
+  serverProc: ReturnType<typeof Bun.spawn>;
+}): Promise<{ cssExit: number; runtimeExit: number; serverExit: number }> => {
+  const [cssExit, serverExit, runtimeExit] = await Promise.all([
+    args.cssProc.exited,
+    args.serverProc.exited,
+    args.runtimeProc?.exited ?? Promise.resolve(0),
   ]);
-  return serverExit === 0 ? cssExit : serverExit;
+  return { cssExit, runtimeExit, serverExit };
+};
+
+export const devCommand = async (flags: DevFlags): Promise<number> => {
+  const port = parsePort(flags.port, DEFAULT_PORT);
+  const { runtimeProc, runtimeSetupCode } = await ensureRuntimeAssetsReady();
+  if (runtimeSetupCode !== 0) {
+    return runtimeSetupCode;
+  }
+
+  const tailwindInput = await findTailwindInput();
+  const tailwindOutput = await resolveTailwindOutput();
+  const cssProc = spawnCssProcess(tailwindInput, tailwindOutput);
+  const serverProc = spawnServerProcess(port);
+  installDevSignalHandlers({ cssProc, runtimeProc, serverProc });
+  return resolveDevExitCode(
+    await waitForDevExit({ cssProc, runtimeProc, serverProc })
+  );
 };