From 2455c871671e6d042da971d7bf18175ae5cd8a75 Mon Sep 17 00:00:00 2001
From: saberzero1 <github@emilebangma.com>
Date: Sun, 24 May 2026 17:23:11 +0200
Subject: [PATCH] fix: show help on invalid CLI commands and debounce watch
 rebuilds

- Change .showHelpOnFail(false) to true for better new-user UX
- Add 100ms debounce to watch mode rebuilds to batch rapid file changes
---
 quartz/bootstrap-cli.mjs |  2 +-
 quartz/build.ts          | 22 +++++++++++++---------
 2 files changed, 14 insertions(+), 10 deletions(-)

diff --git a/quartz/bootstrap-cli.mjs b/quartz/bootstrap-cli.mjs
index 99332ba..34288c7 100755
--- a/quartz/bootstrap-cli.mjs
+++ b/quartz/bootstrap-cli.mjs
@@ -278,7 +278,7 @@ yargs(hideBin(process.argv))
       await handlePluginStatus()
     },
   )
-  .showHelpOnFail(false)
+  .showHelpOnFail(true)
   .help()
   .strict()
   .demandCommand().argv
diff --git a/quartz/build.ts b/quartz/build.ts
index 4b67760..3d73641 100644
--- a/quartz/build.ts
+++ b/quartz/build.ts
@@ -165,30 +165,34 @@ async function startWatching(
   })
 
   const changes: ChangeEvent[] = []
+  let rebuildTimeout: ReturnType<typeof setTimeout> | null = null
+  const scheduleRebuild = () => {
+    if (rebuildTimeout) clearTimeout(rebuildTimeout)
+    rebuildTimeout = setTimeout(() => {
+      rebuildTimeout = null
+      rebuild(changes, clientRefresh, buildData).catch((err) => {
+        console.error(styleText("red", "Rebuild failed:"), err.message ?? err)
+      })
+    }, 100)
+  }
   watcher
     .on("add", (fp) => {
       fp = toPosixPath(fp)
       if (buildData.ignored(fp)) return
       changes.push({ path: fp as FilePath, type: "add" })
-      rebuild(changes, clientRefresh, buildData).catch((err) => {
-        console.error(styleText("red", "Rebuild failed:"), err.message ?? err)
-      })
+      scheduleRebuild()
     })
     .on("change", (fp) => {
       fp = toPosixPath(fp)
       if (buildData.ignored(fp)) return
       changes.push({ path: fp as FilePath, type: "change" })
-      rebuild(changes, clientRefresh, buildData).catch((err) => {
-        console.error(styleText("red", "Rebuild failed:"), err.message ?? err)
-      })
+      scheduleRebuild()
     })
     .on("unlink", (fp) => {
       fp = toPosixPath(fp)
       if (buildData.ignored(fp)) return
       changes.push({ path: fp as FilePath, type: "delete" })
-      rebuild(changes, clientRefresh, buildData).catch((err) => {
-        console.error(styleText("red", "Rebuild failed:"), err.message ?? err)
-      })
+      scheduleRebuild()
     })
 
   return async () => {