idcmd 0.0.11 → 0.0.12

package/README.md

@@ -22,6 +22,14 @@ idcmd deploy       # build + generate deploy files (Vercel/Fly/Railway)
 idcmd client ...   # add/update local src implementations
 ```
 
+For full command docs (flags, examples, side effects), use:
+
+```bash
+idcmd --help
+idcmd init --help
+idcmd deploy --help
+```
+
 ### Deploy targets
 
 ```bash
@@ -36,7 +44,7 @@ idcmd deploy --vercel
 
 `idcmd init --yes` is provider-neutral by default (no provider files generated).
 
-## Layout (V1)
+## Layout
 
 - `content/<slug>.md` -> `/<slug>/` (`index.md` -> `/`)
 - `src/ui/*` is local UI source code (you own and edit these files)
@@ -80,7 +88,7 @@ This is a new page.
 
 It renders at `/hello/`.
 
-## Custom Server Routes (V1)
+## Custom Server Routes
 
 Add `src/routes/api/hello.ts`:
 
@@ -90,9 +98,9 @@ export const GET = (): Response => Response.json({ ok: true });
 
 It responds at `/api/hello`.
 
-## V1 Definition Of Done
+## Definition Of Done
 
-`tickets/ROADMAP.md` is the source of truth. For V1, we explicitly target:
+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).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "idcmd",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "repository": {
     "type": "git",
     "url": "https://github.com/rustydotwtf/idcmd"
@@ -35,8 +35,7 @@
     "prepare": "lefthook install"
   },
   "dependencies": {
-    "preact": "^10.28.3",
-    "preact-render-to-string": "^6.6.5",
+    "@kitajs/html": "^4.2.13",
     "shiki": "^3.22.0",
     "zod": "^3.24.0"
   },

package/src/cli/commands/build.ts

@@ -25,7 +25,8 @@ export const buildCommand = async (): Promise<number> => {
   const cssProc = Bun.spawn(
     [
       "bunx",
-      "@tailwindcss/cli",
+      "--no-install",
+      "tailwindcss",
       "-i",
       tailwindInput,
       "-o",

package/src/cli/commands/dev.ts

@@ -38,7 +38,8 @@ const spawnCssProcess = (
   Bun.spawn(
     [
       "bunx",
-      "@tailwindcss/cli",
+      "--no-install",
+      "tailwindcss",
       "-i",
       tailwindInput,
       "-o",

package/src/cli/commands/init.ts

@@ -116,7 +116,7 @@ const fillPackageJson = (args: {
     .replaceAll("__IDCMD_IDCMD_VERSION__", `^${args.idcmdVersion}`)
     .replaceAll("__IDCMD_DEV_PORT__", String(args.port));
 
-const fillReadme = (args: { siteName: string; text: string }): string =>
+const fillSiteNameTokens = (args: { siteName: string; text: string }): string =>
   args.text
     .replaceAll("__IDCMD_SITE_NAME__", args.siteName)
     .replaceAll("IDCMD_SITE_NAME", args.siteName);
@@ -253,7 +253,14 @@ const applySubstitutions = async (args: {
   );
 
   await replaceInFile(joinPath(args.targetDir, "README.md"), (text) =>
-    fillReadme({
+    fillSiteNameTokens({
+      siteName: args.siteName,
+      text,
+    })
+  );
+
+  await replaceInFile(joinPath(args.targetDir, "content", "index.md"), (text) =>
+    fillSiteNameTokens({
       siteName: args.siteName,
       text,
     })
@@ -282,7 +289,9 @@ const printNextSteps = (dir: string): void => {
 const assertEmptyTargetDir = async (targetDir: string): Promise<void> => {
   const empty = await isDirEmpty(targetDir);
   if (!empty) {
-    throw new Error(`Target directory is not empty: ${targetDir}`);
+    throw new Error(
+      `Target directory is not empty: ${targetDir}\nUse an empty directory or run \`idcmd init <new-directory>\`.`
+    );
   }
 };
 

package/src/cli/commands/preview.ts

@@ -6,12 +6,15 @@ import {
 const stripLeadingSlash = (pathname: string): string =>
   pathname.startsWith("/") ? pathname.slice(1) : pathname;
 
-const tryServeFile = async (relativePath: string): Promise<Response | null> => {
+const tryServeFile = async (
+  relativePath: string,
+  status = 200
+): Promise<Response | null> => {
   const file = Bun.file(`public/${stripLeadingSlash(relativePath)}`);
   if (!(await file.exists())) {
     return null;
   }
-  return new Response(file);
+  return new Response(file, { status });
 };
 
 const toHtmlEntryPath = (canonicalPathname: string): string =>
@@ -32,10 +35,36 @@ const serveHtml = async (pathname: string): Promise<Response> => {
     return served;
   }
 
-  const notFound = await tryServeFile("404.html");
+  const notFound = await tryServeFile("404.html", 404);
   return notFound ?? new Response("Not Found", { status: 404 });
 };
 
+type ShutdownSignal = "SIGINT" | "SIGTERM";
+
+const waitForShutdownSignal = (): Promise<ShutdownSignal> => {
+  const { promise, resolve } = Promise.withResolvers<ShutdownSignal>();
+
+  const handleSigInt = (): void => {
+    cleanup();
+    resolve("SIGINT");
+  };
+
+  const handleSigTerm = (): void => {
+    cleanup();
+    resolve("SIGTERM");
+  };
+
+  const cleanup = (): void => {
+    process.off("SIGINT", handleSigInt);
+    process.off("SIGTERM", handleSigTerm);
+  };
+
+  process.on("SIGINT", handleSigInt);
+  process.on("SIGTERM", handleSigTerm);
+
+  return promise;
+};
+
 export const previewCommand = async (port: number): Promise<number> => {
   const exists = await Bun.file("public/index.html").exists();
   if (!exists) {
@@ -56,5 +85,9 @@ export const previewCommand = async (port: number): Promise<number> => {
 
   // eslint-disable-next-line no-console
   console.log(`Preview running at http://localhost:${server.port}`);
+
+  await waitForShutdownSignal();
+  server.stop(true);
+
   return 0;
 };

package/src/cli/main.ts

@@ -13,11 +13,24 @@ import { parsePort } from "./normalize";
 import { readPackageVersion } from "./version";
 
 const DEFAULT_PREVIEW_PORT = 4173;
+const DEFAULT_DEV_PORT = 4000;
 
-const usage = (): string =>
+type CommandName = "init" | "dev" | "build" | "preview" | "deploy" | "client";
+
+const isCommandName = (value: string): value is CommandName =>
+  value === "init" ||
+  value === "dev" ||
+  value === "build" ||
+  value === "preview" ||
+  value === "deploy" ||
+  value === "client";
+
+const globalHelp = (): string =>
   [
     "idcmd",
     "",
+    "Static docs site CLI optimized for agent workflows.",
+    "",
     "Usage:",
     "  idcmd init [dir] [--yes] [--name <name>] [--description <text>] [--base-url <url>] [--port <port>] [--no-git] [--vercel|--fly|--railway]",
     "  idcmd dev [--port <port>]",
@@ -26,8 +39,181 @@ const usage = (): string =>
     "  idcmd deploy [--vercel|--fly|--railway]",
     "  idcmd client <add|update> <layout|right-rail|search-page|runtime|all> [--dry-run] [--yes]",
     "",
+    "Agent Quickstart:",
+    "  1. idcmd init my-docs --yes --no-git",
+    "  2. cd my-docs && bun install",
+    `  3. idcmd dev --port ${String(DEFAULT_DEV_PORT)}`,
+    "  4. idcmd build",
+    `  5. idcmd preview --port ${String(DEFAULT_PREVIEW_PORT)}`,
+    "  6. idcmd deploy --vercel|--fly|--railway",
+    "",
+    "Commands:",
+    "  init    Scaffold a new site in a target directory",
+    "  dev     Run SSR server + Tailwind/runtime watchers",
+    "  build   Generate static output in public/",
+    "  preview Serve public/ locally with canonical routing",
+    "  deploy  Build + generate provider config files",
+    "  client  Add/update local UI/runtime baseline files",
+    "",
+    "Help:",
+    "  idcmd --help",
+    "  idcmd <command> --help",
+    "  idcmd --version",
+    "",
   ].join("\n");
 
+const initHelp = (): string =>
+  [
+    "idcmd init",
+    "",
+    "Scaffold a new idcmd site from the default template.",
+    "",
+    "Usage:",
+    "  idcmd init [dir] [--yes] [--name <name>] [--description <text>] [--base-url <url>] [--port <port>] [--no-git] [--vercel|--fly|--railway]",
+    "",
+    "Flags:",
+    "  --yes              Non-interactive defaults",
+    "  --name             Site name in site.jsonc",
+    "  --description      Site description in site.jsonc",
+    "  --base-url         Base URL for canonicals + sitemap",
+    `  --port             Default dev script port (default: ${String(DEFAULT_DEV_PORT)})`,
+    "  --no-git           Skip `git init` in target dir",
+    "  --vercel           Generate vercel.json",
+    "  --fly              Generate fly.toml + Docker files",
+    "  --railway          Generate railway.json + Docker files",
+    "",
+    "Side effects:",
+    "  - Writes template files into target directory",
+    "  - Fails if target directory is not empty",
+    "  - Runs `git init` unless --no-git is set",
+    "",
+    "Examples:",
+    "  idcmd init my-docs --yes --no-git",
+    "  idcmd init apps/docs --yes --base-url https://docs.example.com",
+    "",
+  ].join("\n");
+
+const devHelp = (): string =>
+  [
+    "idcmd dev",
+    "",
+    "Run local development: SSR server + Tailwind + runtime bundling in watch mode.",
+    "",
+    "Usage:",
+    "  idcmd dev [--port <port>]",
+    "",
+    "Flags:",
+    `  --port             HTTP port (default: ${String(DEFAULT_DEV_PORT)})`,
+    "",
+    "Side effects:",
+    "  - Writes compiled runtime scripts to public/_idcmd/*.js",
+    "  - Writes compiled CSS to public/styles.css",
+    "",
+    "Examples:",
+    "  idcmd dev",
+    "  idcmd dev --port 4010",
+    "",
+  ].join("\n");
+
+const buildHelp = (): string =>
+  [
+    "idcmd build",
+    "",
+    "Build static site output in public/.",
+    "",
+    "Usage:",
+    "  idcmd build",
+    "",
+    "What it does:",
+    "  - Compiles runtime assets from src/runtime/ to public/_idcmd/",
+    "  - Builds Tailwind CSS to public/styles.css",
+    "  - Renders markdown pages and metadata outputs (llms.txt, search index, sitemap/robots when baseUrl is set)",
+    "",
+    "Examples:",
+    "  idcmd build",
+    "",
+  ].join("\n");
+
+const previewHelp = (): string =>
+  [
+    "idcmd preview",
+    "",
+    "Serve generated public/ output locally with canonical route behavior.",
+    "",
+    "Usage:",
+    "  idcmd preview [--port <port>]",
+    "",
+    "Flags:",
+    `  --port             HTTP port (default: ${String(DEFAULT_PREVIEW_PORT)})`,
+    "",
+    "Notes:",
+    "  - Requires public/index.html (run idcmd build first)",
+    "",
+    "Examples:",
+    "  idcmd preview",
+    "  idcmd preview --port 5000",
+    "",
+  ].join("\n");
+
+const deployHelp = (): string =>
+  [
+    "idcmd deploy",
+    "",
+    "Build project and print provider-specific deployment guidance.",
+    "",
+    "Usage:",
+    "  idcmd deploy [--vercel|--fly|--railway]",
+    "",
+    "Flags (choose one provider):",
+    "  --vercel           Generate vercel.json",
+    "  --fly              Generate fly.toml + Docker files",
+    "  --railway          Generate railway.json + Docker files",
+    "",
+    "Side effects:",
+    "  - Runs idcmd build first",
+    "  - May write provider config files in project root",
+    "",
+    "Examples:",
+    "  idcmd deploy --vercel",
+    "  idcmd deploy --fly",
+    "",
+  ].join("\n");
+
+const clientHelp = (): string =>
+  [
+    "idcmd client",
+    "",
+    "Copy baseline local implementation files into src/ui/ and src/runtime/.",
+    "",
+    "Usage:",
+    "  idcmd client <add|update> <layout|right-rail|search-page|runtime|all> [--dry-run] [--yes]",
+    "",
+    "Flags:",
+    "  --dry-run          Preview changes without writing files",
+    "  --yes              Skip overwrite prompts for update mode",
+    "",
+    "Side effects:",
+    "  - add: creates missing files only",
+    "  - update: overwrites selected files (requires --yes unless --dry-run)",
+    "",
+    "Examples:",
+    "  idcmd client add all",
+    "  idcmd client update runtime --dry-run",
+    "  idcmd client update layout --yes",
+    "",
+  ].join("\n");
+
+const HELP_BUILDERS: Record<CommandName, () => string> = {
+  build: buildHelp,
+  client: clientHelp,
+  deploy: deployHelp,
+  dev: devHelp,
+  init: initHelp,
+  preview: previewHelp,
+};
+
+const commandHelp = (command: CommandName): string => HELP_BUILDERS[command]();
+
 const asStringFlag = (value: unknown): string | undefined =>
   typeof value === "string" ? value : undefined;
 
@@ -94,6 +280,53 @@ const isHelpCommand = (cmd: string | null): boolean =>
 const isVersionCommand = (cmd: string): boolean =>
   cmd === "--version" || cmd === "-v";
 
+const hasSubcommandHelpFlag = (parsed: ParsedArgs): boolean =>
+  parsed.flags.help === true ||
+  parsed.positionals.includes("--help") ||
+  parsed.positionals.includes("-h");
+
+const maybeHandleGeneralHelp = (cmd: string | null): number | null => {
+  if (!isHelpCommand(cmd)) {
+    return null;
+  }
+  console.log(globalHelp());
+  return 0;
+};
+
+const maybeHandleVersion = async (
+  cmd: string | null
+): Promise<number | null> => {
+  if (!cmd || !isVersionCommand(cmd)) {
+    return null;
+  }
+  console.log(await readPackageVersion());
+  return 0;
+};
+
+const maybeHandleHelpCommand = (parsed: ParsedArgs): number | null => {
+  if (parsed.command !== "help") {
+    return null;
+  }
+  const [topic] = parsed.positionals;
+  if (topic && isCommandName(topic)) {
+    console.log(commandHelp(topic));
+    return 0;
+  }
+  console.log(globalHelp());
+  return 0;
+};
+
+const maybeHandleSubcommandHelp = (parsed: ParsedArgs): number | null => {
+  if (!parsed.command || !isCommandName(parsed.command)) {
+    return null;
+  }
+  if (!hasSubcommandHelpFlag(parsed)) {
+    return null;
+  }
+  console.log(commandHelp(parsed.command));
+  return 0;
+};
+
 export const main = async (argv: string[]): Promise<void> => {
   try {
     const code = await runMain(argv);
@@ -109,7 +342,7 @@ const runMain = async (argv: string[]): Promise<number> => {
   const parsed = parseArgs(argv);
   const cmd = parsed.command;
 
-  const metaCode = await maybeHandleMetaCommand(cmd);
+  const metaCode = await maybeHandleMetaCommand(parsed);
   if (metaCode !== null) {
     return metaCode;
   }
@@ -123,19 +356,16 @@ const runMain = async (argv: string[]): Promise<number> => {
 };
 
 const maybeHandleMetaCommand = async (
-  cmd: string | null
+  parsed: ParsedArgs
 ): Promise<number | null> => {
-  if (isHelpCommand(cmd)) {
-    console.log(usage());
-    return 0;
-  }
-
-  if (cmd && isVersionCommand(cmd)) {
-    console.log(await readPackageVersion());
-    return 0;
-  }
+  const cmd = parsed.command;
 
-  return null;
+  return (
+    maybeHandleGeneralHelp(cmd) ??
+    (await maybeHandleVersion(cmd)) ??
+    maybeHandleHelpCommand(parsed) ??
+    maybeHandleSubcommandHelp(parsed)
+  );
 };
 
 const resolveCommandHandler = (
@@ -149,6 +379,6 @@ const resolveCommandHandler = (
 
 const handleUnknownCommand = (cmd: string | null): number => {
   console.error(`Unknown command: ${cmd ?? "(none)"}`);
-  console.log(usage());
+  console.log(globalHelp());
   return 1;
 };

package/src/render/layout.tsx

@@ -1,7 +1,4 @@
-/* eslint-disable react/no-danger */
-import type { JSX } from "preact";
-
-import { render } from "preact-render-to-string";
+/* eslint-disable react/jsx-key */
 
 import type { NavGroup, NavItem } from "../content/navigation";
 import type { ResolvedRightRailConfig } from "../site/config";
@@ -10,6 +7,8 @@ import type { TocItem } from "./toc";
 
 import { RightRail } from "./right-rail";
 
+const escapeText = (value: string): string => Bun.escapeHTML(value);
+
 export interface LayoutProps {
   title: string;
   siteName: string;
@@ -31,10 +30,7 @@ export interface LayoutProps {
 export type RenderLayout = (props: LayoutProps) => string;
 
 const Icon = ({ svg }: { svg: string }): JSX.Element => (
-  <span
-    class="inline-flex w-[18px] h-[18px]"
-    dangerouslySetInnerHTML={{ __html: svg }}
-  />
+  <span class="inline-flex w-[18px] h-[18px]">{svg}</span>
 );
 
 const isActiveLink = (item: NavItem, currentPath: string): boolean =>
@@ -59,7 +55,7 @@ const NavLink = ({
       class={`flex items-center gap-3 px-3 py-1.5 text-sm hover:text-sidebar-foreground transition-colors ${activeClass}`}
     >
       <Icon svg={item.iconSvg} />
-      <span>{item.title}</span>
+      <span>{escapeText(item.title)}</span>
     </a>
   );
 };
@@ -73,11 +69,11 @@ const NavGroupComponent = ({
 }): JSX.Element => (
   <div class="py-2">
     <div class="px-3 py-2 text-xs font-semibold text-muted-foreground uppercase tracking-wider">
-      {group.label}
+      {escapeText(group.label)}
     </div>
     <nav class="space-y-1">
       {group.items.map((item) => (
-        <NavLink key={item.href} item={item} currentPath={currentPath} />
+        <NavLink item={item} currentPath={currentPath} />
       ))}
     </nav>
   </div>
@@ -100,16 +96,12 @@ const Sidebar = ({
         data-prefetch="hover"
       >
         <span class="text-muted-foreground">~/</span>
-        {siteName}
+        {escapeText(siteName)}
       </a>
     </div>
     <div class="sidebar-content">
       {navigation.map((group) => (
-        <NavGroupComponent
-          key={group.id}
-          group={group}
-          currentPath={currentPath}
-        />
+        <NavGroupComponent group={group} currentPath={currentPath} />
       ))}
     </div>
   </aside>
@@ -121,19 +113,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>
@@ -155,7 +148,7 @@ const TopNavbar = ({
           data-prefetch="hover"
         >
           <span class="text-muted-foreground">~/</span>
-          {siteName}
+          {escapeText(siteName)}
         </a>
         <div class="not-prose w-full max-w-xs ml-auto">
           <SearchForm query={query} />
@@ -183,14 +176,16 @@ const DocumentHead = ({
   <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"
@@ -269,8 +264,10 @@ const DocumentBody = ({
         <div class="mx-auto flex w-full max-w-6xl items-start gap-10">
           <article
             class={`prose min-w-0 flex-1${currentPath === "/" ? " prose-home" : ""}`}
-            dangerouslySetInnerHTML={{ __html: content }}
-          />
+          >
+            {/* content is pre-rendered markdown HTML */}
+            {content}
+          </article>
           {shouldShowRightRail ? (
             <RightRailComponent
               canonicalUrl={canonicalUrl}
@@ -282,12 +279,12 @@ const DocumentBody = ({
         </div>
       </main>
       <footer class="site-footer">
-        Built with Preact SSR + Tailwind &nbsp;|&nbsp; Zero JavaScript on
-        content pages
+        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>
 );
@@ -344,4 +341,4 @@ const Layout = ({
 };
 
 export const renderLayout: RenderLayout = (props) =>
-  `<!DOCTYPE html>${render(<Layout {...props} />)}`;
+  `<!DOCTYPE html>${<Layout {...props} />}`;

package/src/render/right-rail.tsx

@@ -1,8 +1,10 @@
-import type { JSX } from "preact";
+/* eslint-disable react/jsx-key */
 
 import type { ResolvedRightRailConfig } from "../site/config";
 import type { TocItem } from "./toc";
 
+const escapeText = (value: string): string => Bun.escapeHTML(value);
+
 const CaretDownIcon = (): JSX.Element => (
   <svg
     width="16"
@@ -171,13 +173,13 @@ const OnThisPage = ({ items }: { items: TocItem[] }): JSX.Element => (
       <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>
           ))}