devconfig-gen-singbox 2.0.0__tar.gz

devconfig_gen_singbox-2.0.0/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 2026 henryliu443
+
+   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.

devconfig_gen_singbox-2.0.0/PKG-INFO

@@ -0,0 +1,343 @@
+Metadata-Version: 2.4
+Name: devconfig_gen_singbox
+Version: 2.0.0
+Summary: Provider-based developer configuration generation engine and CLI
+Author-email: henryliu443 <henryliu443@gmail.com>
+License-Expression: Apache-2.0
+Keywords: configuration,json,yaml,code-generation,cli
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: yaml
+Requires-Dist: PyYAML>=5.1; extra == "yaml"
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: wheel; extra == "dev"
+Requires-Dist: PyYAML>=5.1; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs-material<10,>=9.5; extra == "docs"
+Dynamic: license-file
+
+# DevConfig-Gen_SingBox
+
+> **A sing-box domain implementation built on top of DevConfig-Gen.**
+> **构建在 `DevConfig-Gen` 之上的 sing-box 领域实现（child / fork）。**
+
+[![Version](https://img.shields.io/badge/version-2.0.0-blue.svg)](CHANGELOG.md)
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+![Python 3.8+](https://img.shields.io/badge/python-3.8%2B-blue.svg)
+![Tests](https://img.shields.io/badge/tests-136%20passing-brightgreen.svg)
+![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS-lightgrey.svg)
+
+**`DevConfig-Gen` 是一个以有限领域 Scope 为边界的确定性配置转换引擎。**
+**DevConfig-Gen is a deterministic configuration transformation engine built around bounded domain scopes.**
+
+本仓库定义其中一个 scope：有限的 **`singbox` 领域** —— 它的领域模型、校验规则、
+协议转换、配置变体与分享链接表示。`DevConfig-Gen` 提供中立的执行引擎与稳定的
+Provider 契约；本仓库提供 sing-box 专属的领域实现。
+
+```text
+DevConfig-Gen
+  中立引擎 · Provider 契约 · 执行流水线
+        │
+        ▼
+DevConfig-Gen_SingBox
+  sing-box 领域 · 校验 · 转换 · server/client 变体
+        │
+        ▼
+下游配置 / downstream configurations
+```
+
+**父仓库拥有引擎，子仓库拥有领域。**
+**The parent owns the engine. The child owns the domain.**
+
+## 快速开始 / Quick Start
+
+```bash
+git clone https://github.com/henryliu443/devconfig_gen_singbox.git
+cd devconfig_gen_singbox
+pip install -e ".[yaml]"
+devconfig-gen generate --provider singbox --input examples/singbox.yaml --output-dir dist
+```
+
+未安装时亦可直接通过源码运行：
+
+```bash
+git clone https://github.com/henryliu443/devconfig_gen_singbox.git
+cd devconfig_gen_singbox
+PYTHONPATH=src python3 -m devconfig_gen.cli generate --provider singbox --input examples/singbox.yaml --output-dir dist
+```
+
+## 本仓库是什么 / What this repository is
+
+> **Provider 是有限领域的实现，而不只是格式适配器。**
+> **A Provider is a bounded domain implementation, not merely a format adapter.**
+
+通用配置工具可以把一份文档过一遍 schema。领域 Provider 做得更多：它承载某一个
+系统的**知识**——概念、关系、约束、变体与产物——并把结构化 context 转换成经过
+校验、确定性的、系统专属的配置。
+
+本仓库**不是**「万能配置生成器」。它刻意选择一个 scope，并在其中把整条链路做完整：
+
+```text
+知识 → 约束 → 转换 → 校验 → 产物
+knowledge → constraints → transformation → validation → artifacts
+```
+
+## 领域 Scope：sing-box / Domain Scope: sing-box
+
+本仓库在 DevConfig-Gen 之上实现 **`singbox`** 领域 scope。
+
+```text
+结构化 context
+        │
+        ▼
+sing-box 领域模型
+        │
+        ▼
+校验 validation
+        │
+        ▼
+领域转换 transformation
+        │
+        ▼
+server / client 配置
+        │
+        ▼
+分享链接 share links
+```
+
+领域本身：
+
+```text
+SingBox Domain
+├── 协议 protocols           (anytls / tuic / hysteria2)
+├── 认证 authentication      (每个协议独立的 auth)
+├── TLS / Reality            (证书路径、REALITY 密钥对、decoy 握手)
+├── server / client 变体
+├── 路由 routing             (DNS 分流、route 规则、geo rule set)
+├── 网络/域名语义            (hosts、子域前缀)
+├── 凭据处理                 (凭据即显式输入)
+├── 分享链接表示
+└── 产物生成                 (server / client / links)
+```
+
+领域实现位于：
+
+```text
+src/devconfig_gen/providers/singbox/
+├── provider.py      # 分派 + 组装（不含任何变体字段名）
+├── schema.py        # Context Schema + 结构校验
+├── models.py        # 领域数据结构
+├── plugins/         # 每个协议变体一个模块
+│   ├── anytls.py
+│   ├── tuic.py
+│   └── hysteria2.py
+├── route.py         # DNS + Route 组装（读 data/rules.json）
+├── links.py         # 分享链接聚合
+└── data/rules.json  # 内嵌路由规则表
+```
+
+## 父/子架构 / Parent / Child Architecture
+
+```text
+DevConfig-Gen                         (父仓库 · 主)
+│  中立引擎
+│  Provider 契约
+│  执行流水线
+│
+└── DevConfig-Gen_SingBox             (子仓库 · 兵)
+       │  sing-box 领域知识
+       │  领域校验
+       │  协议转换
+       │  server / client 变体
+       │  分享链接生成
+       │
+       └── downstream (Automated-sing-box-json-generator —— 只读参考，退役中)
+```
+
+**父仓库拥有中立引擎与 Provider 契约；子仓库拥有领域。**
+**The parent owns the neutral engine and the provider contract; the child owns the domain.**
+
+- 权威方向为 **parent → child → downstream**。
+- 核心改动先在父仓库落地，再通过 `upstream` remote 合入本仓库。
+- 本仓库**绝不分叉或重写中立核心**（`engine` / `formats` / `validation`），只新增
+  `providers/singbox/`。
+
+## 领域模型与转换 / Domain Model & Transformations
+
+输入 context 按语义分区：`network`（协议 / 路由 / DNS）、`client`（客户端特有）、
+`options`（产物选项）。`schema.py` 负责归一化，`provider.py` 与各 plugin 负责校验，
+plugin 负责把每个协议转换为它在 sing-box 中的表示。
+
+```yaml
+network:
+  domain_root: example.com
+  subdomain_prefixes: {reality: a1b2c3d4, tuic: e5f6a7b8, hy2: c9d0e1f2}
+  tunnel_mode: proxy            # none | proxy | tun
+  protocols:
+    - type: anytls              # anytls | tuic | hysteria2
+      enabled: true
+      port: 23244
+      auth: {password: replace-me}
+      reality: {private_key: ..., public_key: ..., short_id: ...}
+    - type: tuic
+      enabled: true
+      port: 9443
+      auth: {uuid: ..., password: ...}
+      tls: {cert_path: /etc/.../tuic.crt, key_path: /etc/.../tuic.key}
+    - type: hysteria2
+      enabled: true
+      port: 7443
+      auth: {password: ..., obfs_password: ...}
+      tls: {cert_path: /etc/.../hy2.crt, key_path: /etc/.../hy2.key}
+  routing: {rules_source: embedded, geoip_cn: true}   # custom_rules 可覆盖/补充
+  dns: {direct_servers: [223.5.5.5, 119.29.29.29], remote_server: 1.1.1.1}
+client:
+  server_ip: 203.0.113.10       # TUN 排除路由
+  fingerprint: chrome
+options:
+  target: both                  # server | client | both
+  format: json                  # json | yaml
+```
+
+**隔离契约。** 每个协议的字段名与结构只存在于 `plugins/<variant>.py`。上游 sing-box
+变化时只改**一个 plugin 文件**；`schema.py` / `provider.py` / `route.py` 与产物契约
+保持不动，不做版本追逐。
+
+**独立 auth。** 每个协议各自携带 `auth`（及变体）块——凭据全部是显式输入，不生成、
+不存储、不读环境变量。
+
+## 生成产物 / Generated Artifacts
+
+| 产物 | 条件 | media type |
+| --- | --- | --- |
+| `sing-box.server.{json,yaml}` | `target != client` | `application/json` / `application/yaml` |
+| `sing-box.client.{json,yaml}` | `target != server` | `application/json` / `application/yaml` |
+| `sing-box-links.txt` | `target != server` | `text/plain` |
+
+`{fmt}` 由 `options.format` 决定，产物集合由 `options.target` 决定。
+
+## 输入示例 / Input Example
+
+```bash
+devconfig-gen generate --provider singbox --input examples/singbox.yaml --output-dir dist
+devconfig-gen validate --provider singbox --input examples/singbox.yaml
+devconfig-gen schema   --provider singbox
+```
+
+完整 context 见 [`examples/singbox.yaml`](examples/singbox.yaml)。
+
+## 校验与确定性 / Validation & Determinism
+
+- **路径感知诊断**：每个问题都以 dotted path 报告，例如
+  `network.protocols.0.auth.password`，并一次性收集全部问题。
+- **确定性输出**：JSON/YAML 均保持语义插入顺序；同一输入在多次运行、以及
+  CLI 与 Python API 两端都产出 byte-for-byte 一致的产物。
+- **零副作用**：Provider 不读环境变量、不写 state、不调子进程；凭据与子域前缀
+  全部显式输入。
+
+## 继承自 DevConfig-Gen 的引擎 / Inherited DevConfig-Gen Engine
+
+> 本仓库从 DevConfig-Gen 继承以下基础设施：
+
+- 确定性生成流水线（`engine.generate` / `generate_pipeline`）
+- 结构化校验与诊断（`Diagnostic` / `ValidationError`）
+- JSON/YAML 序列化（标准库 + 可选 PyYAML，内置子集解析器兜底）
+- 多源合并与 dotted-path 覆盖（`deep_merge`、`--set`）
+- CLI 与 Python API
+
+同时也继承中立的 Provider `custom` / `json` / `env`。本仓库在其之上新增领域
+Provider `singbox`：
+
+```bash
+devconfig-gen providers
+# custom / env / json / singbox
+```
+
+> **这些能力是基础设施。sing-box 领域始终由本子仓库负责。**
+> **These capabilities are infrastructure. The sing-box domain remains the responsibility of this child repository.**
+
+## 命令行与 Python API / CLI & Python API
+
+```bash
+# 生成 / 校验 / 查看 schema
+devconfig-gen generate --provider singbox --input examples/singbox.yaml --output-dir dist --format yaml
+devconfig-gen validate --provider singbox --input examples/singbox.yaml --json
+devconfig-gen schema   --provider singbox
+```
+
+```python
+from devconfig_gen import GenerationRequest, generate, generate_pipeline
+
+result = generate(
+    "singbox",
+    GenerationRequest(
+        context={
+            "network": {
+                "domain_root": "example.com",
+                "subdomain_prefixes": {"reality": "a1b2", "tuic": "c3d4", "hy2": "e5f6"},
+                "tunnel_mode": "proxy",
+                "protocols": [
+                    {
+                        "type": "anytls",
+                        "enabled": True,
+                        "auth": {"password": "..."},
+                        "reality": {"private_key": "...", "public_key": "...", "short_id": "..."},
+                    }
+                ],
+            },
+            "options": {"target": "server"},
+        },
+    ),
+)
+print([a.name for a in result.artifacts])   # ['sing-box.server.json']
+
+generate_pipeline(
+    "singbox",
+    input_path="examples/singbox.yaml",
+    output_dir="dist",
+    output_format="yaml",
+)
+```
+
+## 文档 / Documentation
+
+| 主题 | 本地 | 在线 |
+| --- | --- | --- |
+| 快速开始 | [`docs/getting-started.md`](docs/getting-started.md) | [getting-started](https://henryliu443.github.io/DevConfig-Gen/docs/getting-started/) |
+| CLI 参考 | [`docs/cli.md`](docs/cli.md) | [cli](https://henryliu443.github.io/DevConfig-Gen/docs/cli/) |
+| 输入合并与覆盖 | [`docs/input-and-merge.md`](docs/input-and-merge.md) | [input-and-merge](https://henryliu443.github.io/DevConfig-Gen/docs/input-and-merge/) |
+| 格式支持与产物 | [`docs/formats.md`](docs/formats.md) | [formats](https://henryliu443.github.io/DevConfig-Gen/docs/formats/) |
+| 校验与诊断 | [`docs/validation.md`](docs/validation.md) | [validation](https://henryliu443.github.io/DevConfig-Gen/docs/validation/) |
+| Provider 开发 | [`docs/providers.md`](docs/providers.md) | [providers](https://henryliu443.github.io/DevConfig-Gen/docs/providers/) |
+| Python API | [`docs/python-api.md`](docs/python-api.md) | [python-api](https://henryliu443.github.io/DevConfig-Gen/docs/python-api/) |
+| 架构总览 | [`ARCHITECTURE.md`](ARCHITECTURE.md) | — |
+| Provider 铁标准 | [`PROVIDER_STANDARD.md`](PROVIDER_STANDARD.md) | — |
+
+## 开发与测试 / Development & Testing
+
+```bash
+pip install -e ".[yaml]"
+PYTHONPATH=src python3 -m unittest discover -s tests -v
+
+# 可重复烟雾：全量单测 + API/CLI 逐字节一致
+python3 scripts/smoke_rounds.py 8
+```
+
+## 仓库关系 / Repository Relationship
+
+- 本仓库是 **子仓库（child / fork）**：`DevConfig-Gen_SingBox`。
+- **父仓库（parent / upstream）** 为
+  [`DevConfig-Gen`](https://github.com/henryliu443/DevConfig-Gen)，拥有中立核心与
+  [`PROVIDER_STANDARD.md`](PROVIDER_STANDARD.md)。
+- 领域 Provider（如 `providers/singbox/`）只存在于**本仓库**，**不回填父仓库**。
+
+权威方向为 **parent → child → downstream**。核心改动先在父仓库落地，再经 `upstream`
+remote 合入本仓库；不得分叉或改写中立核心。
+
+## 许可证 / License
+
+Apache-2.0。详见 [`LICENSE`](LICENSE)。