for-humanity 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+## 0.4.1 — 2026-10-04
+
+- Coalesce consecutive document and asset saves and serialize dev refreshes so bulk AI edits cannot start overlapping full-site renders and exhaust memory.
+- Continue queued and later edits after failed processing, and apply only the latest valid generation.
+
 ## 0.4.0 — 2026-10-04
 
 - Copy explicitly referenced local images and supported attachments to fingerprinted asset URLs, resolving paths relative to their Markdown files in both build and dev.

package/README.md

@@ -33,7 +33,7 @@ Write Markdown. Keep the context. Share a static site.
 Node.js 22 or later and pnpm. Install the CLI in your document project:
 
 ```sh
-pnpm add -D --save-exact for-humanity@0.4.0
+pnpm add -D --save-exact for-humanity@0.4.1
 mkdir docs
 ```
 
@@ -52,7 +52,7 @@ pnpm exec for-humanity preview docs
 
 If your Markdown files are in the project root, use `.` instead of `docs`. The root `README.md` becomes the home page; root `AGENTS.md` and `CLAUDE.md` stay out of the site.
 
-Version `0.4.0` supports `dev`, `build` and `preview`. `init` is planned; see the [Roadmap](https://github.com/minu-ha/for-humanity/blob/main/templates/document/roadmap.md) and [Changelog](https://github.com/minu-ha/for-humanity/blob/main/CHANGELOG.md).
+Version `0.4.1` supports `dev`, `build` and `preview`. `init` is planned; see the [Roadmap](https://github.com/minu-ha/for-humanity/blob/main/templates/document/roadmap.md) and [Changelog](https://github.com/minu-ha/for-humanity/blob/main/CHANGELOG.md).
 Cloudflare Pages can host the generated site. See [Deployment](https://github.com/minu-ha/for-humanity/blob/main/templates/document/deployment.md) for the build settings.
 
 ### Develop the kit
@@ -74,7 +74,7 @@ pnpm preview    # Preview the static site
 pnpm build:pages # Add Cloudflare Pages headers and a 404 page
 ```
 
-Changes pushed to `main` update the documentation site. A stable version tag such as `v0.4.0` runs checks, publishes the package to npm, then creates a GitHub Release with the same package file.
+Changes pushed to `main` update the documentation site. A stable version tag such as `v0.4.1` runs checks, publishes the package to npm, then creates a GitHub Release with the same package file.
 The npm README updates with each package release. See [Maintenance](https://github.com/minu-ha/for-humanity/blob/main/templates/document/maintenance.md#packaging-and-release) for the release steps.
 
 ## Make it yours

package/dist/cli.js

@@ -8,6 +8,7 @@ import { basename as basename2, dirname as dirname4, extname as extname4, join a
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { serve } from "@hono/node-server";
 import { serveStatic } from "@hono/node-server/serve-static";
+import { debounce } from "es-toolkit";
 import { Hono as Hono3 } from "hono";
 import { toSSG } from "hono/ssg";
 
@@ -349,6 +350,7 @@ var cli_default_command = "dev";
 var cli_default_docs_dir = ".";
 var cli_config_file_name = "for-humanity.config.mjs";
 var cli_dev_port = 4321;
+var cli_reload_delay_ms = 150;
 
 // src/constant/font.ts
 var font_sans_css = "src/asset/font/pretendard/pretendardvariable-dynamic-subset.css";
@@ -1288,6 +1290,32 @@ var siteConfigSchema = z3.object({
   ).default(status_default_phrases)
 });
 
+// src/util/async/to-change-queue.ts
+var toChangeQueue = (options) => {
+  const state = { requested: 0, completed: 0, running: false };
+  return async () => {
+    state.requested += 1;
+    if (state.running) {
+      return;
+    }
+    state.running = true;
+    try {
+      while (state.completed !== state.requested) {
+        const requested = state.requested;
+        try {
+          await options.run();
+        } catch (error) {
+          options.onError(error);
+        } finally {
+          state.completed = requested;
+        }
+      }
+    } finally {
+      state.running = false;
+    }
+  };
+};
+
 // src/util/error/to-error-message.ts
 var toErrorMessage = (error) => {
   if (error instanceof Error && "file" in error && typeof error.file === "string" && "line" in error && typeof error.line === "number") {
@@ -1390,31 +1418,37 @@ var main = async () => {
   const reload = new EventEmitter();
   let generation = 0;
   serve({ fetch: createDevApp({ pages: app, files, reload }).fetch, port: cli_dev_port }, (info) => console.log(`http://localhost:${info.port}/`));
-  const handleDocsChange = async (_event, filename) => {
+  const reloadDocs = debounce(
+    toChangeQueue({
+      run: async () => {
+        const currentGeneration = generation;
+        const nextFiles = new Map(kitFiles);
+        const nextProcessor = createProcessor({ site: siteConfig, root: docsRoot, files: nextFiles });
+        const [docs2, home2] = await Promise.all([readDocs({ root: docsRoot, processor: nextProcessor }), readHome({ root: docsRoot, processor: nextProcessor })]);
+        if (currentGeneration !== generation) {
+          return;
+        }
+        files.clear();
+        for (const entry of nextFiles) {
+          files.set(...entry);
+        }
+        store.docs = docs2;
+        store.home = home2;
+        reload.emit("change");
+      },
+      onError: (error) => console.error(`${copy_error_prefix}: ${toErrorMessage(error)}`)
+    }),
+    cli_reload_delay_ms
+  );
+  const handleDocsChange = (_event, filename) => {
     if (filename !== null) {
       const segments = filename.split(sep3);
       if (segments.includes("dist") || segments.includes("node_modules") || !/\.mdx?$/i.test(filename) && !asset_media_extensions.has(extname4(filename).toLowerCase())) {
         return;
       }
     }
-    const currentGeneration = ++generation;
-    try {
-      const nextFiles = new Map(kitFiles);
-      const nextProcessor = createProcessor({ site: siteConfig, root: docsRoot, files: nextFiles });
-      const [docs2, home2] = await Promise.all([readDocs({ root: docsRoot, processor: nextProcessor }), readHome({ root: docsRoot, processor: nextProcessor })]);
-      if (currentGeneration !== generation) {
-        return;
-      }
-      files.clear();
-      for (const entry of nextFiles) {
-        files.set(...entry);
-      }
-      store.docs = docs2;
-      store.home = home2;
-      reload.emit("change");
-    } catch (error) {
-      console.error(`${copy_error_prefix}: ${toErrorMessage(error)}`);
-    }
+    generation += 1;
+    reloadDocs();
   };
   watch(docsRoot, { recursive: true }, handleDocsChange);
 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "for-humanity",
-    "version": "0.4.0",
+    "version": "0.4.1",
     "description": "Documents written for humans to read: a docs kit with a sidebar, parts, sections and flowcharts, built on Hono and React",
     "keywords": [
         "docs",
@@ -41,7 +41,7 @@
         "build": "pnpm sync:docs && pnpm build:kit && node dist/cli.js build templates/document",
         "build:pages": "pnpm build && node util/prepare-pages.mjs",
         "preview": "node dist/cli.js preview templates/document",
-        "test": "esbuild src/util/font/to-font-css.test.ts src/content/read-docs.test.ts --bundle --platform=node --format=esm --packages=external --outbase=src --outdir=node_modules/.cache/for-humanity-tests --out-extension:.js=.mjs && node --test node_modules/.cache/for-humanity-tests/content/*.test.mjs node_modules/.cache/for-humanity-tests/util/font/*.test.mjs util/*.test.mjs",
+        "test": "esbuild src/util/async/to-change-queue.test.ts src/util/font/to-font-css.test.ts src/content/read-docs.test.ts --bundle --platform=node --format=esm --packages=external --outbase=src --outdir=node_modules/.cache/for-humanity-tests --out-extension:.js=.mjs && node --test node_modules/.cache/for-humanity-tests/util/async/*.test.mjs node_modules/.cache/for-humanity-tests/content/*.test.mjs node_modules/.cache/for-humanity-tests/util/font/*.test.mjs util/*.test.mjs",
         "lint": "biome check && stylelint \"src/**/*.css\"",
         "lint:fix": "biome check --write && stylelint \"src/**/*.css\" --fix",
         "typecheck": "tsc --noEmit",

package/src/cli.ts

@@ -11,11 +11,12 @@ import {basename, dirname, extname, join, relative, resolve, sep} from "node:pat
 import {fileURLToPath, pathToFileURL} from "node:url";
 import {serve} from "@hono/node-server";
 import {serveStatic} from "@hono/node-server/serve-static";
+import {debounce} from "es-toolkit";
 import {Hono} from "hono";
 import {toSSG} from "hono/ssg";
 import {createApp} from "@/app";
 import {asset_client_path, asset_favicon_path, asset_font_dir, asset_media_extensions, asset_style_path} from "@/constant/asset";
-import {cli_config_file_name, cli_default_command, cli_default_docs_dir, cli_dev_port} from "@/constant/cli";
+import {cli_config_file_name, cli_default_command, cli_default_docs_dir, cli_dev_port, cli_reload_delay_ms} from "@/constant/cli";
 import {copy_error_config, copy_error_font_preload, copy_error_prefix, copy_error_unknown_command} from "@/constant/copy";
 import {font_brand_css, font_cache_control, font_mono_css, font_sans_css, font_sans_preload_file} from "@/constant/font";
 import {site_config_absent} from "@/constant/site";
@@ -24,6 +25,7 @@ import {readDocs} from "@/content/read-docs";
 import {readHome} from "@/content/read-home";
 import {createDevApp} from "@/dev";
 import {siteConfigSchema} from "@/type/site-config";
+import {toChangeQueue} from "@/util/async/to-change-queue";
 import {toErrorMessage} from "@/util/error/to-error-message";
 import {toAssetPath} from "@/util/file/to-asset-path";
 import {toFontCss} from "@/util/font/to-font-css";
@@ -129,40 +131,46 @@ const main = async () => {
     serve({fetch: createDevApp({pages: app, files, reload}).fetch, port: cli_dev_port}, (info) => console.log(`http://localhost:${info.port}/`));
 
     /**
-     * Markdown 변경 시 전체 재처리와 새로고침
-     * 재처리 실패 시 직전 정상 문서 유지
+     * 갱신은 하나씩 실행 · 연속 저장 합치기 · 최신 변경만 적용
+     * 문서 수가 많아도 파일 이벤트마다 전체 렌더링이 동시에 쌓이지 않음
      */
-    const handleDocsChange = async (_event: string, filename: string | null) => {
+    const reloadDocs = debounce(
+        toChangeQueue({
+            run: async () => {
+                const currentGeneration = generation;
+                const nextFiles = new Map(kitFiles);
+                const nextProcessor = createProcessor({site: siteConfig, root: docsRoot, files: nextFiles});
+                const [docs, home] = await Promise.all([readDocs({root: docsRoot, processor: nextProcessor}), readHome({root: docsRoot, processor: nextProcessor})]);
+
+                if (currentGeneration !== generation) {
+                    return;
+                }
+
+                files.clear();
+                for (const entry of nextFiles) {
+                    files.set(...entry);
+                }
+                store.docs = docs;
+                store.home = home;
+                reload.emit("change");
+            },
+            onError: (error) => console.error(`${copy_error_prefix}: ${toErrorMessage(error)}`),
+        }),
+        cli_reload_delay_ms,
+    );
+
+    /**
+     * 입력 변경 감지 · 출력·설치 폴더 제외 · 누락 자원 추가도 다시 확인
+     */
+    const handleDocsChange = (_event: string, filename: string | null) => {
         if (filename !== null) {
             const segments = filename.split(sep);
-            // 출력·설치 폴더는 제외 · 실패한 참조의 파일이 뒤늦게 생겨도 다시 처리
             if (segments.includes("dist") || segments.includes("node_modules") || (!/\.mdx?$/i.test(filename) && !asset_media_extensions.has(extname(filename).toLowerCase()))) {
                 return;
             }
         }
-
-        const currentGeneration = ++generation;
-
-        try {
-            const nextFiles = new Map(kitFiles);
-            const nextProcessor = createProcessor({site: siteConfig, root: docsRoot, files: nextFiles});
-            const [docs, home] = await Promise.all([readDocs({root: docsRoot, processor: nextProcessor}), readHome({root: docsRoot, processor: nextProcessor})]);
-
-            // 최신 변경의 처리 결과만 반영
-            if (currentGeneration !== generation) {
-                return;
-            }
-
-            files.clear();
-            for (const entry of nextFiles) {
-                files.set(...entry);
-            }
-            store.docs = docs;
-            store.home = home;
-            reload.emit("change");
-        } catch (error) {
-            console.error(`${copy_error_prefix}: ${toErrorMessage(error)}`);
-        }
+        generation += 1;
+        reloadDocs();
     };
 
     watch(docsRoot, {recursive: true}, handleDocsChange);

package/src/constant/cli.ts

@@ -17,3 +17,8 @@ export const cli_config_file_name = "for-humanity.config.mjs";
  * dev·preview 공통 포트
  */
 export const cli_dev_port = 4321;
+
+/**
+ * 연속 저장을 하나의 문서 갱신으로 합치는 대기 시간 · ms
+ */
+export const cli_reload_delay_ms = 150;

package/src/util/async/to-change-queue.test.ts

@@ -0,0 +1,58 @@
+import assert from "node:assert/strict";
+import {test} from "node:test";
+import {toChangeQueue} from "@/util/async/to-change-queue";
+
+test("coalesces changes during an active render and never overlaps work", async () => {
+    const gate = Promise.withResolvers<void>();
+    const renders: number[] = [];
+    const errors: unknown[] = [];
+    let version = 1;
+    let running = 0;
+    const queue = toChangeQueue({
+        run: async () => {
+            running += 1;
+            assert.equal(running, 1);
+            const current = version;
+            if (current === 1) await gate.promise;
+            renders.push(current);
+            running -= 1;
+        },
+        onError: (error) => errors.push(error),
+    });
+    const first = queue();
+    for (const next of [2, 3, 4, 5]) {
+        version = next;
+        await queue();
+    }
+    gate.resolve();
+    await first;
+    assert.deepEqual(renders, [1, 5]);
+    assert.deepEqual(errors, []);
+});
+
+test("a failed render does not lose a queued recovery or block later edits", async () => {
+    const gate = Promise.withResolvers<void>();
+    const errors: unknown[] = [];
+    const renders: number[] = [];
+    let version = 1;
+    const queue = toChangeQueue({
+        run: async () => {
+            const current = version;
+            if (current === 1) {
+                await gate.promise;
+                throw new Error("Invalid source");
+            }
+            renders.push(current);
+        },
+        onError: (error) => errors.push(error),
+    });
+    const first = queue();
+    version = 2;
+    await queue();
+    gate.resolve();
+    await first;
+    version = 3;
+    await queue();
+    assert.deepEqual(renders, [2, 3]);
+    assert.equal(errors.length, 1);
+});

package/src/util/async/to-change-queue.ts

@@ -0,0 +1,43 @@
+/**
+ * 변경 재처리의 실행과 오류 보고 계약
+ */
+export interface ChangeQueueOptions {
+    /**
+     * 한 번의 최신 입력 처리 · 이전 실행이 끝난 뒤 호출
+     */
+    run: () => Promise<void>;
+    /**
+     * 실패 보고 · 대기 중인 변경과 다음 실행은 유지
+     */
+    onError: (error: unknown) => void;
+}
+
+/**
+ * 동시에 하나만 실행하는 변경 요청 함수 · 실행 중 요청은 다음 한 번으로 합침
+ * 활성 실행의 반환 Promise는 대기 요청까지 끝나면 완료, 중첩 요청은 즉시 반환
+ */
+export const toChangeQueue = (options: ChangeQueueOptions) => {
+    const state = {requested: 0, completed: 0, running: false};
+
+    return async () => {
+        state.requested += 1;
+        if (state.running) {
+            return;
+        }
+        state.running = true;
+        try {
+            while (state.completed !== state.requested) {
+                const requested = state.requested;
+                try {
+                    await options.run();
+                } catch (error) {
+                    options.onError(error);
+                } finally {
+                    state.completed = requested;
+                }
+            }
+        } finally {
+            state.running = false;
+        }
+    };
+};