idcmd 0.0.11 → 0.0.13

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.13",
   "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;
 };