for-humanity 0.12.0 → 0.13.0

package/src/entry/cli/cli.ts

@@ -1,206 +0,0 @@
-#!/usr/bin/env node
-/*
- * CLI · for-humanity <dev|build|preview> [문서 폴더]
- * 기본 문서 폴더: 현재 폴더 · 출력: <문서 폴더>/dist
- */
-
-import {EventEmitter} from "node:events";
-import {existsSync, readFileSync, watch} from "node:fs";
-import {copyFile, mkdir, rm, writeFile} from "node:fs/promises";
-import {dirname, extname, join, relative, resolve, sep} from "node:path";
-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 {asset_favicon_path, asset_font_dir, asset_media_extensions, asset_style_path} from "@/constant/asset";
-import {copy_error_config, copy_error_prefix, copy_error_unknown_command} from "@/constant/copy";
-import {font_body_css, font_brand_css, font_cache_control, font_mono_css} from "@/constant/font";
-import {site_config_absent} from "@/constant/site";
-import {cli_config_file_name, cli_default_command, cli_default_docs_dir, cli_reload_delay_ms} from "@/entry/cli/_constant/cli";
-import {crawling_reserved_roots} from "@/entry/cli/_constant/crawling";
-import {createApp} from "@/entry/cli/_function/create-app";
-import {createDevApp} from "@/entry/cli/_function/create-dev-app";
-import {createProcessor} from "@/entry/cli/_function/create-processor/create-processor";
-import {readDocs} from "@/entry/cli/_function/read-docs";
-import {readHome} from "@/entry/cli/_function/read-home";
-import {toCrawlingApp} from "@/entry/cli/_function/to-crawling-app";
-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";
-
-const commands = ["dev", "build", "preview"];
-const [command = cli_default_command, docsDir = cli_default_docs_dir] = process.argv.slice(2);
-
-/**
- * 명령 실행 · 설정 검증, 렌더링, 빌드·서버 시작
- * 실패: 터미널 오류와 종료 코드 1
- */
-const main = async () => {
-    if (!commands.includes(command)) {
-        throw new Error(`${copy_error_unknown_command}: ${command} (${commands.join(", ")})`);
-    }
-
-    // dist/cli.js 기준 패키지 루트
-    const kitRoot = fileURLToPath(new URL("../", import.meta.url));
-    const docsRoot = resolve(docsDir);
-    const outDir = join(docsRoot, "dist");
-    const configFile = join(docsRoot, cli_config_file_name);
-    const parsedConfig = siteConfigSchema.safeParse(existsSync(configFile) ? (await import(pathToFileURL(configFile).href)).default : site_config_absent);
-
-    if (!parsedConfig.success) {
-        throw new Error(`${copy_error_config}: ${parsedConfig.error.issues.map((issue) => `${issue.path.join(".")} ${issue.message}`).join(", ")}`);
-    }
-
-    const siteConfig = parsedConfig.data;
-
-    if (command === "preview") {
-        const app = new Hono();
-
-        app.use(
-            "/*",
-            serveStatic({
-                root: relative(process.cwd(), outDir),
-                onFound: (_path, c) => {
-                    if (c.req.path.startsWith(`${asset_font_dir}/`)) {
-                        c.header("Cache-Control", font_cache_control);
-                    }
-                },
-            }),
-        );
-        serve({fetch: app.fetch, port: siteConfig.port}, (info) => console.log(`http://localhost:${info.port}/`));
-
-        return;
-    }
-
-    // 내장 @font-face와 파일 수집 · font-family는 token.css 소유
-    const mono = toFontCss({css: join(kitRoot, font_mono_css), fontDir: asset_font_dir});
-    const body = toFontCss({css: join(kitRoot, font_body_css), fontDir: asset_font_dir});
-    const brand = toFontCss({css: join(kitRoot, font_brand_css), fontDir: asset_font_dir});
-
-    const fontCss = [mono.css, body.css, brand.css].join("\n");
-    const stylePath = toAssetPath({path: asset_style_path, file: join(kitRoot, "dist/cli.css")});
-    const browserScript = readFileSync(join(kitRoot, "dist/browser.js"), "utf8");
-    const kitFiles = new Map([
-        [stylePath, join(kitRoot, "dist/cli.css")],
-        [asset_favicon_path, join(kitRoot, "src/asset/favicon.svg")],
-        ...mono.files,
-        ...body.files,
-        ...brand.files,
-    ]);
-    const files = new Map(kitFiles);
-    const snippets = new Set<string>();
-    const processor = createProcessor({site: siteConfig, root: docsRoot, files, snippets});
-    const [docs, home] = await Promise.all([
-        readDocs({root: docsRoot, processor, reserved: siteConfig.url === undefined ? undefined : crawling_reserved_roots}),
-        readHome({root: docsRoot, processor}),
-    ]);
-    const store = {docs, home};
-    const crawling = siteConfig.url === undefined ? undefined : toCrawlingApp({url: siteConfig.url, store});
-    const app = createApp({
-        site: siteConfig,
-        store,
-        assets: {stylePath, browserScript, fontCss, preload: [...brand.files.keys(), ...mono.files.keys(), ...body.files.keys()], reload: command === "dev"},
-    });
-
-    if (command === "build") {
-        // 삭제된 문서·자원의 잔여 파일 방지
-        await rm(outDir, {recursive: true, force: true});
-
-        const result = await toSSG(app, {writeFile, mkdir}, {dir: outDir});
-
-        if (!result.success) {
-            throw result.error;
-        }
-
-        const crawlerResult = crawling === undefined ? undefined : await toSSG(crawling, {writeFile, mkdir}, {dir: outDir});
-
-        if (crawlerResult?.success === false) {
-            throw crawlerResult.error;
-        }
-
-        for (const [url, file] of files) {
-            await mkdir(dirname(join(outDir, url)), {recursive: true});
-            await copyFile(file, join(outDir, url));
-        }
-
-        console.log(
-            `${crawlerResult === undefined ? result.files.length : result.files.length + crawlerResult.files.length} files, ${files.size} assets → ${relative(process.cwd(), outDir)}`,
-        );
-
-        return;
-    }
-
-    const reload = new EventEmitter();
-    let generation = 0;
-
-    serve({fetch: createDevApp({pages: app, crawling, files, reload}).fetch, port: siteConfig.port}, (info) => console.log(`http://localhost:${info.port}/`));
-
-    /**
-     * 갱신은 하나씩 실행 · 연속 저장 합치기 · 최신 변경만 적용
-     * 문서 수가 많아도 파일 이벤트마다 전체 렌더링이 동시에 쌓이지 않음
-     */
-    const reloadDocs = debounce(
-        toChangeQueue({
-            run: async () => {
-                const currentGeneration = generation;
-                const nextFiles = new Map(kitFiles);
-                const nextSnippets = new Set<string>();
-                const nextProcessor = createProcessor({site: siteConfig, root: docsRoot, files: nextFiles, snippets: nextSnippets});
-                const [docs, home] = await Promise.all([
-                    readDocs({root: docsRoot, processor: nextProcessor, reserved: siteConfig.url === undefined ? undefined : crawling_reserved_roots}),
-                    readHome({root: docsRoot, processor: nextProcessor}),
-                ]);
-
-                if (currentGeneration !== generation) {
-                    return;
-                }
-
-                files.clear();
-                for (const entry of nextFiles) {
-                    files.set(...entry);
-                }
-                snippets.clear();
-                for (const entry of nextSnippets) {
-                    snippets.add(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);
-            const isSnippet = snippets.has(join(docsRoot, filename));
-            if (
-                segments.includes("dist") ||
-                segments.includes("node_modules") ||
-                (!isSnippet && !/\.mdx?$/i.test(filename) && !asset_media_extensions.has(extname(filename).toLowerCase()))
-            ) {
-                return;
-            }
-        }
-        generation += 1;
-        reloadDocs();
-    };
-
-    watch(docsRoot, {recursive: true}, handleDocsChange);
-};
-
-try {
-    await main();
-} catch (error) {
-    console.error(`${copy_error_prefix}: ${toErrorMessage(error)}`);
-    process.exit(1);
-}

package/src/env.d.ts

@@ -1,6 +0,0 @@
-/// <reference types="mdast-util-to-hast" />
-
-/**
- * 컴포넌트 CSS 부수효과 import · esbuild CSS 묶음 대상
- */
-declare module "*.css";

package/src/page/doc/pg-doc.tsx

@@ -1,35 +0,0 @@
-import {WgProse} from "@/component/widget/prose/wg-prose";
-import {WgShell} from "@/component/widget/shell/wg-shell";
-import type {Doc} from "@/type/doc";
-import type {SiteAssets} from "@/type/site-assets";
-import type {SiteConfig} from "@/type/site-config";
-
-/**
- * /:slug/ 문서 페이지 입력 · 렌더링된 HTML 사용
- */
-export interface PgDocProps {
-    /**
-     * 검증된 사이트 설정
-     */
-    site: SiteConfig;
-    /**
-     * 사이드바의 전체 문서
-     */
-    docs: Doc[];
-    /**
-     * HTML 머리의 공통 자원
-     */
-    assets: SiteAssets;
-    /**
-     * 현재 페이지의 문서
-     */
-    doc: Doc;
-}
-
-export const PgDoc = (props: PgDocProps) => {
-    return (
-        <WgShell site={props.site} docs={props.docs} assets={props.assets} title={props.doc.data.name} current={props.doc.id} outline={props.doc.outline}>
-            <WgProse html={props.doc.html} />
-        </WgShell>
-    );
-};

package/src/page/home/pg-home.tsx

@@ -1,40 +0,0 @@
-import {WgProse} from "@/component/widget/prose/wg-prose";
-import {WgShell} from "@/component/widget/shell/wg-shell";
-import {copy_home_missing} from "@/constant/copy";
-import type {Doc} from "@/type/doc";
-import type {DocContent} from "@/type/doc-content";
-import type {SiteAssets} from "@/type/site-assets";
-import type {SiteConfig} from "@/type/site-config";
-
-/**
- * / 첫 화면 입력 · 문서 폴더 README의 본문과 목차
- */
-export interface PgHomeProps {
-    /**
-     * 검증된 사이트 설정
-     */
-    site: SiteConfig;
-    /**
-     * 사이드바의 전체 문서
-     */
-    docs: Doc[];
-    /**
-     * HTML 머리의 공통 자원
-     */
-    assets: SiteAssets;
-    /**
-     * README 렌더링 결과 · 파일이 없으면 작성 안내
-     */
-    home?: DocContent;
-}
-
-export const PgHome = (props: PgHomeProps) => {
-    return (
-        <WgShell site={props.site} docs={props.docs} assets={props.assets} outline={props.home?.outline}>
-            {/**
-             * README 원문 · 없을 때만 파일 작성 안내
-             */}
-            {props.home === undefined ? <WgProse head={{title: props.site.title, lead: copy_home_missing}} /> : <WgProse html={props.home.html} />}
-        </WgShell>
-    );
-};

package/src/store/navigation/create-navigation-stores.test.ts

@@ -1,74 +0,0 @@
-import assert from "node:assert/strict";
-import {test} from "node:test";
-import {createNavigationStores} from "@/store/navigation/create-navigation-stores";
-import {navigation_scroll_storage_key} from "@/store/navigation/navigation-storage";
-
-const fixture = () => {
-    const session = new Map<string, string>();
-    const storage = {
-        getItem: (key: string) => {
-            const value = session.get(key);
-            return value === undefined ? null : value;
-        },
-        setItem: (key: string, value: string) => {
-            session.set(key, value);
-        },
-        removeItem: (key: string) => {
-            session.delete(key);
-        },
-    };
-    return {session, options: {session: () => storage}};
-};
-
-test("retains independent wide, desktop and drawer scroll positions within a tab", () => {
-    const setup = fixture();
-    const stores = createNavigationStores(setup.options);
-    stores.scroll.setState({
-        positions: {
-            wide: {navigation: "docs", pathname: "/one/", documents: 450, outline: 300},
-            desktop: {navigation: "docs", pathname: "/two/", documents: 750, outline: 100},
-            drawer: {navigation: "docs", pathname: "/one/", documents: 200, outline: 800},
-        },
-    });
-    assert.deepEqual(createNavigationStores(setup.options).scroll.getState(), stores.scroll.getState());
-});
-
-test("rejects malformed and unknown-version persistence without losing defaults", () => {
-    for (const value of ["{", "null", '{"state":null,"version":1}', '{"state":{"positions":{}},"version":999}']) {
-        const setup = fixture();
-        setup.session.set(navigation_scroll_storage_key, value);
-        const stores = createNavigationStores(setup.options);
-        assert.deepEqual(stores.scroll.getState(), {positions: {}});
-    }
-});
-
-test("rejects invalid scroll coordinates", () => {
-    const setup = fixture();
-    setup.session.set(
-        navigation_scroll_storage_key,
-        JSON.stringify({
-            version: 1,
-            state: {
-                positions: {
-                    desktop: {navigation: "docs", pathname: "/one/", documents: -1, outline: 0},
-                    wide: {navigation: "docs", pathname: "/one/", documents: 100, outline: 20},
-                    drawer: {navigation: "docs", pathname: "/one/", documents: 100, outline: "20"},
-                },
-            },
-        }),
-    );
-    const stores = createNavigationStores(setup.options);
-    assert.deepEqual(stores.scroll.getState().positions.wide, {navigation: "docs", pathname: "/one/", documents: 100, outline: 20});
-    assert.equal(stores.scroll.getState().positions.desktop, undefined);
-    assert.equal(stores.scroll.getState().positions.drawer, undefined);
-});
-
-test("keeps in-memory interaction working when storage reads and writes are blocked", () => {
-    const blocked = () => {
-        throw new Error("Storage blocked");
-    };
-    const stores = createNavigationStores({session: blocked});
-    stores.scroll.setState({positions: {desktop: {navigation: "docs", pathname: "/", documents: 100, outline: 200}}});
-    stores.scroll.persist.rehydrate();
-    assert.equal(stores.scroll.getState().positions.desktop?.documents, 100);
-});

package/src/store/navigation/create-navigation-stores.ts

@@ -1,59 +0,0 @@
-import {createJSONStorage, persist, type StateStorage} from "zustand/middleware";
-import {createStore} from "zustand/vanilla";
-import type {NavigationScrollState} from "@/store/navigation/navigation-state";
-import {navigation_scroll_storage_key, navigation_storage_version} from "@/store/navigation/navigation-storage";
-import {toNavigationScrollState} from "@/store/navigation/to-navigation-scroll-state";
-
-/**
- * 브라우저 저장소를 늦게 읽는 경계 · 차단 환경과 테스트의 메모리 저장소 지원
- */
-interface NavigationStorage {
-    /**
-     * 같은 탭 안에서만 복원할 스크롤 위치
-     */
-    session: () => StateStorage;
-}
-
-/**
- * 브라우저 탐색의 vanilla 스토어 생성기 · Hono Hook이 아닌 생성기이므로 use- 접두사를 붙이지 않음
- * 서버 요청은 이 생성기를 실행하지 않으며 저장 실패 시 메모리 상태 유지
- */
-export const createNavigationStores = (options: NavigationStorage) => {
-    /**
-     * 저장소 접근이 막혀도 persist 갱신이 스크롤 동작을 중단하지 않도록 격리
-     */
-    const toSafeStorage = (getStorage: NavigationStorage["session"]): StateStorage => {
-        return {
-            getItem: (key) => {
-                // persist의 읽기 오류 경로로 보내 기존 메모리 상태를 유지 · null은 실제 저장소 초기화에만 사용
-                return getStorage().getItem(key);
-            },
-            setItem: (key, value) => {
-                try {
-                    return getStorage().setItem(key, value);
-                } catch {
-                    /* 저장 실패 시에도 스토어의 메모리 상태는 유지 */
-                }
-            },
-            removeItem: (key) => {
-                try {
-                    return getStorage().removeItem(key);
-                } catch {
-                    /* 저장소 차단이 탐색을 막지 않음 */
-                }
-            },
-        };
-    };
-
-    return {
-        scroll: createStore<NavigationScrollState>()(
-            persist(() => ({positions: {}}), {
-                name: navigation_scroll_storage_key,
-                version: navigation_storage_version,
-                storage: createJSONStorage(() => toSafeStorage(options.session)),
-                merge: (persisted) => toNavigationScrollState(persisted),
-                migrate: () => ({positions: {}}),
-            }),
-        ),
-    };
-};

package/src/store/navigation/navigation-state.ts

@@ -1,36 +0,0 @@
-/**
- * 스크롤 영역의 배치 · 넓은 3열, 좁은 2열, 모바일 모달
- */
-export type NavigationLayout = "wide" | "desktop" | "drawer";
-
-/**
- * 한 화면 배치의 마지막 탐색 위치 · 목록 변경과 다른 페이지의 목차는 재사용하지 않음
- */
-export interface NavigationPosition {
-    /**
-     * 현재 사이트의 공통 문서 URL·제목 목록
-     */
-    navigation: string;
-    /**
-     * 목차가 속한 페이지
-     */
-    pathname: string;
-    /**
-     * 공통 문서 목록의 세로 위치
-     */
-    documents: number;
-    /**
-     * 현재 페이지 목차의 세로 위치
-     */
-    outline: number;
-}
-
-/**
- * 같은 탭 안에서 유지하는 배치별 탐색 위치
- */
-export interface NavigationScrollState {
-    /**
-     * 아직 열지 않은 배치의 위치는 저장하지 않음
-     */
-    positions: Partial<Record<NavigationLayout, NavigationPosition>>;
-}

package/src/store/navigation/navigation-storage.ts

@@ -1,9 +0,0 @@
-/**
- * 저장 형태가 바뀌면 기존 자료를 기본 상태로 돌리는 persist 버전
- */
-export const navigation_storage_version = 1;
-
-/**
- * 같은 탭에서 문서 이동 후 탐색 위치 복원 · 데스크톱과 드로어는 별도 저장
- */
-export const navigation_scroll_storage_key = "for-humanity:navigation-scroll";

package/src/store/navigation/to-navigation-scroll-state.ts

@@ -1,42 +0,0 @@
-import type {NavigationPosition, NavigationScrollState} from "@/store/navigation/navigation-state";
-
-/**
- * 알 수 없는 저장 형태·음수·무한 좌표 제외 · 초기 HTML과 Zustand에 같은 검증 적용
- */
-export const toNavigationScrollState = (value: unknown): NavigationScrollState => {
-    /**
-     * 한 배치의 완전한 좌표만 복원 대상으로 수용
-     */
-    const toPosition = (position: unknown): NavigationPosition | undefined => {
-        if (
-            typeof position !== "object" ||
-            position === null ||
-            !("navigation" in position) ||
-            typeof position.navigation !== "string" ||
-            !("pathname" in position) ||
-            typeof position.pathname !== "string" ||
-            !("documents" in position) ||
-            typeof position.documents !== "number" ||
-            !Number.isFinite(position.documents) ||
-            position.documents < 0 ||
-            !("outline" in position) ||
-            typeof position.outline !== "number" ||
-            !Number.isFinite(position.outline) ||
-            position.outline < 0
-        ) {
-            return;
-        }
-        return {navigation: position.navigation, pathname: position.pathname, documents: position.documents, outline: position.outline};
-    };
-
-    if (typeof value !== "object" || value === null || !("positions" in value) || typeof value.positions !== "object" || value.positions === null) {
-        return {positions: {}};
-    }
-
-    const positions = {
-        wide: toPosition("wide" in value.positions ? value.positions.wide : undefined),
-        desktop: toPosition("desktop" in value.positions ? value.positions.desktop : undefined),
-        drawer: toPosition("drawer" in value.positions ? value.positions.drawer : undefined),
-    };
-    return {positions: Object.fromEntries(Object.entries(positions).filter((entry) => entry[1] !== undefined))};
-};

package/src/style/base.css

@@ -1,28 +0,0 @@
-/*
- * 전역 상자 크기와 스크롤·움직임 기본값
- */
-
-* {
-    box-sizing: border-box;
-}
-
-/* 페이지 바탕과 절 이동 · 초기 hash 보정 중 smooth scroll 일시 중지 */
-:root {
-    background: var(--app-color-ground);
-    scrollbar-gutter: stable;
-    scroll-behavior: smooth;
-}
-
-/* 움직임 줄이기 · 컴포넌트보다 우선하는 전역 !important 예외 */
-@media (prefers-reduced-motion: reduce) {
-    *,
-    *::before,
-    *::after {
-        animation-duration: 0.01ms !important;
-        animation-delay: 0s !important;
-        animation-iteration-count: 1 !important;
-        transition-duration: 0.01ms !important;
-        transition-delay: 0s !important;
-        scroll-behavior: auto !important;
-    }
-}