deukpack 1.0.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2024 gplat-team
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,6 @@
+DeukPack (core engine)
+Copyright 2024 gplat-team
+
+This product includes software developed as part of the DeukPack project.
+
+SPDX-License-Identifier: Apache-2.0

package/README.ko.md

@@ -0,0 +1,138 @@
+# DeukPack
+
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![npm version](https://img.shields.io/npm/v/deukpack.svg)](https://www.npmjs.com/package/deukpack)
+
+**한 줄 요약:** **득팩(DeukPack)** 은 **네이티브 `.deuk` IDL** 을 중심으로 **Protobuf·OpenAPI·JSON Schema·CSV·레거시 `.thrift`** 까지 한 파이프라인에서 **C#·C++·JavaScript** 코드·스키마를 뽑는 **고속 파싱·코드 생성 엔진**이다. **표준에 가까운 Protobuf 호환(와이어)** 을 먼저 두고, 레거시 공존은 선택.
+
+**v1.0.0 공개 약속**은 **IDL·프로토콜 코드젠·CLI·Binary/Compact/JSON 와이어**만. **Excel 프로토콜·Excel 애드인은 별도 배포** → [DEUKPACK_EXCEL_SEPARATE_DISTRIBUTION.md](docs/DEUKPACK_EXCEL_SEPARATE_DISTRIBUTION.md), [DEUKPACK_V1_RELEASE_SCOPE.md](docs/DEUKPACK_V1_RELEASE_SCOPE.md).
+
+---
+
+## 왜 DeukPack인가?
+
+- **속도:** 대량 IDL도 수십 배 빠른 파싱·코드 생성(예: 160파일 ~1초 vs 15–25초). 런타임 직렬화/역직렬화도 약 10배 빠른 수준.
+- **단일 소스:** **`.deuk` 우선**; `.proto`, `.thrift`, OpenAPI 등과 **한 빌드**에 섞을 수 있음. 직렬화·SQLite 등은 코드 생성. *(v1: Excel·완결 테이블 파이프라인은 비공약.)*
+- **와이어:** **Protobuf 호환(Binary/Compact)** 을 표준으로; 필요 시 레거시 스택과 공존. 득팩을 “Thrift 전용 호환”으로 소개하지 않음.
+- **득팩만의 레이어:** GetSchema, SQLite, msgId·ProtocolRegistry 등 — 게임·백엔드·툴에 맞춘 **득팩 런타임**이 본체. *(메타 테이블·Excel 완결은 후속.)*
+- **AI·에이전트:** `.deuk`, `.proto`, `.thrift`, OpenAPI 입력 → **결정론적 코드·직렬화**. [AI 파이프라인](docs/DEUKPACK_AI_PIPELINE_INTEGRATION.md).
+
+→ [전체 문서](docs/) · [코어 엔진 소개](docs/intro/INTRO_DEUKPACK_CORE_ENGINE.md) · [README (English)](README.md)  
+→ **상세 문서(튜토리얼·API 가이드)**: [deukpack.app](https://deukpack.app/)  
+→ **스타터 키트(유니티·C++·네트워크·TS·Java 등)**: [deukpack.app/starter-kits](https://deukpack.app/starter-kits/)
+
+---
+
+## 기능 요약
+
+- **고속 성능:** 대량 IDL 파싱·코드 생성
+- **다언어:** TypeScript, JavaScript, C++, C#
+- **네이티브 바인딩:** C++ 네이티브 모듈로 최대 성능
+- **크로스 플랫폼:** Windows, macOS, Linux
+- **메모리 최적화:** 버퍼 풀링으로 효율적 메모리 사용
+- **타입 안전:** 생성 타입으로 풀 TypeScript 지원
+
+## 설치
+
+**npm 패키지만 쓸 때 (소스 클론 없음)**: [npm 패키지 사용](docs/NPM_PACKAGE.md).
+
+```bash
+npm install deukpack
+```
+
+## 간단한 사용방법 (CLI)
+
+```bash
+# C# + C++ 코드 생성 (.deuk 또는 .thrift)
+npx deukpack ./schema.deuk ./out --csharp --cpp
+
+# include 경로·프로토콜 지정
+npx deukpack ./api.deuk ./gen -I ./includes --csharp --protocol binary
+
+# 파이프라인 (여러 작업 일괄)
+npx deukpack --pipeline ./deukpack-pipeline.json
+```
+
+**빠른 시작 (C# / C++ / TS / JS)**: [docs/QUICKSTART.md](docs/QUICKSTART.md) — 언어별 예제 실행.  
+**디테일한 문서**(튜토리얼, IDL 가이드, API 레퍼런스): **[deukpack.app](https://deukpack.app/)** → [튜토리얼](https://deukpack.app/tutorial/) · [레퍼런스](https://deukpack.app/reference/).
+
+## 지원 언어
+
+- **TypeScript:** 타입 생성 및 IntelliSense
+- **JavaScript:** ES6+ 호환
+- **C++:** 네이티브 C++ 바인딩, STL 컨테이너
+- **C#:** .NET 호환, LINQ 지원
+
+## 성능 (레거시 컴파일러류 워크플로 대비)
+
+| 항목 | 일반적 IDL 컴파일러류 흐름 | DeukPack | 개선 |
+|------|----------------|----------|------|
+| 160파일 파싱 | 15–25초 | 0.5–1초 | **25–50배** |
+| TypeScript 코드젠 | 2–3초 | 0.1–0.2초 | **15–30배** |
+| 직렬화 | 0.5ms | 0.05ms | **10배** |
+| 역직렬화 | 0.8ms | 0.08ms | **10배** |
+| 메모리 | 100MB | 20MB | **약 5배 절감** |
+
+## 개발
+
+```bash
+npm install
+npm run build
+npm run build:native
+npm test
+npm run benchmark
+npm run dev
+```
+
+## 프로젝트 구조
+
+```
+DeukPack/
+├── deukpack.app/     # 제품 소개 사이트 (서브모듈)
+├── docs/             # 기술 문서
+├── src/              # TypeScript 소스
+├── native/           # C++/C# 네이티브
+└── dist/             # 빌드 결과물
+```
+
+## 문서
+
+- **제품 소개(외부):** [deukpack.app](https://deukpack.app/) — 라인업·포지셔닝·라이선스
+- **기술 문서:** [docs/](docs/) — 설계·가이드·목차는 `docs/README.md` 참고
+
+## 문의
+
+문의·피드백은 **contact@deukpack.app** 또는 [deukpack.app](https://deukpack.app/) 문의 안내를 이용해 주세요.
+
+## 릴리즈·tarball 설치
+
+**[RELEASING.md](RELEASING.md)** 참고 — 태그 `v*.*.*` 푸시 시 GitHub Release에 **`deukpack-x.y.z.tgz`** 첨부. 설치: `npm install ./deukpack-x.y.z.tgz`. CLI: `deukpack` / `npx deukpack`.
+
+## 개발 후원
+
+득팩은 **Apache-2.0** 으로 **무료**입니다. 상용·내부 도구에 막힘 없이 쓸 수 있는 대신, **지속 가능한 OSS**가 되려면 문서·CI·호환성 수정·파서·코드젠 개선·이슈/PR 대응 같은 **유지 비용**이 필요합니다.
+
+득팩이 **CI 시간을 줄였거나**, **수작업 직렬화 대신 안정적인 타입·와이어**를 주거나, **게임·서버 스택을 한 IDL로 맞추는 데** 도움이 되었다면, **후원**으로 그 다음 릴리스·[deukpack.app](https://deukpack.app/) 문서·엔진 개선을 응원해 주실 수 있습니다. 금액은 부담 없는 선에서 **일시·정기** 모두 환영입니다.
+
+**개인 PayPal 계정**으로 받습니다. 후원금은 **법인·단체가 아닌**, 유지보수자 개인 계정(**`joygram@gmail.com`**)으로 들어갑니다. 운영 부담을 줄이고 개발 시간에 쓰기 위한 방식입니다.
+
+- **[PayPal로 후원하기](https://www.paypal.com/donate/?business=joygram%40gmail.com&currency_code=USD&item_name=DeukPack%20development)**  
+- 위 링크가 안 열리면 PayPal에서 **송금** → 수신 **`joygram@gmail.com`**. [PayPal.Me](https://www.paypal.com/paypalme/) 링크를 만드시면 README에 추가해 두면 더 편합니다.
+
+**기부금 영수증(세액공제)** 성격이 아닙니다. 등록 단체 기부가 아니라 **개인 OSS 활동 지원(팁)** 으로 이해해 주시면 됩니다.
+
+후원이 어렵다면 **저장소 Star**, **재현 가능한 이슈**, **PR**, 또는 **득팩이 맞는 팀에 소개**만으로도 큰 힘이 됩니다.
+
+## 기여
+
+1. 저장소 Fork
+2. 기능 브랜치 생성 (`git checkout -b feature/amazing-feature`)
+3. 커밋 후 푸시, Pull Request
+
+## 라이선스
+
+**Apache License 2.0** — [LICENSE](LICENSE), [NOTICE](NOTICE) 참고.
+
+---
+
+**DeukPack** — **득팩 IDL 파이프라인**으로 스펙부터 배포까지. 🚀

package/README.md

@@ -0,0 +1,182 @@
+# DeukPack
+
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+[![npm version](https://img.shields.io/npm/v/deukpack.svg)](https://www.npmjs.com/package/deukpack)
+
+**DeukPack** — one toolchain for specs, code, and data.  
+**Native `.deuk` IDL** plus **Protobuf, OpenAPI, JSON Schema, CSV**, and **legacy `.thrift`** in a **single fast pipeline** → **C#, C++, JavaScript**, registries, and **network-ready message layouts**.
+
+**v1.0.0 (npm / OSS)**: **IDL → multi-language codegen, CLI**, Binary/Compact/JSON wire. **Excel protocol and Excel add-in are distributed separately** — not part of core npm. See [DEUKPACK_V1_RELEASE_SCOPE.md](docs/DEUKPACK_V1_RELEASE_SCOPE.md) and [DEUKPACK_EXCEL_SEPARATE_DISTRIBUTION.md](docs/DEUKPACK_EXCEL_SEPARATE_DISTRIBUTION.md).
+
+---
+
+## At a glance
+
+| | What you get |
+|---|----------------|
+| **Interop** | **Protobuf-style / Binary·Compact** wire first; optional coexistence with legacy stacks. DeukPack is the **product**, not a fork of any single format. |
+| **Inputs** | **`.deuk` first-class**; **`.proto`, `.thrift`, OpenAPI, JSON Schema, CSV** in the **same build** — bring definitions without rewriting everything first. |
+| **Speed** | **Parse & codegen orders of magnitude faster** than typical single-tool IDL workflows at scale; leaner runtime serialize path. |
+| **Integration** | One AST → **multi-language outputs**, **SQLite DDL**, **schema JSON**, **IDL-driven registries** — fewer hand-maintained DTO layers. *(v1: table/Excel workflow out of scope.)* |
+| **Agents** | **Deterministic** codegen from `.deuk`, `.proto`, `.thrift`, or OpenAPI — specs in, typed code out. [AI pipeline →](docs/DEUKPACK_AI_PIPELINE_INTEGRATION.md) |
+| **Extensibility** | **CLI + pluggable generators** (C#, C++, TS, JS). *(v1: use CLI for production emit; library `generateCode` not fully wired.)* |
+
+---
+
+## Why DeukPack (impact)
+
+### 1. Compatibility & legacy migration
+
+- **One engine, many inputs**: **`.deuk`** alongside `.proto`, `.thrift`, OpenAPI — same AST, same codegen rules.
+- **Wire profiles**: **Protobuf-aligned** Binary/Compact first; coexistence with legacy services where needed.
+- **Structural CSV import** — treat wide or headered CSV as schema input where it fits your migration story.
+- **OpenAPI 3.x & JSON Schema** — REST-era contracts feed the same codegen and validation story as your game or backend IDL.
+
+### 2. Performance where it hurts
+
+Large trees of IDL files are where traditional compile steps hurt CI and local iteration. DeukPack is built for **high-throughput parse + multi-language emit** so **integration stays fast** as the spec grows.
+
+| Area | Typical gain (order of magnitude) |
+|------|-------------------------------------|
+| Parse + codegen (many files) | **~25–50×** faster vs classic compiler-style IDL flows on comparable workloads |
+| TS / JS emit | **~15–30×** faster |
+| Runtime serialize / deserialize | **~10×** faster (vs naive hand-rolled paths) |
+
+*See [benchmark notes](docs/DEUKPACK_VS_THRIFT_TEST_REPORT.md) for methodology.*
+
+### 3. Integration, not fragmentation
+
+- **Single source of truth** → **C#, C++, TypeScript, JavaScript** types and serializers together.
+- **Registries & protocol helpers** from IDL — **message / handler wiring** (e.g. msgId-style dispatch). *(Full Deuk table + Excel pipeline: not v1 public scope.)*
+- **Multiple on-the-wire styles** — **Binary**, **Compact**, **JSON** bridging where you need HTTP or debuggability alongside binary frames.
+- **SQLite** path from schema when you want **local / embedded** structured storage aligned with the same types.
+
+### 4. Built for AI & agent workflows
+
+- Agents produce or refine **OpenAPI, `.deuk`, `.proto`, or `.thrift`**; DeukPack turns them into **repeatable, reviewable code** — no ambiguous “rewrite the service by hand” step.
+- **CLI** (and parse-oriented library use) for **scripts, CI, or orchestration** — same as an agent invoking a compiler. *(v1 production codegen: prefer CLI.)*
+
+→ [DEUKPACK_AI_PIPELINE_INTEGRATION.md](docs/DEUKPACK_AI_PIPELINE_INTEGRATION.md)
+
+### 5. Major languages, one IDL story
+
+| Output | Role |
+|--------|------|
+| **C#** | .NET / Unity / servers — full runtime types, `GetSchema()`, protocol helpers. |
+| **C++** | Native services, performance-critical paths. |
+| **TypeScript / JavaScript** | BFFs, tools, editors, Node pipelines. |
+
+*Same struct names, same field IDs, same wire — across stacks.*
+
+### 6. API & generator extension
+
+- **Engine API** for parse → AST → emit; suitable for **custom pipelines** and **wrapped CLIs**.
+- **Code generators** as clear extension points — add languages or corporate templates without reimplementing the front-end.
+- **`deukpack` CLI** for zero-code integration in CI (`npx deukpack …`).
+
+---
+
+## Installation
+
+**Using only the npm package (no source clone)?** → [npm package usage](docs/NPM_PACKAGE.md).
+
+```bash
+npm install deukpack
+# or
+npm install ./deukpack-x.y.z.tgz   # from GitHub Release asset
+```
+
+Global CLI:
+
+```bash
+npm i -g deukpack
+deukpack --help
+```
+
+---
+
+## Simple usage (CLI)
+
+```bash
+# Install (or use npx without installing)
+npm install deukpack
+
+# Generate C# + C++ from one IDL (.deuk or .thrift)
+npx deukpack ./schema.deuk ./out --csharp --cpp
+
+# With include paths and protocol
+npx deukpack ./api.deuk ./gen -I ./includes --csharp --protocol binary
+
+# Pipeline (multiple jobs)
+npx deukpack --pipeline ./deukpack-pipeline.json
+```
+
+**Quick start by language**: [docs/QUICKSTART.md](docs/QUICKSTART.md) (C# · C++ · TypeScript · JavaScript).  
+**Detailed docs** (tutorials, IDL guide, API reference): **[deukpack.app](https://deukpack.app/)** → [Tutorial](https://deukpack.app/tutorial/) · [Reference](https://deukpack.app/reference/).
+
+Programmatic: `DeukPackEngine` parse / AST — see `src` and [docs](docs/). **Multi-language emit: use CLI** for v1 ([scope](docs/DEUKPACK_V1_RELEASE_SCOPE.md)).
+
+---
+
+## Documentation & links
+
+| | |
+|--|--|
+| **npm only (no clone)** | [docs/NPM_PACKAGE.md](docs/NPM_PACKAGE.md) — install, CLI, pipeline |
+| **Quick start (C# / C++ / TS / JS)** | [docs/QUICKSTART.md](docs/QUICKSTART.md) — run examples by language |
+| **Detailed docs (tutorial, API, guides)** | **[deukpack.app](https://deukpack.app/)** — IDL guide, C#/C++ guides, protocol, API reference |
+| **AI / agents** | [DEUKPACK_AI_PIPELINE_INTEGRATION.md](docs/DEUKPACK_AI_PIPELINE_INTEGRATION.md) |
+| **Korean intro** | [README.ko.md](README.ko.md) · [INTRO_DEUKPACK_CORE_ENGINE.md](docs/intro/INTRO_DEUKPACK_CORE_ENGINE.md) |
+| **Releases** | [RELEASING.md](RELEASING.md) — tags, GitHub Release tarballs |
+| **Full doc tree** | [docs/README.md](docs/README.md) |
+| **CI/CD · samples (C#/C++/TS/JS)** | [DEUKPACK_CI_CD_AND_DEV_PIPELINE.md](docs/DEUKPACK_CI_CD_AND_DEV_PIPELINE.md) · [examples/README.md](examples/README.md) |
+| **Starter kits** | [deukpack.app/starter-kits](https://deukpack.app/starter-kits/) (Unity, C++, network, TS, Java…) |
+
+**Product / site:** [deukpack.app](https://deukpack.app/) · **contact:** contact@deukpack.app
+
+---
+
+## Development
+
+```bash
+npm ci
+npm run build
+npm test
+npm run benchmark   # optional
+```
+
+---
+
+## Support development
+
+DeukPack stays **free and Apache-2.0** — you can ship products on it without a license fee. That only works if the project stays **maintained**: documentation, CI, compatibility fixes, faster parsers, new language targets, and time to review issues and PRs.
+
+If DeukPack **saves you CI minutes**, **replaces brittle hand-rolled serializers**, or **keeps your game/server stacks aligned on one IDL**, consider **chipping in**. A one-time or recurring tip **directly supports continued OSS work** on the engine, docs ([deukpack.app](https://deukpack.app/)), and releases — at any amount you’re comfortable with.
+
+**Personal PayPal (maintainer)** — tips go to the **individual account** tied to **`joygram@gmail.com`**, not a separate legal entity. That keeps overhead low and funds time on DeukPack directly.
+
+- **[Donate via PayPal](https://www.paypal.com/donate/?business=joygram%40gmail.com&currency_code=USD&item_name=DeukPack%20development)**  
+- If the button doesn’t open in your region, use PayPal **Send** to **`joygram@gmail.com`** (or your [PayPal.Me](https://www.paypal.com/paypalme/) link once you create one and we can add it here).
+
+This is **not** a tax-deductible charity donation unless you have a separate registered nonprofit; treat it as **support for the maintainer’s OSS work**.
+
+Not in a position to donate? **Star the repo**, **open clear issues**, **send PRs**, or **tell a team** that’s juggling Protobuf + Thrift + OpenAPI — that helps too.
+
+---
+
+## Contributing
+
+1. Fork → feature branch → PR.  
+2. See [RELEASING.md](RELEASING.md) for release layout.
+
+---
+
+## License
+
+**Apache License 2.0** — [LICENSE](LICENSE) · [NOTICE](NOTICE).
+
+---
+
+## Acknowledgments
+
+The broader IDL / OpenAPI / schema communities; DeukPack is a **standalone pipeline** (not an Apache Thrift subproject).

package/RELEASING.md

@@ -0,0 +1,71 @@
+# DeukPack OSS — 릴리즈·배포
+
+## v1.0.0 공개 스펙
+
+**1.0.0 태그·npm 공개 시 “지원한다”고 말할 수 있는 범위**는 [docs/DEUKPACK_V1_RELEASE_SCOPE.md](docs/DEUKPACK_V1_RELEASE_SCOPE.md)에 고정한다.  
+(테이블·Excel 연동은 v1 공약에서 제외; **Excel 프로토콜·Excel 애드인은 별도 배포** — [docs/DEUKPACK_EXCEL_SEPARATE_DISTRIBUTION.md](docs/DEUKPACK_EXCEL_SEPARATE_DISTRIBUTION.md).)
+
+## 사전 확인
+
+1. **`package.json`의 `repository` / `bugs` / `homepage`**  
+   실제 GitHub 경로로 바꾼다. OSS: `https://github.com/joygram/DeukPack` .
+
+2. **빌드·테스트 (로컬)**
+
+   ```bash
+   npm ci
+   npm run build
+   npm test
+   npm pack --dry-run
+   ```
+
+3. **CLI**
+
+   - 전역: `npm i -g deukpack` 후 `deukpack <args>`  
+   - 일회: `npx deukpack <args>`  
+   - 저장소 클론 시: `node scripts/build_deukpack.js` (동일 인자)
+
+## GitHub Release (바이너리 = npm tarball)
+
+태그를 푸시하면 **GitHub Actions → Release** 가 돌아가고, **`deukpack-x.y.z.tgz`** 가 릴리즈 자산으로 붙는다.
+
+```bash
+git tag v1.0.0
+git push origin v1.0.0
+```
+
+- 워크플로: `.github/workflows/release.yml`  
+- 태그 `v1.2.3` → `package.json` 버전을 `1.2.3`에 맞춘 뒤 `npm pack` 실행.
+
+사용자는 Release 페이지에서 `.tgz` 받아 `npm install ./deukpack-1.0.0.tgz` 로 설치 가능.
+
+## npm registry (선택)
+
+1. [npm](https://www.npmjs.com/) 계정·토큰 생성.  
+2. GitHub 저장소 **Settings → Secrets** 에 `NPM_TOKEN` 추가.  
+3. `.github/workflows/release.yml` 맨 아래 **Publish to npm** 단계 주석 해제.  
+4. 또는 로컬에서:
+
+   ```bash
+   npm run build && npm test
+   npm publish --access public
+   ```
+
+`prepublishOnly` 가 publish 직전에 다시 `build` 를 돌린다.
+
+## CI
+
+- **push / PR**: `.github/workflows/ci.yml` — Ubuntu·Windows, Node 18·20, `build` + `test` + **example IDL codegen smoke**.
+- 소비자 파이프라인·샘플: [docs/DEUKPACK_CI_CD_AND_DEV_PIPELINE.md](docs/DEUKPACK_CI_CD_AND_DEV_PIPELINE.md).
+
+## 공개(OSS) vs 내부 (GitLab 정본)
+
+| 구분 | 경로 | npm / 공개 GitHub |
+|------|------|-------------------|
+| **레거시 Thrift→.deuk** | `scripts/internal/legacy-migration/` | **제외** (`.npmignore`) |
+| **GPLAT 문건** | `docs/internal/` | **제외** |
+| **코어 CLI·코드젠** | `bin/`, `scripts/build_deukpack.js`, `dist/` | **포함** |
+
+GitHub 미러 동기화 시 `scripts/internal/`, `docs/internal/` 는 **올리지 않는다.**
+
+**형제 클론**: `i/DeukPack` · `i/DeukPackOSS` 구조일 때 동기화 → [docs/OSS_PUBLISH_SCOPE.md](docs/OSS_PUBLISH_SCOPE.md) §로컬 DeukPackOSS.

package/bin/deukpack.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * DeukPack CLI (npm global / npx).
+ * Forwards to scripts/build_deukpack.js after ensuring cwd-independent resolution.
+ */
+const path = require('path');
+const root = path.join(__dirname, '..');
+process.chdir(root);
+require(path.join(root, 'scripts', 'build_deukpack.js'));