for-humanity 0.13.0 → 0.14.0

package/dist/{run-site-command-C80YoNOe.js → run-site-command-DPG5RNIN.js}

@@ -1,18 +1,18 @@
 import { d as copy_error_missing_build, n as copy_error_config } from "./copy-C1uzvEnr.js";
 import { t as logger } from "./logger-Dv1i9xSV.js";
-import { n as site_config_absent, t as siteConfigSchema } from "./site-config-bllORGpm.js";
-import { n as font_cache_control, r as asset_font_dir, t as loadSite } from "./load-site-CbpLEhwu.js";
+import { n as site_config_absent, t as siteConfigSchema } from "./site-config-FmStUQ2W.js";
+import { n as font_cache_control, r as asset_font_dir, t as loadSite } from "./load-site-CBJGMNfH.js";
 import { n as config_file_names, t as toErrorMessage } from "./to-error-message-pF6_7wGK.js";
 import { copyFile, mkdir, rm, writeFile } from "node:fs/promises";
 import { z } from "zod";
-import { existsSync } from "node:fs";
-import { dirname, join, relative, resolve } from "node:path";
+import { existsSync, realpathSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { toSSG } from "hono/ssg";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { createJiti } from "jiti";
 //#region src/app/_function/read-site-config.ts
 /**
-* 문서 루트의 설정 조회, TypeScript 실행과 스키마 검증
+* 프로젝트 루트의 설정 조회, TypeScript 실행과 스키마 검증
 *
 *   - 중복 파일 거부, 실제 적용되는 설정의 모호성 방지
 *   - Node의 기본 TypeScript 지원 여부와 무관하게 같은 설정 실행
@@ -31,6 +31,29 @@ var readSiteConfig = async (root) => {
 	return parsed.data.default;
 };
 //#endregion
+//#region src/app/_function/read-project.ts
+/**
+* 프로젝트 설정과 문서 루트 해소, 외부·시스템 폴더 symlink 거부
+*/
+var readProject = async (directory) => {
+	const projectRoot = realpathSync(resolve(directory));
+	const site = await readSiteConfig(projectRoot);
+	const root = resolve(projectRoot, site.content.root);
+	if (existsSync(root)) {
+		const location = relative(projectRoot, realpathSync(root));
+		if (location === ".." || location.startsWith(`..${sep}`) || isAbsolute(location)) throw new Error(`content 루트는 프로젝트 내부여야 합니다: ${root}`);
+		if (location.split(sep).some((part) => [
+			"dist",
+			".git",
+			"node_modules"
+		].includes(part.toLowerCase()))) throw new Error(`content 루트는 dist, .git, node_modules 내부일 수 없습니다: ${root}`);
+	}
+	return {
+		root,
+		site
+	};
+};
+//#endregion
 //#region src/entry/preview/to-preview-config.ts
 /**
 * 빌드된 사이트 전용 Vite 설정. 소비 프로젝트의 설정과 환경 파일 자동 로드 제외
@@ -75,31 +98,31 @@ var toPreviewConfig = (params) => {
 */
 var runSiteCommand = async (params) => {
 	try {
-		if (params.args._.length > 1) throw new Error("문서 폴더는 하나만 지정하세요");
+		if (params.args._.length > 1) throw new Error("프로젝트 폴더는 하나만 지정하세요");
 		const kitRoot = fileURLToPath(new URL("../", import.meta.url));
-		const docsRoot = resolve(params.args.dir);
-		const outDir = join(docsRoot, "dist");
-		const siteConfig = await readSiteConfig(docsRoot);
+		const project = await readProject(params.args.dir);
+		const outDir = join(project.root, "dist");
 		if (params.command === "preview") {
 			(await (await import("vite")).preview(toPreviewConfig({
-				root: docsRoot,
-				port: siteConfig.port
+				root: project.root,
+				port: project.site.port
 			}))).printUrls();
 			return;
 		}
 		if (params.command === "dev") {
-			await (await import("./start-dev-server-C4_Lu1nZ.js")).startDevServer({
-				root: docsRoot,
+			await (await import("./start-dev-server-x7Ja5uwv.js")).startDevServer({
+				root: project.root,
 				kitRoot,
-				site: siteConfig,
-				source: false
+				site: project.site,
+				source: false,
+				includePrivate: true
 			});
 			return;
 		}
 		const snapshot = await loadSite({
-			root: docsRoot,
+			root: project.root,
 			kitRoot,
-			site: siteConfig
+			site: project.site
 		});
 		await rm(outDir, {
 			recursive: true,

package/dist/{site-config-bllORGpm.js → site-config-FmStUQ2W.js}

@@ -18,6 +18,14 @@ var site_port_default = 4321;
 * 포트 번호 상한. TCP
 */
 var site_port_max = 65535;
+/**
+* 기본 문서 루트와 공개 범위 폴더
+*/
+var content_default = {
+	root: "content",
+	public: "public",
+	private: "private"
+};
 //#endregion
 //#region src/constant/status.ts
 /**
@@ -39,11 +47,47 @@ var status_default_phrases = [{
 	kind: status_kind.unverified
 }];
 //#endregion
+//#region src/type/content-config.ts
+/**
+* 프로젝트 내부의 상대 경로, 출력 폴더와 시스템 폴더 제외
+*/
+var contentPathSchema = z.string().trim().min(1).refine((value) => !/^[\\/]|[:?#%*\p{Cc}]/u.test(value) && !value.split(/[\\/]/).some((part) => [
+	"..",
+	"dist",
+	"node_modules",
+	".git"
+].includes(part.toLowerCase())), "프로젝트 내부 상대 경로만 사용하세요. dist, node_modules, .git 경로는 사용할 수 없습니다").transform((value) => value.replaceAll("\\", "/").split("/").filter((part) => part !== "" && part !== ".").join("/"));
+/**
+* 공개와 내부 문서 폴더의 상대 경로 계약
+*/
+var contentConfigSchema = z.object({
+	/**
+	* 프로젝트 루트 기준 문서 폴더, 점 하나는 프로젝트 루트
+	*/
+	root: contentPathSchema.transform((value) => value === "" ? "." : value).default(content_default.root),
+	/**
+	* 문서 루트 아래 공개 문서 폴더
+	*/
+	public: contentPathSchema.refine((value) => value !== "", "공개 문서는 별도 하위 폴더가 필요합니다").default(content_default.public),
+	/**
+	* 문서 루트 아래 로컬 전용 문서 폴더
+	*/
+	private: contentPathSchema.refine((value) => value !== "", "내부 문서는 별도 하위 폴더가 필요합니다").default(content_default.private)
+}).refine((value) => {
+	const published = value.public.toLowerCase();
+	const internal = value.private.toLowerCase();
+	return published !== internal && !published.startsWith(`${internal}/`) && !internal.startsWith(`${published}/`);
+}, "공개 문서와 내부 문서 폴더는 같거나 중첩될 수 없습니다");
+//#endregion
 //#region src/type/site-config.ts
 /**
 * 사이트 설정의 입력 검증과 기본값 적용
 */
 var siteConfigSchema = z.object({
+	/**
+	* 프로젝트 기준 문서 루트와 공개 범위
+	*/
+	content: contentConfigSchema.default(content_default),
 	/**
 	* 사이드바 이름과 탭 제목
 	*/

package/dist/site.js

@@ -1 +1 @@
-export { t as loadSite } from "./load-site-CbpLEhwu.js";
+export { t as loadSite } from "./load-site-CBJGMNfH.js";

package/dist/{start-dev-server-C4_Lu1nZ.js → start-dev-server-x7Ja5uwv.js}

@@ -96,7 +96,9 @@ var toDevConfig = (params) => {
 						currentSite = nextSite;
 						if (generation > 0) server.hot.send({ type: "full-reload" });
 					},
-					onError: (error) => server.config.logger.error(`${copy_error_prefix}: ${toErrorMessage(error)}`)
+					onError: (error) => {
+						return server.config.logger.error(`${copy_error_prefix}: ${toErrorMessage(error)}`);
+					}
 				});
 				const reload = debounce(refresh, 150);
 				/**
@@ -126,7 +128,9 @@ var toDevConfig = (params) => {
 				};
 				prepare = refresh;
 			},
-			closeBundle: () => dispose?.()
+			closeBundle: () => {
+				return dispose?.();
+			}
 		}, devServer({
 			exclude: params.source ? [
 				...viteClientPaths,
@@ -137,13 +141,17 @@ var toDevConfig = (params) => {
 				/^\/src\/entry\/browser\//
 			] : viteClientPaths,
 			ignoreWatching: dev_ignored_paths,
-			handleHotUpdate: (context) => context.file.endsWith(".css") ? void 0 : [],
+			handleHotUpdate: (context) => {
+				return context.file.endsWith(".css") ? void 0 : [];
+			},
 			loadModule: async () => {
 				ready ??= prepare?.();
 				await ready;
 				if (currentSite === void 0) throw new Error("문서 준비에 실패했습니다. 위 오류를 수정하면 다시 반영합니다.");
 				const app = currentSite.app;
-				return { fetch: async (request, env) => app.fetch(request, env) };
+				return { fetch: async (request, env) => {
+					return app.fetch(request, env);
+				} };
 			}
 		})]
 	};

package/dist/type/content-config.d.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+/**
+ * 공개와 내부 문서 폴더의 상대 경로 계약
+ */
+export declare const contentConfigSchema: z.ZodObject<{
+    root: z.ZodDefault<z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodTransform<string, string>>>;
+    public: z.ZodDefault<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+    private: z.ZodDefault<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+}, z.core.$strip>;

package/dist/type/site-config.d.ts

@@ -3,6 +3,11 @@ import { z } from "zod";
  * 사이트 설정의 입력 검증과 기본값 적용
  */
 export declare const siteConfigSchema: z.ZodObject<{
+    content: z.ZodDefault<z.ZodObject<{
+        root: z.ZodDefault<z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>, z.ZodTransform<string, string>>>;
+        public: z.ZodDefault<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+        private: z.ZodDefault<z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>>;
+    }, z.core.$strip>>;
     title: z.ZodDefault<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
     url: z.ZodOptional<z.ZodPipe<z.ZodPipe<z.ZodURL, z.ZodTransform<URL, string>>, z.ZodTransform<string, URL>>>;
@@ -26,6 +31,10 @@ export type ResolvedSiteConfig = z.infer<typeof siteConfigSchema>;
  * 작성자가 지정하는 사이트 설정, 기본값 적용 전 입력
  */
 export interface SiteConfig {
+    /**
+     * 기본 content/public, content/private 구조의 경로 변경
+     */
+    content?: z.input<typeof siteConfigSchema>["content"];
     /**
      * 사이드바 이름과 탭 제목, 생략 시 for humanity
      */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "for-humanity",
-    "version": "0.13.0",
+    "version": "0.14.0",
     "description": "Documents written for humans to read: a docs kit with a sidebar, parts, sections and Mermaid diagrams, built on Hono JSX",
     "keywords": [
         "docs",
@@ -27,6 +27,7 @@
     "files": [
         "dist",
         "src/asset",
+        "template",
         "CHANGELOG.md"
     ],
     "engines": {
@@ -37,9 +38,9 @@
         "sync:readme": "tsx util/sync-readme.ts",
         "sync:docs": "pnpm sync:readme && tsx util/sync-changelog.ts",
         "dev": "pnpm sync:docs && pnpm build:kit && tsx src/entry/dev/dev.ts",
-        "build": "pnpm sync:docs && pnpm build:kit && node dist/cli.js build templates/document",
+        "build": "pnpm sync:docs && pnpm build:kit && node dist/cli.js build .",
         "build:pages": "pnpm build && tsx util/prepare-pages.ts",
-        "preview": "node dist/cli.js preview templates/document",
+        "preview": "node dist/cli.js preview .",
         "test": "pnpm build:kit && vitest run",
         "test:watch": "pnpm build:kit && vitest",
         "test:browser": "pnpm build:kit && playwright test",

package/template/content/README.md

@@ -0,0 +1,5 @@
+# Project notes
+
+이 프로젝트의 소개와 문서 안내.
+
+[시작하기](public/getting-started.md)

package/template/content/public/getting-started.md

@@ -0,0 +1,26 @@
+---
+name: Getting started
+label: 문서 작성과 공개 범위
+group: Guide
+order: 10
+---
+
+# Getting started
+
+`content/public`은 공개 문서, `content/private`는 로컬 전용 문서입니다.
+공용 이미지와 첨부는 `content/asset`, 내부 자료는 `content/private/asset`에 보관합니다.
+
+프로젝트 루트에서 실행합니다.
+
+```sh
+pnpm exec for-humanity dev
+pnpm exec for-humanity build
+pnpm exec for-humanity preview
+```
+
+`dev`는 전체 문서, `build`와 `preview`는 공개 결과를 제공합니다.
+배포할 폴더는 `content/dist`입니다. `content` 전체를 업로드하지 않습니다.
+`private`는 사이트 배포 제외이며 Git 저장소 접근 제어가 아닙니다.
+
+설정은 프로젝트 루트의 `for-humanity.config.ts`, 홈은 `content/README.md`입니다.
+공개 문서의 URL에는 `public`이 붙지 않습니다. 이 문서는 `/getting-started/`에서 확인할 수 있습니다.

package/template/for-humanity.config.ts

@@ -0,0 +1,8 @@
+import type {SiteConfig} from "for-humanity";
+
+export default {
+    title: "Project notes",
+
+    // 프로젝트 기준 문서 루트, 문서 루트 기준 공개와 내부 폴더
+    content: {root: "content", public: "public", private: "private"},
+} satisfies SiteConfig;