@unana_dev/doxen 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Safience Una
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,197 @@
1
- # Temporary Holding Version
1
+ # Doxen
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ > 기존 저장소의 Markdown 폴더를 설정 파일 하나로 연결하는 npm 패키지입니다. Node.js 22 이상이 필요합니다. 현재 0.2.0 구현 기준입니다.
4
+
5
+ 상단 탭, 폴더별 문서 탐색, 목차, 한국어 전체 검색, 검색 위치 이동, 문서 및 지정 섹션 안에서 찾기 기능을 제공합니다. React/Vue 등 사용자 프로젝트의 프레임워크에 의존하지 않으며, 사이트 소스는 패키지 안에 있습니다.
6
+
7
+ ## 설치와 시작
8
+
9
+ npm 레지스트리에 배포된 패키지는 다음과 같이 설치합니다. 로컬 설치는 `npm pack`으로 만든 tgz 경로를 패키지명 대신 사용합니다.
10
+
11
+ ```bash
12
+ npm install -D @unana_dev/doxen
13
+ npx docs init
14
+ npm run docs:dev
15
+ npm run docs:build
16
+ ```
17
+
18
+ Yarn도 같은 패키지를 사용할 수 있습니다.
19
+
20
+ ```bash
21
+ yarn add -D @unana_dev/doxen
22
+ yarn doxen init
23
+ yarn docs:dev
24
+ yarn docs:build
25
+ ```
26
+
27
+ `docs`라는 실행 파일이 다른 의존성과 겹치면 동일한 CLI인 `doxen`을 사용하세요. 생성되는 스크립트는 충돌을 줄이기 위해 `doxen`을 사용합니다.
28
+
29
+ `init`은 기존 설정, 문서, 프로젝트 스크립트를 덮어쓰지 않습니다. 설정이 없으면 `docs/README.md`, `docs.config.ts`를 만들고 `docs:dev`, `docs:build`, `docs:deploy` 스크립트를 추가합니다. `.gitignore`에는 생성물과 `node_modules`를 등록합니다. 이미 문서 폴더가 있다면 설정 파일의 경로만 연결하고 생성된 시작 문서는 필요에 따라 제거하세요.
30
+
31
+ ## 설정
32
+
33
+ ```ts
34
+ // docs.config.ts
35
+ export default {
36
+ title: '팀 문서',
37
+ icon: { background: '#edf8ff', color: '#467792', border: '#bcdff8' },
38
+ tabs: [
39
+ { title: '시작하기', dir: './guide', slug: 'guide' },
40
+ { title: '작성 가이드', dir: './writing', slug: 'writing' },
41
+ { title: '레퍼런스', dir: './reference', slug: 'reference' },
42
+ ],
43
+ };
44
+ ```
45
+
46
+ 선택적으로 `import { defineConfig } from '@unana_dev/doxen'`을 사용하면 타입 도움을 받을 수 있습니다. `.ts`, `.mjs`, `.js` 설정을 지원합니다. 설정 파일은 Node에서 실행되므로 신뢰할 수 있는 저장소에서 사용하세요.
47
+
48
+ - `dir`: 설정 파일 기준의 전용 하위 폴더. 저장소 루트 또는 외부 폴더는 허용하지 않습니다.
49
+ - `slug`: 고유한 영문 소문자·숫자·하이픈. 문서 URL의 일부입니다.
50
+ - `icon.background` / `icon.color`: 상단 로고와 파비콘의 배경색 / 글자색. `#fff` 또는 `#ffffff` 형식의 HEX 색상을 지원하며, 생략하면 각각 `#edf8ff` / `#467792`가 적용됩니다.
51
+ - `icon.border`: 상단 로고의 테두리 색상. 같은 HEX 형식을 지원하며, 기본값은 `#bcdff8`입니다.
52
+ - `icon: '#eab308'`처럼 색상 하나만 지정하면 같은 색 계열의 밝은 배경색, 중간 톤 테두리, 진한 글자색을 자동 생성합니다. 개별 색상 객체 대신 사용할 수 있습니다.
53
+ - 파일 이름순(숫자 순서 인식)으로 정렬합니다. `01-introduction.md`처럼 번호를 붙이면 순서를 제어할 수 있습니다.
54
+ - 하위 폴더는 탐색 목록에 경로로 표시합니다. 숨김 파일, `node_modules`, 심볼릭 링크 문서는 제외합니다.
55
+ - 탭 전체 내용은 같은 정적 사이트에 포함됩니다. 탭별 권한 분리는 제공하지 않습니다.
56
+
57
+ ## 명령
58
+
59
+ | 명령 | 기능 |
60
+ | --- | --- |
61
+ | `docs init` | 시작 문서, 설정, 스크립트, Git 제외 설정 |
62
+ | `docs dev` | `http://127.0.0.1:4173` 미리보기와 변경 시 자동 새로고침 |
63
+ | `docs dev --port 4200` | 포트 변경 |
64
+ | `docs build` | 설정 파일 옆 `.docs-dist/`에 정적 사이트 생성 |
65
+ | `docs deploy` | 인증 설정 검사 → 빌드 → Cloudflare Pages 운영 배포 |
66
+ | `docs build --config ./config/docs.config.ts` | 설정 파일 지정 (dev, deploy, ai에도 적용) |
67
+ | `docs ai --file docs/guide.md --instruction "변경 요청"` | 표준 문서 양식과 AI 편집 작업 지침을 stdout에 출력 |
68
+
69
+ 빌드는 자체 생성 표시가 있는 출력 폴더만 교체합니다. 문서 변환에 실패하면 이전 성공 결과를 유지합니다. 출력에는 문서 HTML과 검색용 본문이 포함되므로 소스가 비공개라면 결과물도 비공개로 배포해야 합니다.
70
+
71
+ ## 검색과 문서 작성
72
+
73
+ `⌘/Ctrl K` 또는 상단 검색 버튼으로 모든 탭의 제목·본문·표·코드를 검색합니다. 공백으로 나눈 단어를 모두 포함하는 섹션을 찾으며 제목에 일치하는 결과를 먼저 표시합니다. 한국어 Unicode 정규화와 영문 대소문자 구분 없는 부분 일치를 지원합니다. 형태소 분석·오타 교정 검색은 포함하지 않습니다.
74
+
75
+ 결과를 선택하면 해당 문서와 제목 위치로 이동하며 일치하는 글자를 표시합니다. 문서 상단 검색창 또는 다음과 같은 섹션 검색창에서 이전·다음 버튼, Enter / Shift+Enter로 이동합니다. 검색은 현재 선택한 한 영역에 적용됩니다. 섹션 및 문서 내 검색은 입력한 문자열이 포함된 표의 본문 행만 남기고 나머지 행을 숨깁니다. 표 머리글은 유지하며 검색어를 지우면 모든 행을 복원합니다. 영문 대소문자와 한국어 Unicode 정규화를 적용하고 앞뒤 공백을 제외한 연속 문자열로 비교합니다. 표 밖의 본문은 숨기지 않고 일치 위치를 강조합니다.
76
+
77
+ ```markdown
78
+ ## 1. 문서 작성
79
+
80
+ :::search 작성 방법 검색
81
+
82
+ | 작업 | 방법 |
83
+ | --- | --- |
84
+ | 제목 추가 | Markdown 제목 문법 사용 |
85
+ :::
86
+ ```
87
+
88
+ 번호가 있는 제목은 검색 영역 밖에 두세요. 제목 바로 아래에 `:::search 영역 이름`을 작성하면 해당 영역에만 검색창이 표시됩니다. 검색이 필요 없는 섹션은 일반 Markdown으로 작성합니다. 기존처럼 검색 영역 안에 첫 제목을 작성한 문서도 화면에서는 제목 아래로 검색창을 배치합니다. 전체 검색은 헤더 중앙, 문서 전체에서 찾기는 본문 상단의 접이식 메뉴로 제공합니다.
89
+
90
+ 표준 Markdown, 코드 블록, 표, 상대 `.md` 링크, 한국어 제목 앵커, 이미지와 PDF 첨부를 지원합니다. 연결된 PNG/JPEG/GIF/WebP/AVIF/ICO/PDF만 복사하며 문서 폴더 밖 첨부는 빌드 오류로 처리합니다. 로컬 파일 링크는 현재 문서 기준 상대 경로를 사용하세요. 한 문서의 여러 검색 영역을 나란히 구성할 수 있으며 중첩 검색 영역은 사용하지 마세요.
91
+
92
+ 제목은 자동으로 목차에 표시됩니다. 중복 제목에는 `-1`, `-2`가 붙습니다. Markdown 링크가 존재하지 않는 문서 파일을 가리키면 빌드를 중단합니다. 대상 제목 앵커의 존재 여부는 별도로 검사하지 않습니다.
93
+
94
+ 실행 가능한 HTML, MDX, YAML frontmatter 메타데이터, 확장 Markdown 플러그인은 현재 지원하지 않습니다. 원시 HTML은 실행하지 않고 텍스트로 표시하며 결과 HTML을 정제합니다. 외부 이미지·링크는 원래 URL을 유지합니다.
95
+
96
+ ## AI로 정해진 양식에 맞추기
97
+
98
+ ```bash
99
+ npx docs ai --file guide/writing.md --instruction "현재 내용을 유지하고 문서 작성 방법을 표로 정리" > /tmp/writing-prompt.txt
100
+ ```
101
+
102
+ 생성된 내용을 사용 중인 AI 코딩 도구에 전달하세요. 문서 정보 범위 → 번호별 단계 → 예외 → 관련 문서 순서의 양식과 기존 문서, 요청을 함께 제공합니다. 결과를 검토하여 Markdown에 반영한 다음 미리보기와 Git diff를 확인합니다.
103
+
104
+ 이 명령은 API를 호출하거나 파일을 자동 수정하지 않습니다. AI 제공자·모델·인증 설정이 정해지지 않아 현재 버전은 도구에 전달할 작업 지침 생성까지 제공합니다. 출력에 기존 문서 전문이 포함되므로 공유 범위는 원본 문서와 동일하게 취급하세요.
105
+
106
+ ## 명령 하나로 비공개 배포하기
107
+
108
+ 문서 프로젝트에서 다음 명령을 실행하세요. 최초에는 한국어 설정 안내가 나오고, 이후에는 같은 명령으로 수정한 문서를 다시 배포합니다. Node.js 22 이상이 필요하며 Wrangler는 Doxen에 포함되어 별도로 설치하지 않습니다.
109
+
110
+ ```bash
111
+ npx doxen deploy
112
+ # 또는 npm run docs:deploy / yarn docs:deploy
113
+ ```
114
+
115
+ 문서 설정이 아직 없다면 먼저 `npx doxen init`으로 문서 폴더를 준비하세요. 기존 프로젝트도 `init`을 다시 실행하면 배포 스크립트가 추가됩니다. `--config ./config/docs.config.ts`로 다른 문서 설정을 지정할 수 있습니다.
116
+
117
+ ### 첫 실행에서 하는 일
118
+
119
+ 1. **Cloudflare 연결:** 안내되는 [토큰 발급 화면](https://dash.cloudflare.com/profile/api-tokens)에서 로그인하고 배포용 API 토큰을 한 번 발급합니다. 터미널의 가려진 입력란에 붙여넣습니다. 환경 변수를 직접 설정할 필요는 없습니다.
120
+ 2. **계정 선택:** 접근 가능한 계정을 조회합니다. 여러 개면 사용할 계정을 선택합니다.
121
+ 3. **사이트 이름과 열람자 입력:** 새 사이트 이름과 열람할 업무 이메일을 입력합니다. 본인 이메일도 포함하세요. 기존 회사 로그인 방법이 있으면 선택하고, 없으면 이메일 일회용 코드 로그인을 준비합니다.
122
+ 4. **내용 확인:** 계정·사이트·열람자·업로드할 문서 폴더를 확인하고 진행합니다.
123
+ 5. **자동 준비와 배포:** Pages 프로젝트, 운영·미리보기 Access 애플리케이션, 허용 이메일 정책, Fail closed 설정을 준비하고 검증합니다. AUD와 팀 주소도 자동으로 가져옵니다. 이후 문서를 빌드하고 업로드합니다.
124
+
125
+ Cloudflare 계정 생성, 토큰 발급 및 계정에서 요구하는 Zero Trust 최초 약관·플랜 선택은 사용자가 진행해야 합니다. 도구는 유료 플랜을 구매하지 않습니다. 토큰에는 사용할 **계정 하나**를 지정하고 다음 권한을 부여하세요. 일반 Wrangler 브라우저 로그인만으로 이 Access 자동 설정을 대신하지 않습니다.
126
+
127
+ | Account 권한 | 수준 | 용도 |
128
+ | --- | --- | --- |
129
+ | Account Settings | Read | 계정 조회 |
130
+ | Cloudflare Pages | Edit | 프로젝트 생성·배포 |
131
+ | Access: Apps and Policies | Edit | 접근 애플리케이션·허용 정책 생성·조회 |
132
+ | Access: Organizations, Identity Providers, and Groups | Edit | 팀 주소 확인·생성 및 로그인 방법 준비 |
133
+
134
+ 기존 회사 로그인 설정은 변경하지 않고 선택한 방법을 사용합니다. 로그인 방법이 없는 계정에는 확인 화면에 안내한 대로 이메일 일회용 코드 제공자를 추가합니다. 기존 Pages 프로젝트와 이름이 충돌하면 다른 이름을 선택해야 하며, 기존 사이트를 자동으로 인수하거나 덮어쓰지 않습니다.
135
+
136
+ ### 다음 배포와 저장 위치
137
+
138
+ Markdown 수정 후 **같은 `npx doxen deploy` 명령**을 실행하세요. 설정이 완료되어 있으면 사이트 이름·이메일을 다시 묻지 않습니다. 기존 정책과 Fail closed 설정을 확인한 다음 운영 브랜치에 배포합니다. Git push는 필요하지 않습니다.
139
+
140
+ - 프로젝트 설정은 문서 설정 파일 옆 `.doxen-deploy.json`에 저장합니다. 계정 ID, 사이트, 허용 이메일과 생성된 Access 식별자가 들어가며 API 토큰은 들어가지 않습니다. 기존 `docs.config.ts`를 수정하지 않습니다. 팀 저장소에 공유할 때는 이메일 목록의 공개 범위를 확인하세요.
141
+ - macOS/Linux에서는 토큰을 이 컴퓨터에 저장할지 선택할 수 있습니다. 저장하면 `~/.config/doxen/accounts/<계정 ID>.json`에 **평문으로 저장**하며 디렉터리는 700, 파일은 600 권한을 사용합니다. OS 키체인 저장은 아닙니다. 저장하지 않으면 다음 실행에서 다시 입력합니다. Windows에서는 자동 저장을 제공하지 않습니다.
142
+ - 저장된 토큰이 만료되거나 계정 권한이 거부되면 새 토큰 입력을 안내합니다. 토큰을 제거하려면 해당 계정 파일을 삭제하고, 효력을 없애려면 Cloudflare에서 토큰을 폐기하세요.
143
+ - CI에서는 저장된 프로젝트 설정과 비밀 환경 변수 `CLOUDFLARE_API_TOKEN`을 사용합니다. `CLOUDFLARE_ACCOUNT_ID`를 함께 지정할 경우 저장된 계정과 같아야 합니다. 대화형 최초 설정은 CI에서 실행하지 않습니다.
144
+
145
+ 중간에 실패하면 생성된 자원의 식별자를 보존합니다. 같은 명령을 다시 실행하면 기록된 단계에서 이어갑니다. 설정이 미완료된 동안에는 일반 `docs build`도 차단합니다. 서버가 자원을 만들었지만 응답·로컬 기록에 실패한 경우에는 중복 생성이나 기존 사이트 덮어쓰기를 막기 위해 대시보드 확인이 필요할 수 있습니다. 자동으로 원격 자원을 삭제하지 않습니다.
146
+
147
+ ### 열람 권한과 운영 관리
148
+
149
+ 배포 이력·롤백·도메인은 Cloudflare Pages, 로그인·접근 정책은 Cloudflare One의 Access에서 관리합니다. 자동 설정은 기본 Pages 운영 주소와 미리보기 주소를 대상으로 합니다. 커스텀 도메인은 별도로 연결하고 Access로 보호해야 합니다.
150
+
151
+ 새 열람자는 **운영·미리보기 Access 정책과 `.doxen-deploy.json`의 `emails`에 모두 추가**한 뒤 재배포합니다. 도구는 재배포 때 정책을 임의로 덮어쓰지 않고 목록의 일치를 검사합니다. 퇴사자 등의 접근을 회수할 때는 모든 관련 Access 정책에서 제거하고 활성 세션을 취소한 다음 저장된 목록도 수정해 재배포하세요. 이전 배포에는 당시 목록이 남으므로 필요하면 이전 배포도 삭제합니다. 롤백하면 이전 목록도 돌아올 수 있습니다.
152
+
153
+ 허용 사용자는 사이트 전체를 읽습니다. 문서별·탭별 권한은 제공하지 않습니다. 자동 설정은 초기 연결 과정을 줄이는 기능이며, 별도의 열람자 관리 화면은 아직 없습니다.
154
+
155
+ ### 보호 방식과 기존 수동 설정
156
+
157
+ 배포 설정이 있으면 `docs build`에도 Pages 서버 인증 코드(`_worker.js`)와 전체 경로 라우팅(`_routes.json`)이 포함됩니다. 서버는 Cloudflare Access JWT의 서명·발급자·AUD·만료와 허용 이메일을 확인한 뒤 파일을 제공합니다. HTML, `/site.json`, 이미지, PDF 모두 보호하며 인증 실패·공개키 조회 실패는 403으로 차단합니다. 응답은 `private, no-store`로 설정합니다. Cache Rules로 이를 덮어쓰지 마세요.
158
+
159
+ 로그인은 Cloudflare Access가 담당합니다. Access가 연결되지 않은 주소는 로그인 화면 대신 403을 반환합니다. 배포 후 허용·미허용 계정으로 운영·미리보기 주소의 문서와 첨부파일 접근을 확인하세요. 실제 계정의 로그인과 정책 전파는 로컬 자동 테스트로 검증할 수 없습니다.
160
+
161
+ 로컬 `docs dev`에는 인증이 적용되지 않습니다. 배포 설정 없는 `docs build`는 일반 정적 사이트를 만듭니다. 보호된 빌드도 일반 정적 호스팅에서는 인증 코드가 실행되지 않으므로 Pages Functions로 배포해야 합니다.
162
+
163
+ 기존 `docs.config.ts`의 `deploy` 설정과 환경 변수 방식도 지원합니다. 자동 설정 파일과 수동 `deploy` 설정을 동시에 두지는 마세요. 수동 설정은 기존처럼 호스트별 Access 정책과 Fail closed를 관리자가 준비해야 합니다.
164
+
165
+ ```ts
166
+ deploy: {
167
+ project: 'team-docs',
168
+ access: {
169
+ teamDomain: 'https://your-team.cloudflareaccess.com',
170
+ audiences: ['0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef'],
171
+ emails: ['member@company.com'],
172
+ },
173
+ },
174
+ ```
175
+
176
+ 공식 참고: [Pages 프로젝트 생성 API](https://developers.cloudflare.com/api/resources/pages/subresources/projects/methods/create/), [Access 애플리케이션 API](https://developers.cloudflare.com/api/resources/zero_trust/subresources/access/subresources/applications/methods/create/), [Zero Trust 조직 API](https://developers.cloudflare.com/api/resources/zero_trust/subresources/organizations/methods/create/), [JWT 검증](https://developers.cloudflare.com/cloudflare-one/access-controls/applications/http-apps/authorization-cookie/validating-json/), [Fail closed](https://developers.cloudflare.com/pages/functions/routing/).
177
+
178
+ ## 패키지 개발·검증·게시
179
+
180
+ ```bash
181
+ npm ci
182
+ npm run dev # 예제 사이트
183
+ npm run check # Node 테스트와 문법 검사
184
+ npm run test:browser # Chromium 브라우저 테스트
185
+ npm run test:package # tgz를 별도 프로젝트에 설치하여 검증
186
+ npm run build # 예제 정적 빌드
187
+ npm pack --dry-run # 배포 파일 목록 검토
188
+ npm pack
189
+ ```
190
+
191
+ 브라우저 테스트는 먼저 `npx playwright install chromium`을 실행하세요. 기존 Chrome을 쓰려면 `PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH`에 실행 파일 경로를 설정할 수 있습니다. npm에 게시하려면 스코프 소유권·이름 사용 가능 여부·로그인을 확인한 뒤 버전을 갱신하고 `npm publish --access public`을 실행합니다. 게시 여부는 이 저장소 구현 완료와 별개입니다.
192
+
193
+ 배포 파일은 package.json의 `files` 허용 목록으로 제한됩니다. `bin/`, `src/`, `client/`, README, LICENSE만 포함하고 예제, 테스트, 문서 저장소 원본은 포함하지 않습니다. 런타임 의존성은 일반 npm 의존성으로 설치합니다.
194
+
195
+ 구조: `bin/docs.js` → 설정 로더 → Markdown/섹션/첨부 처리 → 정적 빌드 또는 로컬 서버. 화면과 브라우저 검색은 `client/`에 있습니다. 사이트는 해시 URL을 사용해 하위 경로에서도 서버 rewrite 없이 동작합니다. 전체 문서 데이터를 한 번 내려받으므로 초기 버전은 소규모·중규모 팀 문서에 맞췄으며 대형 저장소 성능은 별도 측정이 필요합니다.
196
+
197
+ 파일 감시 한도 오류(EMFILE/ENOSPC)나 네트워크 파일시스템에서 갱신이 안 되면 `CHOKIDAR_USEPOLLING=1 npm run docs:dev`를 사용하세요. 설정·문서 오류는 터미널과 미리보기 응답에 표시되며 수정 후 새로고침하면 복구됩니다.
package/bin/docs.js ADDED
@@ -0,0 +1,64 @@
1
+ #!/usr/bin/env node
2
+ import { parseArgs } from "node:util";
3
+ import { loadConfig } from "../src/config.js";
4
+ import { init } from "../src/init.js";
5
+ import { build } from "../src/build.js";
6
+ import { dev } from "../src/dev.js";
7
+ import { prepareAi } from "../src/ai.js";
8
+
9
+ try {
10
+ const { values, positionals } = parseArgs({
11
+ allowPositionals: true,
12
+ options: {
13
+ config: { type: "string" },
14
+ port: { type: "string", default: "4173" },
15
+ file: { type: "string" },
16
+ instruction: { type: "string" },
17
+ help: { type: "boolean", short: "h" },
18
+ version: { type: "boolean", short: "v" },
19
+ },
20
+ });
21
+ const [command, ...extra] = positionals;
22
+ if (values.version) console.log("0.2.0");
23
+ else if (values.help || !command)
24
+ console.log(
25
+ `Doxen — 저장소 기반 문서 사이트\n\n docs init 설정과 스크립트 생성\n docs dev [--port 4173] 로컬 미리보기 및 자동 갱신\n docs build .docs-dist 정적 사이트 생성\n docs deploy 최초 설정 안내 및 비공개 Cloudflare Pages 배포\n docs ai --file <문서.md> --instruction "변경 요청"\n 표준 양식과 AI 작업 지침을 stdout으로 출력\n\n옵션: --config <파일> (dev/build/deploy/ai), --help, --version\n동일 명령: doxen <명령>`,
26
+ );
27
+ else {
28
+ if (extra.length) throw new Error(`알 수 없는 인자: ${extra.join(" ")}`);
29
+ if (command === "init") {
30
+ if (values.config)
31
+ throw new Error("init은 --config 옵션을 지원하지 않습니다.");
32
+ await init(process.cwd());
33
+ } else if (command === "build")
34
+ console.log(
35
+ `빌드 완료: ${await build(await loadConfig(process.cwd(), values.config))}`,
36
+ );
37
+ else if (command === "deploy") {
38
+ const { deploy } = await import("../src/deploy.js");
39
+ await deploy(await loadConfig(process.cwd(), values.config));
40
+ }
41
+ else if (command === "ai")
42
+ console.log(
43
+ await prepareAi(
44
+ await loadConfig(process.cwd(), values.config),
45
+ values.file,
46
+ values.instruction,
47
+ ),
48
+ );
49
+ else if (command === "dev") {
50
+ const port = Number(values.port);
51
+ if (!Number.isInteger(port) || port < 1 || port > 65535)
52
+ throw new Error("port는 1~65535 정수여야 합니다.");
53
+ const running = await dev(process.cwd(), values.config, port);
54
+ for (const signal of ["SIGINT", "SIGTERM"])
55
+ process.once(signal, async () => {
56
+ await running.close();
57
+ process.exit(0);
58
+ });
59
+ } else throw new Error(`알 수 없는 명령: ${command}`);
60
+ }
61
+ } catch (error) {
62
+ console.error(`Doxen: ${error.name === "ExitPromptError" ? "배포 안내를 취소했습니다. 같은 명령으로 다시 시작할 수 있습니다." : error.message}`);
63
+ process.exitCode = 1;
64
+ }
package/client/app.js ADDED
@@ -0,0 +1,349 @@
1
+ import { searchDocuments, matchRanges, matchesRow } from "./search.js";
2
+
3
+ const $ = (selector) => document.querySelector(selector);
4
+ const el = (tag, text, className) => {
5
+ const node = document.createElement(tag);
6
+ if (text !== undefined) node.textContent = text;
7
+ if (className) node.className = className;
8
+ return node;
9
+ };
10
+ const route = (id, anchor = "") =>
11
+ `#/${encodeURIComponent(id)}${anchor ? `/${encodeURIComponent(anchor)}` : ""}`;
12
+ let site;
13
+ let current;
14
+ let activeTab;
15
+ let pendingQuery = "";
16
+ const dialog = $("#search-dialog");
17
+
18
+ function clearMarks(root) {
19
+ for (const mark of root.querySelectorAll("mark[data-hit]"))
20
+ mark.replaceWith(document.createTextNode(mark.textContent));
21
+ root.normalize();
22
+ }
23
+
24
+ function highlight(root, query) {
25
+ clearMarks(root);
26
+ const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT, {
27
+ acceptNode(node) {
28
+ return node.parentElement.closest(".section-tools, script, style, [hidden]")
29
+ ? NodeFilter.FILTER_REJECT
30
+ : NodeFilter.FILTER_ACCEPT;
31
+ },
32
+ });
33
+ const nodes = [];
34
+ while (walker.nextNode()) nodes.push(walker.currentNode);
35
+ const hits = [];
36
+ for (const node of nodes) {
37
+ const ranges = matchRanges(node.textContent, query);
38
+ if (!ranges.length) continue;
39
+ const fragment = document.createDocumentFragment();
40
+ let offset = 0;
41
+ for (const [start, end] of ranges) {
42
+ fragment.append(
43
+ document.createTextNode(node.textContent.slice(offset, start)),
44
+ );
45
+ const mark = el("mark", node.textContent.slice(start, end));
46
+ mark.dataset.hit = "";
47
+ fragment.append(mark);
48
+ hits.push(mark);
49
+ offset = end;
50
+ }
51
+ fragment.append(document.createTextNode(node.textContent.slice(offset)));
52
+ node.replaceWith(fragment);
53
+ }
54
+ return hits;
55
+ }
56
+
57
+ let finders = [];
58
+ function attachFinder(input, root, count, prev, next) {
59
+ const rows = [...root.querySelectorAll("tbody tr")];
60
+ let hits = [];
61
+ let index = -1;
62
+ const state = {
63
+ input,
64
+ reset() {
65
+ for (const row of rows) row.hidden = false;
66
+ hits = [];
67
+ index = -1;
68
+ count.textContent = "";
69
+ prev.disabled = next.disabled = true;
70
+ },
71
+ };
72
+ finders.push(state);
73
+ const update = () => {
74
+ count.textContent = input.value
75
+ ? `${index < 0 ? 0 : index + 1} / ${hits.length}`
76
+ : "";
77
+ prev.disabled = next.disabled = !hits.length;
78
+ };
79
+ const move = (direction) => {
80
+ if (!hits.length) return;
81
+ hits[index]?.classList.remove("active-hit");
82
+ index = (index + direction + hits.length) % hits.length;
83
+ hits[index].classList.add("active-hit");
84
+ hits[index].scrollIntoView({ block: "center", behavior: "smooth" });
85
+ update();
86
+ };
87
+ input.oninput = () => {
88
+ for (const finder of finders)
89
+ if (finder !== state) {
90
+ finder.input.value = "";
91
+ finder.reset();
92
+ }
93
+ clearMarks($("#article"));
94
+ for (const row of rows) {
95
+ row.hidden = !matchesRow([...row.cells].map((cell) => cell.textContent).join(" "), input.value);
96
+ }
97
+ hits = highlight(root, input.value);
98
+ index = -1;
99
+ if (hits.length) move(1);
100
+ else update();
101
+ };
102
+ input.onkeydown = (event) => {
103
+ if (event.key === "Enter") {
104
+ event.preventDefault();
105
+ move(event.shiftKey ? -1 : 1);
106
+ }
107
+ };
108
+ prev.onclick = () => move(-1);
109
+ next.onclick = () => move(1);
110
+ state.reset();
111
+ }
112
+
113
+ function renderNavigation() {
114
+ $("#tabs").replaceChildren();
115
+ for (const tab of site.tabs) {
116
+ const first = site.documents.find((doc) => doc.tab === tab.slug);
117
+ const link = el("a", tab.title, tab.slug === activeTab ? "active" : "");
118
+ link.href = first ? route(first.id) : route(`${tab.slug}/`);
119
+ if (tab.slug === activeTab) link.setAttribute("aria-current", "page");
120
+ $("#tabs").append(link);
121
+ }
122
+ $("#documents").replaceChildren();
123
+ const folders = new Map();
124
+ for (const doc of site.documents.filter((item) => item.tab === activeTab)) {
125
+ let parent = $("#documents");
126
+ let key = "";
127
+ for (const part of doc.path.split("/").slice(0, -1)) {
128
+ key += `${part}/`;
129
+ if (!folders.has(key)) {
130
+ const group = el("details", undefined, "folder-group");
131
+ group.open = current?.path.startsWith(key) || false;
132
+ group.append(el("summary", part));
133
+ const children = el("div", undefined, "folder-children");
134
+ group.append(children);
135
+ parent.append(group);
136
+ folders.set(key, children);
137
+ }
138
+ parent = folders.get(key);
139
+ }
140
+ const link = el("a", doc.title, doc.id === current?.id ? "selected" : "");
141
+ link.href = route(doc.id);
142
+ if (doc.id === current?.id) link.setAttribute("aria-current", "page");
143
+ parent.append(link);
144
+ }
145
+ }
146
+
147
+ function render() {
148
+ let id, anchor;
149
+ try {
150
+ [id, anchor] = location.hash.slice(2).split("/").map(decodeURIComponent);
151
+ } catch {
152
+ id = "invalid";
153
+ }
154
+ current = id
155
+ ? site.documents.find((doc) => doc.id === id)
156
+ : site.documents[0];
157
+ activeTab =
158
+ current?.tab ||
159
+ site.tabs.find((tab) => id?.startsWith(`${tab.slug}/`))?.slug ||
160
+ site.tabs[0].slug;
161
+ renderNavigation();
162
+ $("#toc").replaceChildren();
163
+ $("#pagination").replaceChildren();
164
+ $("#page-search").value = "";
165
+ finders = [];
166
+ $(".document-find").open = false;
167
+ if (!current) {
168
+ $("#article").replaceChildren(
169
+ el(
170
+ "h1",
171
+ id?.endsWith("/") || !id
172
+ ? "아직 문서가 없습니다"
173
+ : "문서를 찾을 수 없습니다",
174
+ ),
175
+ el(
176
+ "p",
177
+ "설정된 폴더에 Markdown 파일을 추가하거나 왼쪽 목록에서 문서를 선택하세요.",
178
+ ),
179
+ );
180
+ $(".document-tools").hidden = true;
181
+ $("#breadcrumb").textContent = site.tabs.find(
182
+ (tab) => tab.slug === activeTab,
183
+ ).title;
184
+ return;
185
+ }
186
+ $(".document-tools").hidden = false;
187
+ document.title = `${current.title} · ${site.title}`;
188
+ $("#breadcrumb").textContent =
189
+ `${site.tabs.find((tab) => tab.slug === current.tab).title} / ${current.path}`;
190
+ $("#article").innerHTML = current.html;
191
+ if (!$("#article h1")) $("#article").prepend(el("h1", current.title));
192
+ // Existing containers with a leading heading also display the search below it.
193
+ for (const section of document.querySelectorAll(".search-section")) {
194
+ const heading =
195
+ section.querySelector(".section-content")?.firstElementChild;
196
+ if (heading && /^H[2-6]$/.test(heading.tagName)) section.before(heading);
197
+ }
198
+ for (const heading of current.toc.filter((item) => item.level > 1)) {
199
+ const link = el("a", heading.title);
200
+ link.href = route(current.id, heading.anchor);
201
+ link.style.paddingLeft = `${Math.max(0, heading.level - 2) * 12}px`;
202
+ $("#toc").append(link);
203
+ }
204
+ const siblings = site.documents.filter((doc) => doc.tab === activeTab);
205
+ const index = siblings.indexOf(current);
206
+ for (const [label, doc] of [
207
+ ["← 이전 문서", siblings[index - 1]],
208
+ ["다음 문서 →", siblings[index + 1]],
209
+ ]) {
210
+ if (!doc) {
211
+ $("#pagination").append(el("span"));
212
+ continue;
213
+ }
214
+ const link = el("a");
215
+ link.href = route(doc.id);
216
+ link.append(el("small", label), el("strong", doc.title));
217
+ $("#pagination").append(link);
218
+ }
219
+ attachFinder(
220
+ $("#page-search"),
221
+ $("#article"),
222
+ $("#page-count"),
223
+ $("#page-prev"),
224
+ $("#page-next"),
225
+ );
226
+ for (const section of document.querySelectorAll(".search-section"))
227
+ attachFinder(
228
+ section.querySelector("[data-section-search]"),
229
+ section.querySelector(".section-content"),
230
+ section.querySelector(".match-count"),
231
+ section.querySelector("[data-find-prev]"),
232
+ section.querySelector("[data-find-next]"),
233
+ );
234
+ if (pendingQuery) {
235
+ $(".document-find").open = true;
236
+ $("#page-search").value = pendingQuery;
237
+ $("#page-search").oninput();
238
+ pendingQuery = "";
239
+ }
240
+ if (anchor) {
241
+ const heading = [...$("#article").querySelectorAll("[id]")].find(
242
+ (node) => node.id === anchor,
243
+ );
244
+ requestAnimationFrame(() => heading?.scrollIntoView({ block: "start" }));
245
+ } else window.scrollTo(0, 0);
246
+ }
247
+
248
+ function renderResults() {
249
+ const query = $("#global-search").value;
250
+ const results = searchDocuments(site.documents, query);
251
+ $("#search-count").textContent = query.trim()
252
+ ? results.length
253
+ ? `${results.length}개 결과${results.length === 80 ? " (최대 80개 표시)" : ""}`
254
+ : "일치하는 내용이 없습니다."
255
+ : "한국어와 영문으로 모든 탭의 내용을 검색합니다.";
256
+ $("#results").replaceChildren();
257
+ for (const { doc, section } of results) {
258
+ const link = el("a", undefined, "result");
259
+ link.href = route(doc.id, section.anchor);
260
+ const title = el("strong", section.title);
261
+ const ranges = matchRanges(section.text, query);
262
+ const start = Math.max(0, (ranges[0]?.[0] || 0) - 45);
263
+ const snippet = el(
264
+ "p",
265
+ `${start ? "…" : ""}${section.text.slice(start, start + 180)}${section.text.length > start + 180 ? "…" : ""}`,
266
+ );
267
+ link.append(
268
+ el(
269
+ "small",
270
+ `${site.tabs.find((tab) => tab.slug === doc.tab).title} / ${doc.title}`,
271
+ ),
272
+ title,
273
+ snippet,
274
+ );
275
+ highlight(title, query);
276
+ highlight(snippet, query);
277
+ link.onclick = () => {
278
+ pendingQuery = query;
279
+ dialog.close();
280
+ if (location.hash === link.hash) render();
281
+ };
282
+ $("#results").append(link);
283
+ }
284
+ }
285
+
286
+ const openSearch = () => {
287
+ if (!site) return;
288
+ dialog.showModal();
289
+ $("#global-search").focus();
290
+ renderResults();
291
+ };
292
+ $("#open-search").onclick = openSearch;
293
+ $("#close-search").onclick = () => dialog.close();
294
+ $("#global-search").oninput = renderResults;
295
+ $("#global-search").onkeydown = (event) => {
296
+ if (event.key === "ArrowDown") {
297
+ event.preventDefault();
298
+ $("#results a")?.focus();
299
+ } else if (event.key === "Enter") $("#results a")?.click();
300
+ };
301
+ $("#results").onkeydown = (event) => {
302
+ if (!["ArrowDown", "ArrowUp"].includes(event.key)) return;
303
+ event.preventDefault();
304
+ const links = [...$("#results").children];
305
+ links[
306
+ (links.indexOf(document.activeElement) +
307
+ (event.key === "ArrowDown" ? 1 : -1) +
308
+ links.length) %
309
+ links.length
310
+ ]?.focus();
311
+ };
312
+ document.addEventListener("keydown", (event) => {
313
+ if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "k") {
314
+ event.preventDefault();
315
+ if (!dialog.open) openSearch();
316
+ }
317
+ });
318
+ dialog.addEventListener("click", (event) => {
319
+ if (event.target === dialog) {
320
+ const rect = dialog.getBoundingClientRect();
321
+ if (
322
+ event.clientX < rect.left ||
323
+ event.clientX > rect.right ||
324
+ event.clientY < rect.top ||
325
+ event.clientY > rect.bottom
326
+ )
327
+ dialog.close();
328
+ }
329
+ });
330
+ window.addEventListener("hashchange", () => {
331
+ if (site) render();
332
+ });
333
+ $(".skip-link").onclick = (event) => {
334
+ event.preventDefault();
335
+ $("#content").focus();
336
+ $("#content").scrollIntoView();
337
+ };
338
+ try {
339
+ const response = await fetch("./site.json");
340
+ if (!response.ok) throw new Error(`HTTP ${response.status}`);
341
+ site = await response.json();
342
+ $("#site-title").textContent = site.title;
343
+ render();
344
+ } catch (error) {
345
+ $("#article").replaceChildren(
346
+ el("h1", "문서를 불러오지 못했습니다"),
347
+ el("p", `정적 HTTP 서버에서 사이트를 열어주세요. ${error.message}`),
348
+ );
349
+ }