idcmd 0.0.5 → 0.0.7

package/templates/default/scripts/smoke.ts

@@ -0,0 +1,223 @@
+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/site/{public/_idcmd/llm-menu.js → code/runtime/llm-menu.ts}

@@ -2,7 +2,7 @@ const COPY_SELECTOR = 'a[data-copy-markdown="1"]';
 const LABEL_SELECTOR = '[data-copy-markdown-label="1"]';
 const RESET_DELAY_MS = 2000;
 
-const setLinkDisabled = (link, disabled) => {
+const setLinkDisabled = (link: HTMLAnchorElement, disabled: boolean): void => {
   if (disabled) {
     link.setAttribute("aria-disabled", "true");
     link.style.pointerEvents = "none";
@@ -15,14 +15,14 @@ const setLinkDisabled = (link, disabled) => {
   link.style.opacity = "";
 };
 
-const setLinkLabel = (link, next) => {
+const setLinkLabel = (link: HTMLAnchorElement, next: string): void => {
   const label = link.querySelector(LABEL_SELECTOR);
   if (label) {
     label.textContent = next;
   }
 };
 
-const toAbsoluteUrl = (href) => {
+const toAbsoluteUrl = (href: string): string => {
   try {
     return new URL(href, window.location.href).toString();
   } catch {
@@ -30,7 +30,7 @@ const toAbsoluteUrl = (href) => {
   }
 };
 
-const createHiddenTextarea = (text) => {
+const createHiddenTextarea = (text: string): HTMLTextAreaElement => {
   const textarea = document.createElement("textarea");
   textarea.value = text;
   textarea.setAttribute("readonly", "true");
@@ -40,7 +40,7 @@ const createHiddenTextarea = (text) => {
   return textarea;
 };
 
-const safeExecCommandCopy = () => {
+const safeExecCommandCopy = (): boolean => {
   try {
     return document.execCommand("copy");
   } catch {
@@ -48,7 +48,7 @@ const safeExecCommandCopy = () => {
   }
 };
 
-const copyViaExecCommand = (text) => {
+const copyViaExecCommand = (text: string): boolean => {
   const textarea = createHiddenTextarea(text);
   document.body.append(textarea);
   textarea.focus();
@@ -58,7 +58,7 @@ const copyViaExecCommand = (text) => {
   return ok;
 };
 
-const copyText = async (text) => {
+const copyText = async (text: string): Promise<boolean> => {
   const { clipboard } = navigator;
   if (clipboard?.writeText) {
     try {
@@ -72,18 +72,18 @@ const copyText = async (text) => {
   return copyViaExecCommand(text);
 };
 
-const closeMenuIfPresent = (link) => {
+const closeMenuIfPresent = (link: HTMLAnchorElement): void => {
   const details = link.closest("details");
   if (details instanceof HTMLDetailsElement) {
     details.open = false;
   }
 };
 
-const getOriginalLabel = (link) =>
+const getOriginalLabel = (link: HTMLAnchorElement): string =>
   link.querySelector(LABEL_SELECTOR)?.textContent ??
   "Copy Markdown to Clipboard";
 
-const fetchMarkdownText = async (href) => {
+const fetchMarkdownText = async (href: string): Promise<string | null> => {
   const res = await fetch(toAbsoluteUrl(href), { credentials: "same-origin" });
   if (!res.ok) {
     return null;
@@ -91,7 +91,7 @@ const fetchMarkdownText = async (href) => {
   return res.text();
 };
 
-const copyMarkdownFromHref = async (href) => {
+const copyMarkdownFromHref = async (href: string): Promise<boolean> => {
   try {
     const text = await fetchMarkdownText(href);
     if (!text) {
@@ -103,24 +103,30 @@ const copyMarkdownFromHref = async (href) => {
   }
 };
 
-const startCopyOperation = (link) => {
+const startCopyOperation = (link: HTMLAnchorElement): void => {
   setLinkDisabled(link, true);
   setLinkLabel(link, "Copying...");
 };
 
-const finishCopyOperation = (link, ok) => {
+const finishCopyOperation = (link: HTMLAnchorElement, ok: boolean): void => {
   setLinkLabel(link, ok ? "Copied" : "Copy failed");
   closeMenuIfPresent(link);
 };
 
-const scheduleResetOperation = (link, originalLabel) => {
+const scheduleResetOperation = (
+  link: HTMLAnchorElement,
+  originalLabel: string
+): void => {
   window.setTimeout(() => {
     setLinkLabel(link, originalLabel);
     setLinkDisabled(link, false);
   }, RESET_DELAY_MS);
 };
 
-const handleCopyClick = async (link, originalLabel) => {
+const handleCopyClick = async (
+  link: HTMLAnchorElement,
+  originalLabel: string
+): Promise<void> => {
   const href = link.getAttribute("href");
   if (!href) {
     return;
@@ -132,7 +138,7 @@ const handleCopyClick = async (link, originalLabel) => {
   scheduleResetOperation(link, originalLabel);
 };
 
-const attachCopyHandler = (link) => {
+const attachCopyHandler = (link: HTMLAnchorElement): void => {
   const originalLabel = getOriginalLabel(link);
   link.addEventListener("click", async (event) => {
     event.preventDefault();
@@ -143,8 +149,11 @@ const attachCopyHandler = (link) => {
   });
 };
 
-const initCopyMarkdownButtons = () => {
-  const links = [...document.querySelectorAll(COPY_SELECTOR)];
+const initCopyMarkdownButtons = (): void => {
+  const links = [...document.querySelectorAll(COPY_SELECTOR)].filter(
+    (link): link is HTMLAnchorElement => link instanceof HTMLAnchorElement
+  );
+
   for (const link of links) {
     attachCopyHandler(link);
   }

package/templates/default/site/{public/_idcmd/nav-prefetch.js → code/runtime/nav-prefetch.ts}

@@ -1,8 +1,8 @@
 (() => {
   const selector = 'a[data-prefetch="hover"][href]';
-  const prefetched = new Set();
+  const prefetched = new Set<string>();
 
-  const prefetch = (href) => {
+  const prefetch = (href: string | null | undefined): void => {
     if (!href || prefetched.has(href)) {
       return;
     }
@@ -14,7 +14,7 @@
     document.head.append(link);
   };
 
-  const onOver = (event) => {
+  const onOver = (event: Event): void => {
     const { target } = event;
     if (!(target instanceof Element)) {
       return;

package/templates/default/site/{public/_idcmd/right-rail-scrollspy.js → code/runtime/right-rail-scrollspy.ts}

@@ -3,15 +3,16 @@ const TOC_LINK_SELECTOR = 'a[data-toc-link="1"][href^="#"]';
 const TOC_SCROLL_CONTAINER_SELECTOR = '[data-toc-scroll-container="1"]';
 
 const NAVBAR_GAP_PX = 16;
-const clamp = (value, min, max) => Math.min(Math.max(value, min), max);
+const clamp = (value: number, min: number, max: number): number =>
+  Math.min(Math.max(value, min), max);
 
-const getTopOffset = () => {
+const getTopOffset = (): number => {
   const header = document.querySelector("header");
   const headerHeight = header?.getBoundingClientRect().height ?? 0;
   return Math.ceil(headerHeight + NAVBAR_GAP_PX);
 };
 
-const decodeAnchorId = (href) => {
+const decodeAnchorId = (href: string | null): string | null => {
   if (!href?.startsWith("#")) {
     return null;
   }
@@ -28,7 +29,13 @@ const decodeAnchorId = (href) => {
   }
 };
 
-const toEntry = (link) => {
+interface TocEntry {
+  heading: HTMLElement;
+  link: HTMLAnchorElement;
+  y: number;
+}
+
+const toEntry = (link: HTMLAnchorElement): TocEntry | null => {
   const id = decodeAnchorId(link.getAttribute("href"));
   if (!id) {
     return null;
@@ -44,32 +51,39 @@ const toEntry = (link) => {
   return { heading, link, y: 0 };
 };
 
-const buildEntries = (tocRoot) =>
+const buildEntries = (tocRoot: Element): TocEntry[] =>
   [...tocRoot.querySelectorAll(TOC_LINK_SELECTOR)]
+    .filter(
+      (link): link is HTMLAnchorElement => link instanceof HTMLAnchorElement
+    )
     .map(toEntry)
-    .filter((entry) => entry !== null);
+    .filter((entry): entry is TocEntry => entry !== null);
 
-const measureEntries = (entries) => {
+const measureEntries = (entries: TocEntry[]): void => {
   for (const entry of entries) {
     entry.y = entry.heading.getBoundingClientRect().top + window.scrollY;
   }
 };
 
-const setScrollMarginTop = (topOffset) => {
+const setScrollMarginTop = (topOffset: number): void => {
   document.documentElement.style.setProperty(
     "--scroll-margin-top",
     `${topOffset}px`
   );
 };
 
-const binarySearchLastAtOrAbove = (entries, anchorLine) => {
+const binarySearchLastAtOrAbove = (
+  entries: TocEntry[],
+  anchorLine: number
+): number => {
   let lo = 0;
   let hi = entries.length;
 
   // Find the first entry with y > anchorLine, then step back one.
   while (lo < hi) {
     const mid = Math.floor((lo + hi) / 2);
-    if (entries[mid].y <= anchorLine) {
+    const midY = entries[mid]?.y ?? Number.POSITIVE_INFINITY;
+    if (midY <= anchorLine) {
       lo = mid + 1;
     } else {
       hi = mid;
@@ -79,28 +93,30 @@ const binarySearchLastAtOrAbove = (entries, anchorLine) => {
   return lo - 1;
 };
 
-const findActiveIndex = (entries, topOffset) => {
+const findActiveIndex = (entries: TocEntry[], topOffset: number): number => {
   const anchorLine = window.scrollY + topOffset + 1;
   const best = binarySearchLastAtOrAbove(entries, anchorLine);
   return Math.max(0, best);
 };
 
-const parseTransformValues = (transform, prefix) =>
+const parseTransformValues = (transform: string, prefix: string): number[] =>
   transform
     .slice(prefix.length, -1)
     .split(",")
     .map((value) => Number.parseFloat(value.trim()));
 
-const getNumberAtIndex = (values, index) => {
-  const [value] = values.slice(index, index + 1);
+const getNumberAtIndex = (values: number[], index: number): number => {
+  const value = values[index] ?? Number.NaN;
   return Number.isFinite(value) ? value : 0;
 };
 
-const getMatrix3dTranslateY = (values) => getNumberAtIndex(values, 13);
+const getMatrix3dTranslateY = (values: number[]): number =>
+  getNumberAtIndex(values, 13);
 
-const getMatrixTranslateY = (values) => getNumberAtIndex(values, 5);
+const getMatrixTranslateY = (values: number[]): number =>
+  getNumberAtIndex(values, 5);
 
-const getComputedTranslateY = (element) => {
+const getComputedTranslateY = (element: Element): number => {
   const { transform } = window.getComputedStyle(element);
   if (!transform || transform === "none") {
     return 0;
@@ -119,16 +135,20 @@ const getComputedTranslateY = (element) => {
   return 0;
 };
 
-const setTranslateY = (element, next) => {
+const setTranslateY = (element: HTMLElement, next: number): void => {
   element.style.transform = `translate3d(0, ${next}px, 0)`;
 };
 
-const getElementCenterY = (element) => {
+const getElementCenterY = (element: Element): number => {
   const rect = element.getBoundingClientRect();
   return rect.top + rect.height / 2;
 };
 
-const getCenteredTranslateY = (scrollContainer, list, link) => {
+const getCenteredTranslateY = (
+  scrollContainer: HTMLElement,
+  list: HTMLElement,
+  link: HTMLAnchorElement
+): number => {
   const containerHeight = scrollContainer.clientHeight;
   const listHeight = list.scrollHeight;
 
@@ -142,7 +162,20 @@ const getCenteredTranslateY = (scrollContainer, list, link) => {
   return clamp(currentTranslate + delta, minTranslate, 0);
 };
 
-const centerLinkIfNeeded = (state, link) => {
+interface ScrollSpyState {
+  activeIndex: number;
+  centerActiveItem: boolean;
+  entries: TocEntry[];
+  isTicking: boolean;
+  scrollContainer: HTMLElement | null;
+  tocList: HTMLElement | null;
+  topOffset: number;
+}
+
+const centerLinkIfNeeded = (
+  state: ScrollSpyState,
+  link: HTMLAnchorElement
+): void => {
   const { scrollContainer, tocList } = state;
   if (!scrollContainer || !tocList) {
     return;
@@ -157,7 +190,14 @@ const centerLinkIfNeeded = (state, link) => {
   setTranslateY(tocList, next);
 };
 
-const setActiveLink = (state, index) => {
+const setCurrentLocationAttr = (entry: TocEntry | undefined): void => {
+  if (!entry) {
+    return;
+  }
+  entry.link.setAttribute("aria-current", "location");
+};
+
+const setActiveLink = (state: ScrollSpyState, index: number): void => {
   if (index === state.activeIndex) {
     return;
   }
@@ -167,18 +207,18 @@ const setActiveLink = (state, index) => {
 
   state.activeIndex = index;
   const current = state.entries[state.activeIndex];
-  current.link.setAttribute("aria-current", "location");
+  setCurrentLocationAttr(current);
 
-  if (state.centerActiveItem) {
+  if (state.centerActiveItem && current) {
     centerLinkIfNeeded(state, current.link);
   }
 };
 
-const updateActive = (state) => {
+const updateActive = (state: ScrollSpyState): void => {
   setActiveLink(state, findActiveIndex(state.entries, state.topOffset));
 };
 
-const scheduleUpdate = (state) => {
+const scheduleUpdate = (state: ScrollSpyState): void => {
   if (state.isTicking) {
     return;
   }
@@ -190,7 +230,7 @@ const scheduleUpdate = (state) => {
   });
 };
 
-const refreshLayout = (state) => {
+const refreshLayout = (state: ScrollSpyState): void => {
   state.topOffset = getTopOffset();
   setScrollMarginTop(state.topOffset);
   measureEntries(state.entries);
@@ -204,7 +244,7 @@ const refreshLayout = (state) => {
   }
 };
 
-const createState = () => {
+const createState = (): ScrollSpyState | null => {
   const { body } = document;
   const tocRoot = document.querySelector(TOC_ROOT_SELECTOR);
   const entries = tocRoot ? buildEntries(tocRoot) : [];
@@ -226,13 +266,14 @@ const createState = () => {
     centerActiveItem,
     entries,
     isTicking: false,
-    scrollContainer,
-    tocList,
+    scrollContainer:
+      scrollContainer instanceof HTMLElement ? scrollContainer : null,
+    tocList: tocList instanceof HTMLElement ? tocList : null,
     topOffset: getTopOffset(),
   };
 };
 
-const start = (state) => {
+const start = (state: ScrollSpyState): void => {
   // Disable independent TOC scrolling whenever scrollspy is active.
   // The TOC list position is controlled by JS (either centered or left as-is).
   document.body.dataset.tocFollow = "1";
@@ -250,7 +291,7 @@ const start = (state) => {
   refreshLayout(state);
 };
 
-const init = () => {
+const init = (): void => {
   const state = createState();
   if (!state) {
     return;

package/templates/default/site/{server → code}/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 `site/server/routes/**`.
+// V1 runs the built-in idcmd server; add custom endpoints via `site/code/routes/**`.
 
 export const serverPlaceholder = true;