devconfig-gen-singbox 2.0.0__py3-none-any.whl

devconfig_gen/models.py

@@ -0,0 +1,135 @@
+"""Stable public data structures for configuration providers."""
+
+from dataclasses import dataclass, field
+from typing import Any, Mapping, Optional, Protocol, Sequence
+
+
+@dataclass(frozen=True)
+class GenerationRequest:
+    """Input to a provider; mappings are treated as read-only."""
+
+    context: Mapping[str, Any] = field(default_factory=dict)
+    options: Mapping[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class Diagnostic:
+    """A single, machine-readable validation message.
+
+    ``field`` is the dotted path to the offending value (for example
+    ``app.port``). ``message`` is the fully rendered, user-facing text
+    (for example ``port must be between 1 and 65535, got 99999``).
+    ``severity`` is ``"error"`` or ``"warning"``.
+    """
+
+    field: str
+    message: str
+    severity: str = "error"
+
+    def __str__(self) -> str:
+        return self.message
+
+    def as_dict(self) -> dict:
+        return {"field": self.field, "message": self.message, "severity": self.severity}
+
+
+@dataclass(frozen=True)
+class GeneratedArtifact:
+    name: str
+    content: Any
+    media_type: str = "application/json"
+
+
+@dataclass(frozen=True)
+class GenerationResult:
+    provider: str
+    artifacts: Sequence[GeneratedArtifact]
+    diagnostics: Sequence[Diagnostic] = field(default_factory=tuple)
+
+
+@dataclass(frozen=True)
+class ProviderField:
+    """Declarative description of one provider input field.
+
+    ``name`` is the dotted field path, e.g. ``app.port``. The remaining
+    attributes describe the value for documentation and future UI generation.
+
+    ``i18n`` optionally maps a locale (e.g. ``"zh"``) to translated
+    ``title``/``description`` strings, letting clients render localized
+    metadata without changing the canonical English defaults.
+    """
+
+    name: str
+    type: str = "string"
+    required: bool = False
+    default: Any = None
+    description: str = ""
+    choices: Sequence[str] = ()
+    minimum: Optional[float] = None
+    maximum: Optional[float] = None
+    title: str = ""
+    i18n: Mapping[str, Mapping[str, str]] = field(default_factory=dict)
+
+    def as_dict(self) -> dict:
+        data = {
+            "name": self.name,
+            "title": self.title or self.name,
+            "type": self.type,
+            "required": self.required,
+            "default": self.default,
+            "description": self.description,
+        }
+        if self.choices:
+            data["choices"] = list(self.choices)
+        if self.minimum is not None:
+            data["minimum"] = self.minimum
+        if self.maximum is not None:
+            data["maximum"] = self.maximum
+        if self.i18n:
+            data["i18n"] = {locale: dict(values) for locale, values in self.i18n.items()}
+        return data
+
+
+@dataclass(frozen=True)
+class ProviderStep:
+    """A declarative step grouping fields for a guided input flow.
+
+    ``i18n`` optionally maps a locale (e.g. ``"zh"``) to translated
+    ``title``/``description`` strings for localized clients.
+    """
+
+    id: str
+    title: str
+    description: str = ""
+    fields: Sequence[ProviderField] = ()
+    i18n: Mapping[str, Mapping[str, str]] = field(default_factory=dict)
+
+    def as_dict(self) -> dict:
+        data = {
+            "id": self.id,
+            "title": self.title,
+            "description": self.description,
+            "fields": [item.as_dict() for item in self.fields],
+        }
+        if self.i18n:
+            data["i18n"] = {locale: dict(values) for locale, values in self.i18n.items()}
+        return data
+
+
+class ConfigProvider(Protocol):
+    """Structural contract every provider implements.
+
+    ``validate`` returns rendered messages. Providers may additionally
+    implement ``diagnose`` (structured ``Diagnostic`` values) and
+    ``describe_schema`` / ``steps`` (declarative field metadata). Metadata
+    methods are optional, so a minimal provider only needs ``name``,
+    ``validate``, and ``generate``.
+    """
+
+    name: str
+
+    def generate(self, request: GenerationRequest) -> GenerationResult:
+        ...
+
+    def validate(self, request: GenerationRequest) -> Sequence[str]:
+        ...

devconfig_gen/providers/__init__.py

@@ -0,0 +1,8 @@
+"""Built-in configuration providers."""
+
+from .custom import CustomProvider
+from .env_provider import EnvProvider
+from .json_provider import JsonProvider
+from .singbox import SingBoxProvider
+
+__all__ = ["CustomProvider", "EnvProvider", "JsonProvider", "SingBoxProvider"]

devconfig_gen/providers/custom.py

@@ -0,0 +1,92 @@
+"""A generic, schema-free provider for arbitrary JSON/YAML documents.
+
+Unlike schema-bound providers that validate a fixed set of domain fields,
+``custom`` imposes no schema at all: any nesting of mappings, sequences and
+scalars is accepted, and callers can add, remove, or clear nodes at any level.
+It exists so users are not forced into a particular domain model.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Sequence
+
+from .. import formats
+from ..models import (
+    GeneratedArtifact,
+    GenerationRequest,
+    GenerationResult,
+    ProviderField,
+    ProviderStep,
+)
+from ..validation import ValidationError
+
+DEFAULT_ARTIFACT_STEM = "custom"
+
+
+class CustomProvider:
+    """Pass an arbitrary, freely-edited document through the pipeline."""
+
+    name = "custom"
+
+    steps: Sequence[ProviderStep] = (
+        ProviderStep(
+            id="document",
+            title="Custom document",
+            description="Build any nested JSON/YAML structure; add, remove, or clear nodes at any level.",
+            i18n={
+                "zh": {
+                    "title": "自定义文档",
+                    "description": "自由构建任意嵌套的 JSON/YAML 结构；任意层级都可增删或清空。",
+                }
+            },
+            fields=(
+                ProviderField(
+                    "document",
+                    type="tree",
+                    required=False,
+                    title="Document tree",
+                    description="Arbitrary nested document; keys and values are fully editable.",
+                    i18n={
+                        "zh": {
+                            "title": "文档结构",
+                            "description": "任意嵌套文档；键与值均可自由编辑。",
+                        }
+                    },
+                ),
+            ),
+        ),
+    )
+
+    def describe_schema(self) -> Sequence[ProviderStep]:
+        return self.steps
+
+    def _unwrap_context(self, context: Any) -> Any:
+        if isinstance(context, Mapping) and set(context.keys()) == {"document"}:
+            return context["document"]
+        return context
+
+    def validate(self, request: GenerationRequest):
+        return ()
+
+    def generate(self, request: GenerationRequest) -> GenerationResult:
+        errors = self.validate(request)
+        if errors:
+            raise ValidationError(errors)
+        fmt = formats.resolve_format(
+            request.options.get("format"),
+            name=request.options.get("name"),
+            default=formats.JSON,
+        )
+        suffix = "yaml" if fmt == formats.YAML else "json"
+        filename = request.options.get("name") or f"{DEFAULT_ARTIFACT_STEM}.{suffix}"
+        context = self._unwrap_context(request.context)
+        return GenerationResult(
+            provider=self.name,
+            artifacts=(
+                GeneratedArtifact(
+                    name=str(filename),
+                    content=context,
+                    media_type=formats.media_type_for(fmt),
+                ),
+            ),
+        )

devconfig_gen/providers/env_provider.py

@@ -0,0 +1,184 @@
+"""A second provider with real transformation: structured data -> ``.env``.
+
+Nested mappings are flattened into ``UPPER_SNAKE_CASE`` variables. This is a
+domain-neutral, non-JSON output format, which makes the provider contract's
+``media_type`` handling and multi-source merging easy to demonstrate.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Mapping, Optional, Sequence, Tuple
+
+from ..models import (
+    Diagnostic,
+    GeneratedArtifact,
+    GenerationRequest,
+    GenerationResult,
+    ProviderField,
+    ProviderStep,
+)
+from ..validation import ValidationError, is_mapping
+
+_SEGMENT_RE = re.compile(r"[^A-Za-z0-9]+")
+
+DEFAULT_ARTIFACT_NAME = ".env"
+ENV_MEDIA_TYPE = "text/plain"
+
+
+class EnvProvider:
+    """Flatten a structured mapping into a ``.env`` document."""
+
+    name = "env"
+
+    steps: Sequence[ProviderStep] = (
+        ProviderStep(
+            id="variables",
+            title="Environment variables",
+            description="Nested keys are joined with '_' and upper-cased.",
+            i18n={"zh": {"title": "环境变量", "description": "嵌套键用 '_' 连接并转为大写。"}},
+            fields=(
+                ProviderField(
+                    "variables",
+                    type="mapping",
+                    required=True,
+                    title="Variables",
+                    description="Variables; nested keys become UPPER_SNAKE_CASE names.",
+                    i18n={"zh": {"title": "变量", "description": "变量；嵌套键会转为 UPPER_SNAKE_CASE 名称。"}},
+                ),
+            ),
+        ),
+    )
+
+    def describe_schema(self) -> Sequence[ProviderStep]:
+        return self.steps
+
+    def diagnose(self, request: GenerationRequest) -> Sequence[Diagnostic]:
+        _, diagnostics = self._prepare(request)
+        return tuple(diagnostics)
+
+    def validate(self, request: GenerationRequest):
+        return tuple(item.message for item in self.diagnose(request))
+
+    def generate(self, request: GenerationRequest) -> GenerationResult:
+        pairs, diagnostics = self._prepare(request)
+        if diagnostics:
+            raise ValidationError(diagnostics)
+        text = "\n".join(f"{key}={value}" for key, value in pairs.items()) + "\n"
+        name = request.options.get("name") or DEFAULT_ARTIFACT_NAME
+        return GenerationResult(
+            provider=self.name,
+            artifacts=(
+                GeneratedArtifact(
+                    name=str(name),
+                    content=text,
+                    media_type=ENV_MEDIA_TYPE,
+                ),
+            ),
+        )
+
+    # -- normalization + validation -----------------------------------------
+
+    def _prepare(self, request: GenerationRequest) -> Tuple[dict, list]:
+        diagnostics: list = []
+        context = request.context
+        if not is_mapping(context):
+            return {}, [Diagnostic("variables", "variables must be a mapping at the document root")]
+
+        raw: Mapping = context
+        if set(context.keys()) == {"variables"} and is_mapping(context["variables"]):
+            raw = context["variables"]
+
+        if not raw:
+            return {}, [Diagnostic("variables", "variables must not be empty")]
+
+        pairs: dict = {}
+        origins: dict = {}
+        self._flatten(raw, (), pairs, origins, diagnostics)
+        return pairs, diagnostics
+
+    def _flatten(
+        self,
+        source: Mapping,
+        prefix: Tuple[str, ...],
+        pairs: dict,
+        origins: dict,
+        diagnostics: list,
+    ) -> None:
+        for key, value in source.items():
+            segment = self._segment(key, prefix, diagnostics)
+            if segment is None:
+                continue
+            path = prefix + (segment,)
+
+            if is_mapping(value):
+                if not value:
+                    env_key = "_".join(path)
+                    self._assign(env_key, "", path, pairs, origins, diagnostics)
+                else:
+                    self._flatten(value, path, pairs, origins, diagnostics)
+            elif isinstance(value, (list, tuple)):
+                if any(is_mapping(item) for item in value):
+                    diagnostics.append(
+                        Diagnostic(
+                            ".".join(path).lower(),
+                            f"{'.'.join(path).lower()} must not contain mappings",
+                        )
+                    )
+                    continue
+                rendered = ",".join(self._scalar_to_env(item) for item in value)
+                self._assign("_".join(path), rendered, path, pairs, origins, diagnostics)
+            elif isinstance(value, (dict, set)):
+                diagnostics.append(
+                    Diagnostic(
+                        ".".join(path).lower(),
+                        f"{'.'.join(path).lower()} has an unsupported value type",
+                    )
+                )
+            else:
+                self._assign(
+                    "_".join(path), self._scalar_to_env(value), path, pairs, origins, diagnostics
+                )
+
+    def _assign(
+        self,
+        env_key: str,
+        value: str,
+        path: Tuple[str, ...],
+        pairs: dict,
+        origins: dict,
+        diagnostics: list,
+    ) -> None:
+        origin = ".".join(path).lower()
+        if env_key in pairs and origins.get(env_key) != origin:
+            diagnostics.append(
+                Diagnostic(
+                    origin,
+                    f"'{env_key}' collides with '{origins[env_key]}' after normalization",
+                )
+            )
+            return
+        pairs[env_key] = value
+        origins[env_key] = origin
+
+    @staticmethod
+    def _segment(key: Any, prefix: Tuple[str, ...], diagnostics: list) -> Optional[str]:
+        segment = _SEGMENT_RE.sub("_", str(key)).strip("_").upper()
+        path = ".".join(prefix + (str(key),)).lower()
+        if not segment:
+            label = path or "<root>"
+            diagnostics.append(Diagnostic(path, f"{label} is not a valid variable name"))
+            return None
+        return segment
+
+    @staticmethod
+    def _scalar_to_env(value: Any) -> str:
+        if value is None:
+            return ""
+        if value is True:
+            return "true"
+        if value is False:
+            return "false"
+        if isinstance(value, (int, float)):
+            return str(value)
+        return str(value)

devconfig_gen/providers/json_provider.py

@@ -0,0 +1,84 @@
+"""Pass-through JSON/YAML provider.
+
+This provider performs no field-level transformation; it exists so callers can
+normalize or re-serialize an arbitrary structured document through the same
+pipeline as richer providers.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Sequence
+
+from .. import formats
+from ..models import (
+    GeneratedArtifact,
+    GenerationRequest,
+    GenerationResult,
+    ProviderField,
+    ProviderStep,
+)
+from ..validation import ValidationError
+
+
+class JsonProvider:
+    name = "json"
+
+    steps: Sequence[ProviderStep] = (
+        ProviderStep(
+            id="document",
+            title="Document",
+            description="Upload, paste, or edit an arbitrary JSON/YAML document to pass through unchanged.",
+            i18n={"zh": {"title": "文档", "description": "支持上传文件或直接粘贴/编辑任意 JSON/YAML 文档，原样透传与格式转换。"}},
+            fields=(
+                ProviderField(
+                    "document",
+                    type="document",
+                    required=True,
+                    title="Document Content",
+                    description="Upload a JSON/YAML file or paste/edit document content directly.",
+                    i18n={"zh": {"title": "文档内容", "description": "支持直接上传 JSON/YAML 文件，或直接粘贴/编辑文档内容。"}},
+                ),
+            ),
+        ),
+    )
+
+    def describe_schema(self) -> Sequence[ProviderStep]:
+        return self.steps
+
+    def _unwrap_context(self, context: Any) -> Any:
+        if (
+            isinstance(context, Mapping)
+            and set(context.keys()) == {"document"}
+            and isinstance(context["document"], Mapping)
+        ):
+            return context["document"]
+        return context
+
+    def validate(self, request: GenerationRequest):
+        context = self._unwrap_context(request.context)
+        if not isinstance(context, Mapping):
+            return ("document: expected a mapping at the root",)
+        return ()
+
+    def generate(self, request: GenerationRequest) -> GenerationResult:
+        errors = self.validate(request)
+        if errors:
+            raise ValidationError(errors)
+        fmt = formats.resolve_format(
+            request.options.get("format"),
+            name=request.options.get("name"),
+            default=formats.JSON,
+        )
+        suffix = "yaml" if fmt == formats.YAML else "json"
+        filename = request.options.get("name") or f"config.{suffix}"
+        context = self._unwrap_context(request.context)
+        return GenerationResult(
+            provider=self.name,
+            artifacts=(
+                GeneratedArtifact(
+                    name=str(filename),
+                    content=dict(context),
+                    media_type=formats.media_type_for(fmt),
+                ),
+            ),
+        )

devconfig_gen/providers/singbox/__init__.py

@@ -0,0 +1,9 @@
+"""The sing-box domain provider (child-repo integration fork).
+
+The neutral engine lives in the parent repository; this package owns all
+sing-box domain detail and follows ``PROVIDER_STANDARD.md``.
+"""
+
+from .provider import SingBoxProvider
+
+__all__ = ["SingBoxProvider"]

devconfig_gen/providers/singbox/data/rules.json

@@ -0,0 +1,97 @@
+{
+  "direct_exact": [
+    "blzddist1-a.akamaihd.net",
+    "download.jetbrains.com",
+    "file-igamecj.akamaized.net",
+    "identity.apple.com",
+    "images-cn.ssl-images-amazon.com",
+    "officecdn-microsoft-com.akamaized.net",
+    "speedtest.macpaw.com",
+    "www-cdn.icloud.com.akadns.net"
+  ],
+  "proxy_exact": [
+    "copilot.microsoft.com",
+    "copilot.bing.com",
+    "cdn.angruo.com",
+    "api.statsig.com",
+    "browser-intake-datadoghq.com",
+    "chat.openai.com.cdn.cloudflare.net",
+    "o33249.ingest.sentry.io",
+    "openai-api.arkoselabs.com",
+    "openaicom-api-bdcpf8c6d2e9atf6.z01.azurefd.net",
+    "openaicomproductionae4b.blob.core.windows.net",
+    "production-openaicom-storage.azureedge.net",
+    "static.cloudflareinsights.com",
+    "chatgpt.com",
+    "generativelanguage.googleapis.com",
+    "ai.google.dev"
+  ],
+  "direct_suffix": [
+    "aaplimg.com",
+    "apple-cloudkit.com",
+    "apple.co",
+    "apple.news",
+    "apple.com.cn",
+    "appstore.com",
+    "cdn-apple.com",
+    "icloud-content.com",
+    "icloud.com",
+    "icloud.com.cn",
+    "me.com",
+    "mzstatic.com",
+    "apple.com",
+    "itunes.com"
+  ],
+  "proxy_suffix": [
+    "apple-relay.akamaized.net",
+    "apple-relay.apple.com",
+    "apple-relay.cloudflare.com",
+    "apple-relay.fastly-edge.com",
+    "apple-relay.mask.apple-dns.net",
+    "m-team.cc",
+    "sciencemag.org",
+    "teamviewer.com",
+    "v2ex.com"
+  ],
+  "direct_keyword": [
+    "apple.com.edgekey.net"
+  ],
+  "proxy_keyword": [
+    "blogspot",
+    "pixiv",
+    "openaicom-api"
+  ],
+  "direct_cidr": [
+    "192.168.0.0/16",
+    "10.0.0.0/8",
+    "172.16.0.0/12",
+    "127.0.0.0/8",
+    "2403:300:a42::/48",
+    "2403:300:a51::/48",
+    "2620:149:a44::/48",
+    "2a01:b740:a42::/48"
+  ],
+  "proxy_cidr": [
+    "17.0.0.0/8",
+    "142.250.0.0/15",
+    "142.251.0.0/16",
+    "172.217.0.0/16",
+    "172.253.0.0/16",
+    "216.239.32.0/19",
+    "24.199.123.28/32",
+    "45.76.214.191/32",
+    "64.23.132.171/32",
+    "143.198.200.27/32",
+    "159.89.204.203/32",
+    "91.108.4.0/22",
+    "91.108.8.0/22",
+    "91.108.12.0/22",
+    "91.108.16.0/22",
+    "91.108.56.0/22",
+    "109.239.140.0/24",
+    "149.154.160.0/20",
+    "2001:B28:F23D::/48",
+    "2001:B28:F23F::/48",
+    "2001:67C:4E8::/48"
+  ]
+}

devconfig_gen/providers/singbox/links.py

@@ -0,0 +1,24 @@
+"""Share-link aggregation.
+
+Links are derived output: one line per enabled protocol, in input order, so the
+result is deterministic and stable.
+"""
+
+from __future__ import annotations
+
+from typing import Sequence
+
+from .models import BuildContext, ProtocolConfig
+from .plugins import get_plugin
+
+
+def build_links(protocols: Sequence[ProtocolConfig], ctx: BuildContext) -> str:
+    lines = []
+    for cfg in protocols:
+        plugin = get_plugin(cfg.type)
+        if plugin is None:
+            continue
+        lines.append(plugin.build_share_link(cfg, ctx))
+    if not lines:
+        return ""
+    return "\n".join(lines) + "\n"