@devport-kr/portki 0.1.1

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/.env.example ADDED
@@ -0,0 +1,11 @@
1
+ # Optional overrides only.
2
+ # The public branch works without any .env file.
3
+
4
+ # Quality gate: standard | strict
5
+ DEVPORT_QUALITY_GATE_LEVEL=strict
6
+
7
+ # Trend ingestion window in days
8
+ DEVPORT_TREND_WINDOW_DAYS=180
9
+
10
+ # Official docs discovery mode
11
+ DEVPORT_OFFICIAL_DOC_DISCOVERY=auto
package/AGENTS.md ADDED
@@ -0,0 +1,205 @@
1
+ # portki public-agent instructions
2
+
3
+ ## Role
4
+
5
+ You are the AI agent operating this tool. This repository is the public branch of the devport wiki generator. It reads public GitHub repositories and produces Korean wiki content as plain Markdown files. `src/agent.ts` handles the deterministic pipeline only. The agent is responsible for understanding the codebase and writing the content.
6
+
7
+ Do not call external LLM APIs. Do not add OpenAI or Anthropic API usage.
8
+
9
+ ## Public Branch Rules
10
+
11
+ - This branch is the public version.
12
+ - There is no DB, no embeddings, no PostgreSQL, and no OpenAI API dependency.
13
+ - It should work without `.env` setup.
14
+ - Final output lives under `devport-output/wiki/{owner}/{repo}/` as Markdown files.
15
+ - `persist-section` means local validation plus session registration only.
16
+ - `finalize` assembles the full Markdown wiki bundle.
17
+ - `package` is the monolithic path that exports Markdown directly from a full accepted output.
18
+
19
+ ## Only Use `src/agent.ts`
20
+
21
+ The only supported commands are:
22
+
23
+ - `ingest`
24
+ - `detect`
25
+ - `package`
26
+ - `plan-sections`
27
+ - `validate-plan`
28
+ - `persist-section`
29
+ - `finalize`
30
+
31
+ Do not use legacy entrypoints.
32
+
33
+ ## Required End-to-End Flow
34
+
35
+ Preferred chunked flow:
36
+
37
+ 1. `ingest`
38
+ 2. `plan-sections`
39
+ 3. The agent writes `section-plan.json`
40
+ 4. `validate-plan`
41
+ 5. The agent writes section outputs
42
+ 6. `persist-section` for each section
43
+ 7. `finalize --advance_baseline`
44
+
45
+ Monolithic alternative for small repos:
46
+
47
+ 1. `ingest`
48
+ 2. The agent writes `accepted-output.json`
49
+ 3. `package --advance_baseline`
50
+
51
+ ## Public Repo Assumption
52
+
53
+ - This branch targets public repositories by default.
54
+ - `GITHUB_TOKEN` is not required.
55
+ - Private repository support is out of scope for this branch.
56
+
57
+ ## Workspace Naming Rule
58
+
59
+ If multiple repos are processed in parallel, all agent-authored intermediate files must be stored in `devport-output/workspace/` and prefixed with the repo slug.
60
+
61
+ Examples:
62
+
63
+ - `devport-output/workspace/ollama-artifact.json`
64
+ - `devport-output/workspace/ollama-section-plan.json`
65
+ - `devport-output/workspace/ollama-section-1-output.json`
66
+
67
+ ## Commands
68
+
69
+ ### `ingest`
70
+
71
+ ```bash
72
+ npx tsx src/agent.ts ingest --repo owner/repo --out devport-output/workspace/{repo-slug}-artifact.json
73
+ ```
74
+
75
+ The agent must read these fields:
76
+
77
+ - `ingest_run_id`
78
+ - `commit_sha`
79
+ - `repo_ref`
80
+ - `snapshot_path`
81
+ - `files_scanned`
82
+ - `metadata.key_paths`
83
+ - `metadata.language_mix`
84
+
85
+ ### `detect`
86
+
87
+ ```bash
88
+ npx tsx src/agent.ts detect --repo owner/repo
89
+ ```
90
+
91
+ Interpret the status as:
92
+
93
+ - `noop`: do nothing
94
+ - `incremental`: regenerate only `impacted_section_ids`
95
+ - `full-rebuild`: regenerate everything
96
+
97
+ ### `plan-sections`
98
+
99
+ ```bash
100
+ npx tsx src/agent.ts plan-sections --artifact devport-output/workspace/{repo-slug}-artifact.json --out devport-output/workspace/{repo-slug}-plan-context.json
101
+ ```
102
+
103
+ The output includes:
104
+
105
+ - `profile`
106
+ - `readmeExcerpt`
107
+ - `keyPaths`
108
+ - `fileTree`
109
+ - `constraints`
110
+
111
+ ### `validate-plan`
112
+
113
+ ```bash
114
+ npx tsx src/agent.ts validate-plan --input devport-output/workspace/{repo-slug}-section-plan.json --context devport-output/workspace/{repo-slug}-plan-context.json --out devport-output/workspace/{repo-slug}-section-plan.json
115
+ ```
116
+
117
+ ### `persist-section`
118
+
119
+ ```bash
120
+ npx tsx src/agent.ts persist-section --plan devport-output/workspace/{repo-slug}-section-plan.json --section sec-1 --input devport-output/workspace/{repo-slug}-section-1-output.json
121
+ ```
122
+
123
+ This command only does the following:
124
+
125
+ - validates the section JSON schema
126
+ - checks body length, repetition, Mermaid, and source paths
127
+ - updates `session.json`
128
+
129
+ It does not write to a database, generate embeddings, or call external APIs.
130
+
131
+ ### `finalize`
132
+
133
+ ```bash
134
+ npx tsx src/agent.ts finalize --plan devport-output/workspace/{repo-slug}-section-plan.json --advance_baseline
135
+ ```
136
+
137
+ This command:
138
+
139
+ - validates cross-section repetition
140
+ - assembles persisted sections from the local session
141
+ - writes `devport-output/wiki/{owner}/{repo}/README.md`
142
+ - writes section Markdown files such as `devport-output/wiki/{owner}/{repo}/01-sec-1.md`
143
+ - optionally advances the freshness baseline
144
+
145
+ ### `package`
146
+
147
+ ```bash
148
+ npx tsx src/agent.ts package --input devport-output/workspace/{repo-slug}-accepted-output.json --advance_baseline
149
+ ```
150
+
151
+ This validates a monolithic accepted output and writes the same Markdown wiki bundle.
152
+
153
+ ## Section Writing Rules
154
+
155
+ - Read actual files from the snapshot.
156
+ - All Korean prose must use formal `합니다` style.
157
+ - Prefer 4 to 6 sections.
158
+ - Each section must have at least 3 subsections.
159
+ - Each `bodyKo` must be at least 3,000 characters.
160
+ - At least one architecture Mermaid block must exist.
161
+ - `sourcePaths` must point to real files in the snapshot.
162
+ - Do not pad with repeated sentences or repeated long blocks.
163
+
164
+ ## `sub-1-1` Override
165
+
166
+ `sub-1-1` is the project-level introduction.
167
+
168
+ - Explain what the project is and why it exists.
169
+ - Include installation or getting-started guidance.
170
+ - Briefly map what the remaining sections cover.
171
+ - Do not make it a code call-flow analysis section.
172
+
173
+ ## Output Shape
174
+
175
+ Per-section output:
176
+
177
+ ```json
178
+ {
179
+ "sectionId": "sec-1",
180
+ "titleKo": "Project Overview",
181
+ "summaryKo": "This section explains ...",
182
+ "sourcePaths": ["README.md", "src/main.ts"],
183
+ "subsections": [
184
+ {
185
+ "sectionId": "sec-1",
186
+ "subsectionId": "sub-1-1",
187
+ "titleKo": "Project Introduction and Overview",
188
+ "bodyKo": "..."
189
+ }
190
+ ]
191
+ }
192
+ ```
193
+
194
+ The final result is Markdown, not a delivery JSON artifact.
195
+
196
+ ## Output Paths
197
+
198
+ ```text
199
+ devport-output/
200
+ workspace/
201
+ snapshots/{owner}/{repo}/
202
+ chunked/{owner}/{repo}/session.json
203
+ wiki/{owner}/{repo}/
204
+ freshness/state.json
205
+ ```
package/CLAUDE.md ADDED
@@ -0,0 +1,174 @@
1
+ # portki public-agent instructions for Claude Code
2
+
3
+ ## Role
4
+
5
+ You are the AI agent operating this tool. This repository is the public branch of the devport wiki generator. It reads public GitHub repositories and produces Korean wiki content as plain Markdown files. `src/agent.ts` handles the deterministic pipeline only. The agent is responsible for understanding the codebase and writing the content.
6
+
7
+ Do not call external LLM APIs. Do not add OpenAI or Anthropic API usage.
8
+
9
+ ## Public Branch Rules
10
+
11
+ - This branch is the public version.
12
+ - There is no DB, no embeddings, no PostgreSQL, and no OpenAI API dependency.
13
+ - It should work without `.env` setup.
14
+ - Final output lives under `devport-output/wiki/{owner}/{repo}/` as Markdown files.
15
+ - `persist-section` means local validation plus session registration only.
16
+ - `finalize` assembles the full Markdown wiki bundle.
17
+ - `package` is the monolithic path that exports Markdown directly from a full accepted output.
18
+
19
+ ## Only Use `src/agent.ts`
20
+
21
+ The only supported commands are:
22
+
23
+ - `ingest`
24
+ - `detect`
25
+ - `package`
26
+ - `plan-sections`
27
+ - `validate-plan`
28
+ - `persist-section`
29
+ - `finalize`
30
+
31
+ ## Required Flow
32
+
33
+ Preferred chunked flow:
34
+
35
+ 1. `ingest`
36
+ 2. `plan-sections`
37
+ 3. The agent writes `section-plan.json`
38
+ 4. `validate-plan`
39
+ 5. The agent writes section outputs
40
+ 6. `persist-section` for each section
41
+ 7. `finalize --advance_baseline`
42
+
43
+ Monolithic alternative for small repos:
44
+
45
+ 1. `ingest`
46
+ 2. The agent writes `accepted-output.json`
47
+ 3. `package --advance_baseline`
48
+
49
+ ## Public Repo Assumption
50
+
51
+ - This branch targets public repositories by default.
52
+ - `GITHUB_TOKEN` is not required.
53
+ - Private repository support is out of scope for this branch.
54
+
55
+ ## Workspace Naming Rule
56
+
57
+ All agent-authored intermediate files must be written to `devport-output/workspace/` and prefixed with the repo slug.
58
+
59
+ Examples:
60
+
61
+ - `devport-output/workspace/redis-artifact.json`
62
+ - `devport-output/workspace/redis-section-plan.json`
63
+ - `devport-output/workspace/redis-section-2-output.json`
64
+
65
+ ## Commands
66
+
67
+ ### `ingest`
68
+
69
+ ```bash
70
+ npx tsx src/agent.ts ingest --repo owner/repo --out devport-output/workspace/{repo-slug}-artifact.json
71
+ ```
72
+
73
+ Read these fields from the artifact:
74
+
75
+ - `ingest_run_id`
76
+ - `commit_sha`
77
+ - `repo_ref`
78
+ - `snapshot_path`
79
+ - `files_scanned`
80
+ - `metadata.key_paths`
81
+ - `metadata.language_mix`
82
+
83
+ ### `detect`
84
+
85
+ ```bash
86
+ npx tsx src/agent.ts detect --repo owner/repo
87
+ ```
88
+
89
+ - `noop`: stop
90
+ - `incremental`: regenerate only the impacted sections
91
+ - `full-rebuild`: regenerate everything
92
+
93
+ ### `plan-sections`
94
+
95
+ ```bash
96
+ npx tsx src/agent.ts plan-sections --artifact devport-output/workspace/{repo-slug}-artifact.json --out devport-output/workspace/{repo-slug}-plan-context.json
97
+ ```
98
+
99
+ ### `validate-plan`
100
+
101
+ ```bash
102
+ npx tsx src/agent.ts validate-plan --input devport-output/workspace/{repo-slug}-section-plan.json --context devport-output/workspace/{repo-slug}-plan-context.json --out devport-output/workspace/{repo-slug}-section-plan.json
103
+ ```
104
+
105
+ ### `persist-section`
106
+
107
+ ```bash
108
+ npx tsx src/agent.ts persist-section --plan devport-output/workspace/{repo-slug}-section-plan.json --section sec-1 --input devport-output/workspace/{repo-slug}-section-1-output.json
109
+ ```
110
+
111
+ What it does:
112
+
113
+ - validates the section JSON
114
+ - checks body length, repetition, Mermaid, and source paths
115
+ - updates the local `session.json`
116
+
117
+ What it does not do:
118
+
119
+ - database writes
120
+ - embedding generation
121
+ - external API calls
122
+
123
+ ### `finalize`
124
+
125
+ ```bash
126
+ npx tsx src/agent.ts finalize --plan devport-output/workspace/{repo-slug}-section-plan.json --advance_baseline
127
+ ```
128
+
129
+ Outputs:
130
+
131
+ - `devport-output/wiki/{owner}/{repo}/README.md`
132
+ - `devport-output/wiki/{owner}/{repo}/01-sec-1.md`
133
+ - additional section Markdown files
134
+
135
+ ### `package`
136
+
137
+ ```bash
138
+ npx tsx src/agent.ts package --input devport-output/workspace/{repo-slug}-accepted-output.json --advance_baseline
139
+ ```
140
+
141
+ This validates a monolithic accepted output and writes the same Markdown result.
142
+
143
+ ## Writing Rules
144
+
145
+ - Use real snapshot files only.
146
+ - All Korean prose must use formal `합니다` style.
147
+ - Prefer 4 to 6 sections.
148
+ - Each section must have at least 3 subsections.
149
+ - Each `bodyKo` must be at least 3,000 characters.
150
+ - Include at least one Mermaid architecture block.
151
+ - `sourcePaths` must be real snapshot paths.
152
+ - Do not use repetitive filler blocks.
153
+
154
+ ## `sub-1-1` Override
155
+
156
+ `sub-1-1` is the project introduction summary.
157
+
158
+ - explain the project purpose
159
+ - explain the problem space
160
+ - include getting-started guidance
161
+ - briefly map the remaining sections
162
+
163
+ Code call-flow analysis should begin in `sub-1-2` or later.
164
+
165
+ ## Output Paths
166
+
167
+ ```text
168
+ devport-output/
169
+ workspace/
170
+ snapshots/{owner}/{repo}/
171
+ chunked/{owner}/{repo}/session.json
172
+ wiki/{owner}/{repo}/
173
+ freshness/state.json
174
+ ```
package/README.md ADDED
@@ -0,0 +1,144 @@
1
+ # portki (포트키)
2
+
3
+ **portki**는 **ports** + **wiki** 의 합성어로 ['포트키(Portkey)'](https://en.wikipedia.org/wiki/Magical_objects_in_Harry_Potter#Portkeys)처럼 순간이동해 다양한 AI 프로젝트를 만날 수 있는 Agent 입니다. [devport](https://devport.kr)의 [ports](https://devport.kr/ports)에 있는 모든 위키를 책임지고 있습니다.
4
+
5
+
6
+ ## 주요 기능
7
+
8
+ - **GitHub 저장소 스냅샷 수집**: 저장소의 코드를 분석하기 위해 특정 커밋 시점의 스냅샷을 다운로드합니다.
9
+ - **AI 에이전트 인터페이스**: AI가 코드베이스를 직접 읽고, 분석하여 위키 문서를 작성할 수 있도록 기계적인 파이프라인(스냅샷, 변경 감지, 검증, 세션 기록, Markdown 출력 등)을 제공합니다.
10
+ - **청크 기반 생성 (Chunked Generation)**: 저장소의 규모가 클 경우, 문서를 여러 섹션으로 나누고 각 섹션 단위로 상세한 문서를 생성 및 검증한 뒤 로컬 세션 상태에 반영합니다.
11
+ - **순수 Markdown 출력**: 최종 위키를 데이터베이스가 아니라 `README.md`와 섹션별 `.md` 파일로 출력합니다.
12
+ - **증분 업데이트 (Incremental Update)**: 전체 코드를 매번 다시 분석하지 않고, 마지막 위키 생성 커밋 이후 변경된 파일과 영향을 받는 섹션만 추적하여 위키를 효율적으로 갱신합니다.
13
+
14
+ ## 설치
15
+
16
+ Node.js 환경이 필요합니다.
17
+
18
+ ```bash
19
+ npm install
20
+ ```
21
+
22
+ 공개 버전에서는 `.env`를 만들 필요가 없습니다.
23
+
24
+ 출시 후에는 로컬 clone 없이도 사용할 수 있습니다.
25
+
26
+ ```bash
27
+ npx @devport-kr/portki help
28
+ ```
29
+
30
+ 또는 전역 설치:
31
+
32
+ ```bash
33
+ npm install -g @devport-kr/portki
34
+ portki help
35
+ ```
36
+
37
+ ## GitHub Releases
38
+
39
+ `public` 브랜치에서는 GitHub Release를 만들 수 있습니다.
40
+
41
+ - `v*` 태그를 `public` 브랜치 커밋에 push하면 Release가 자동으로 생성됩니다.
42
+ - Actions의 수동 실행(`workflow_dispatch`)으로도 Release를 만들 수 있습니다.
43
+ - Release에는 자동 생성된 노트와 함께 소스 아카이브(`.tar.gz`, `.zip`), npm 패키지 tarball(`devport-kr-portki-<version>.tgz`), SHA256 체크섬 파일이 첨부됩니다.
44
+ - npm publish workflow를 함께 켜두면 같은 `v*` 태그에서 npm 패키지도 배포할 수 있습니다.
45
+
46
+ 기본 절차:
47
+
48
+ ```bash
49
+ git checkout public
50
+ git pull origin public
51
+
52
+ # package.json version과 태그는 일치해야 합니다.
53
+ git tag v0.1.1
54
+ git push origin public --follow-tags
55
+ ```
56
+
57
+ npm 배포까지 하려면 저장소 Secrets에 `NPM_TOKEN`을 추가해야 합니다.
58
+
59
+ ## 권장 실행 환경
60
+ **(2026년 3월 7일 기준)**
61
+ | 환경 | 권장 모델 | (Effort (Thinking) Level) | 설정 지침 |
62
+ |------|-----------|--------------------------|------------------|
63
+ | **Claude Code** | `Opus 4.6` | High | [`CLAUDE.md`](./CLAUDE.md)|
64
+ | **Codex** | `GPT-5.4` | xHigh | [`AGENTS.md`](./AGENTS.md)|
65
+ | **Gemini CLI** | `gemini 3.1-pro-preview` | High | [`AGENTS.md`](./AGENTS.md)|
66
+
67
+ ## 명령어 (Commands)
68
+
69
+ 모든 명령은 프로젝트 루트에서 실행합니다.
70
+
71
+ ```bash
72
+ npx tsx src/agent.ts <command> [flags]
73
+ ```
74
+
75
+ | 명령 | 설명 |
76
+ |------|------|
77
+ | `ingest` | 저장소 스냅샷을 수집하고 분석용 메타데이터(`artifact.json`)를 생성합니다. |
78
+ | `plan-sections` | 저장소 구조를 분석하여 섹션별 작성 계획을 위한 컨텍스트와 중점 분석 대상 파일 목록을 제공합니다. |
79
+ | `validate-plan` | AI가 생성한 섹션 플랜의 정합성(스키마, 조건 등)을 검증합니다. |
80
+ | `persist-section` | 생성된 단일 섹션의 품질을 검증하고, 허용되면 로컬 세션 상태에 반영합니다. |
81
+ | `finalize` | 작성 완료된 모든 섹션 간의 교차 검증을 수행하고, 최종 Markdown 위키와 기준점을 업데이트합니다. |
82
+ | `package` | 위키 결과물 규격을 검증하고 순수 Markdown 위키 번들로 출력합니다. |
83
+ | `detect` | 마지막 배포 시점과 현재 저장소의 변경 사항을 비교하여 증분 업데이트 필요 여부와 대상 섹션을 파악합니다. |
84
+
85
+ ## 워크플로우
86
+
87
+ 이 도구는 AI 에이전트가 위키 문서를 더 정확하고 꼼꼼하게 작성하도록 **청크 단위 작업**을 권장합니다.
88
+
89
+ ### 1. 청크 단위 위키 생성 (권장)
90
+
91
+ 저장소를 분석하여 여러 섹션으로 분리한 후 각 섹션별로 코드를 깊이 있게 확인하고 작성하는 방식입니다.
92
+
93
+ ```bash
94
+ # 1. 저장소 스냅샷 수집
95
+ npx tsx src/agent.ts ingest --repo owner/repo --out devport-output/workspace/{repo-slug}-artifact.json
96
+
97
+ # 2. 분석 및 섹션 계획 수립 준비 (컨텍스트 생성)
98
+ npx tsx src/agent.ts plan-sections --artifact devport-output/workspace/{repo-slug}-artifact.json --out devport-output/workspace/{repo-slug}-plan-context.json
99
+
100
+ # (AI 작업: plan-context.json과 주요 코드를 바탕으로 {repo-slug}-section-plan.json 생성)
101
+
102
+ # 3. 플랜 검증
103
+ npx tsx src/agent.ts validate-plan --input devport-output/workspace/{repo-slug}-section-plan.json --context devport-output/workspace/{repo-slug}-plan-context.json --out devport-output/workspace/{repo-slug}-section-plan.json
104
+
105
+ # 4. 각 섹션별 작성 및 세션 반영 (전체 섹션 완료 시까지 반복)
106
+ # (AI 작업: 해당 섹션의 코드를 분석하고 {repo-slug}-section-1-output.json 생성)
107
+ npx tsx src/agent.ts persist-section --plan devport-output/workspace/{repo-slug}-section-plan.json --section sec-1 --input devport-output/workspace/{repo-slug}-section-1-output.json
108
+
109
+ # 5. 최종 완성 및 증분 베이스라인 갱신
110
+ npx tsx src/agent.ts finalize --plan devport-output/workspace/{repo-slug}-section-plan.json --advance_baseline
111
+ ```
112
+
113
+ `finalize`가 완료되면 `devport-output/wiki/{owner}/{repo}/README.md`와 섹션별 Markdown 파일이 생성됩니다.
114
+
115
+ ### 2. 증분 업데이트 (Incremental Update)
116
+
117
+ 이전에 작성 완료된 위키를 바탕으로 변경된 파일들만 식별하여 최신화합니다.
118
+
119
+ ```bash
120
+ # 1. 변경사항 감지
121
+ npx tsx src/agent.ts detect --repo owner/repo
122
+ # 반환된 JSON의 status에 따라 분기:
123
+ # - noop: 변경점 없음 (수정 불필요)
124
+ # - incremental: 변경된 코드와 영향을 받는 섹션(impacted_section_ids)만 재생성
125
+ # - full-rebuild: 너무 많은 변화로 인해 전체 위키 재작성 필요
126
+
127
+ # 2. 재생성 필요 시 최신 코드로 스냅샷 다시 수집
128
+ npx tsx src/agent.ts ingest --repo owner/repo --out devport-output/workspace/{repo-slug}-artifact.json
129
+
130
+ # (이후 영향을 받는 섹션만 다시 작성하여 persist-section 후 finalize 수행)
131
+ ```
132
+
133
+ ## 출력 경로 (File Layout)
134
+
135
+ 작업 중에 AI가 생성한 임시 파일과 파이프라인이 생성한 모든 데이터는 프로젝트 루트를 오염시키지 않도록 `devport-output/` 내부에 기록됩니다. (이 디렉터리는 `.gitignore`에 포함되어 있습니다.)
136
+
137
+ ```text
138
+ devport-output/
139
+ workspace/ # AI 에이전트가 중간에 생성하고 읽는 작업 파일 ({repo-slug}-*.json)
140
+ snapshots/{owner}/{repo}/ # 다운로드된 코드 스냅샷 원본 (절대 직접 수정 금지)
141
+ wiki/{owner}/{repo}/ # 최종 Markdown 위키 출력
142
+ chunked/{owner}/{repo}/ # 진행 중인 섹션별 작업 및 세션 상태 보관 파일
143
+ freshness/state.json # 증분 업데이트 감지 시 사용하는 마지막 베이스라인 상태 파일
144
+ ```
package/dist/cli.cjs ADDED
@@ -0,0 +1,6 @@
1
+ #!/usr/bin/env node
2
+
3
+ import("./cli.js").catch((error) => {
4
+ process.stderr.write(`\n[portki] error: ${String(error)}\n`);
5
+ process.exitCode = 1;
6
+ });