devconfig-gen 1.0.0__py3-none-any.whl

devconfig_gen/__init__.py

@@ -0,0 +1,90 @@
+"""Provider-based developer configuration generation.
+
+The core package exposes the provider pipeline only. The interactive terminal
+wizard and the local web studio are imported lazily so that ``import
+devconfig_gen`` stays lightweight and free of any server or browser imports.
+"""
+
+from .engine import (
+    build_request,
+    describe_provider,
+    diagnose_request,
+    generate,
+    generate_from_file,
+    generate_pipeline,
+    validate_request,
+)
+from .formats import (
+    FormatError,
+    coerce_scalar,
+    deep_merge,
+    dump_data,
+    dump_file,
+    dumps,
+    load_data,
+    load_file,
+    loads,
+)
+from .models import (
+    ConfigProvider,
+    Diagnostic,
+    GeneratedArtifact,
+    GenerationRequest,
+    GenerationResult,
+    ProviderField,
+    ProviderStep,
+)
+from .registry import ProviderRegistry, default_registry
+from .validation import ValidationError
+
+__all__ = [
+    "ConfigProvider",
+    "Diagnostic",
+    "FormatError",
+    "GeneratedArtifact",
+    "GenerationRequest",
+    "GenerationResult",
+    "ProviderField",
+    "ProviderRegistry",
+    "ProviderStep",
+    "ValidationError",
+    "build_request",
+    "coerce_scalar",
+    "deep_merge",
+    "default_registry",
+    "describe_provider",
+    "diagnose_request",
+    "dump_data",
+    "dump_file",
+    "dumps",
+    "generate",
+    "generate_from_file",
+    "generate_pipeline",
+    "load_data",
+    "load_file",
+    "loads",
+    "run_interactive_wizard",
+    "run_web_ui",
+    "validate_request",
+]
+__version__ = "0.3.0"
+
+_LAZY_EXPORTS = {
+    "run_interactive_wizard": ("interactive", "run_interactive_wizard"),
+    "run_web_ui": ("web_ui", "run_web_ui"),
+}
+
+
+def __getattr__(name):
+    """Import the optional UI entry points on first use (PEP 562)."""
+
+    try:
+        module_name, attribute = _LAZY_EXPORTS[name]
+    except KeyError:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from None
+    import importlib
+
+    module = importlib.import_module(f".{module_name}", __name__)
+    value = getattr(module, attribute)
+    globals()[name] = value
+    return value

devconfig_gen/cli.py

@@ -0,0 +1,213 @@
+"""Command-line interface for the generic generation engine."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import formats
+from .engine import describe_provider, diagnose_request, generate_pipeline
+from .registry import default_registry
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="devconfig-gen",
+        description="Generate and validate structured JSON/YAML configuration.",
+    )
+    parser.add_argument("--version", action="version", version="%(prog)s 1.0.0")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    providers = sub.add_parser("providers", help="List available providers")
+    providers.set_defaults(handler=_list_providers)
+
+    generate_cmd = sub.add_parser("generate", help="Generate configuration from structured input")
+    generate_cmd.add_argument("--provider", default="json", help="Provider name (default: json)")
+    generate_cmd.add_argument(
+        "--input",
+        required=True,
+        action="append",
+        type=Path,
+        help="JSON or YAML input file (repeatable; merged left to right)",
+    )
+    generate_cmd.add_argument("--output-dir", required=True, type=Path, help="Directory for artifacts")
+    generate_cmd.add_argument("--format", choices=("json", "yaml"), help="Output format")
+    generate_cmd.add_argument("--name", help="Output file name (default: provider-specific)")
+    generate_cmd.add_argument(
+        "--set",
+        action="append",
+        default=[],
+        dest="overrides",
+        metavar="KEY=VALUE",
+        help="Override a value by dotted path, e.g. app.port=9090 (repeatable)",
+    )
+    generate_cmd.set_defaults(handler=_generate)
+
+    validate_cmd = sub.add_parser("validate", help="Validate input without generating output")
+    validate_cmd.add_argument("--provider", default="json", help="Provider name (default: json)")
+    validate_cmd.add_argument(
+        "--input",
+        required=True,
+        action="append",
+        type=Path,
+        help="JSON or YAML input file (repeatable; merged left to right)",
+    )
+    validate_cmd.add_argument("--format", choices=("json", "yaml"), help="Input format override")
+    validate_cmd.add_argument(
+        "--set",
+        action="append",
+        default=[],
+        dest="overrides",
+        metavar="KEY=VALUE",
+        help="Override a value by dotted path before validating (repeatable)",
+    )
+    validate_cmd.add_argument(
+        "--json", action="store_true", help="Print structured diagnostics as JSON"
+    )
+    validate_cmd.set_defaults(handler=_validate)
+
+    schema_cmd = sub.add_parser(
+        "schema", help="Print a provider's declarative field schema as JSON"
+    )
+    schema_cmd.add_argument("--provider", default="json", help="Provider name (default: json)")
+    schema_cmd.set_defaults(handler=_schema)
+
+    init_cmd = sub.add_parser(
+        "init",
+        help="Run interactive terminal wizard to create configuration",
+        description="Run interactive terminal wizard to create configuration.",
+    )
+    init_cmd.add_argument("--provider", default="custom", help="Provider name (default: custom)")
+    init_cmd.add_argument("--input", type=Path, help="Optional existing config file to pre-fill wizard")
+    init_cmd.add_argument("--output-dir", default=".", type=Path, help="Directory for generated artifact")
+    init_cmd.add_argument("--format", choices=("json", "yaml"), help="Output format override")
+    init_cmd.set_defaults(handler=_init)
+
+    ui_cmd = sub.add_parser(
+        "ui",
+        help="Launch local configuration studio WebUI",
+        description="Launch local configuration studio WebUI.",
+    )
+    ui_cmd.add_argument("--host", default="127.0.0.1", help="Host address (default: 127.0.0.1)")
+    ui_cmd.add_argument("--port", default=8848, type=int, help="Port to bind (default: 8848)")
+    ui_cmd.add_argument("--no-browser", action="store_true", help="Do not automatically open browser")
+    ui_cmd.add_argument(
+        "--workspace",
+        default=None,
+        help="Directory the studio may export into (default: current directory)",
+    )
+    ui_cmd.set_defaults(handler=_ui)
+
+    return parser
+
+
+def _list_providers(args) -> int:
+    for name in default_registry.names():
+        print(name)
+    return 0
+
+
+def _parse_overrides(pairs) -> dict:
+    overrides = {}
+    for item in pairs or ():
+        if "=" not in item:
+            raise ValueError(f"--set expects KEY=VALUE, got {item!r}")
+        key, value = item.split("=", 1)
+        key = key.strip()
+        if not key:
+            raise ValueError(f"--set expects a non-empty key, got {item!r}")
+        overrides[key] = formats.coerce_scalar(value)
+    return overrides
+
+
+def _generate(args) -> int:
+    options = {"name": args.name} if args.name else None
+    try:
+        overrides = _parse_overrides(args.overrides)
+        result = generate_pipeline(
+            args.provider,
+            input_path=[str(path) for path in args.input],
+            output_dir=str(args.output_dir),
+            output_format=args.format,
+            options=options,
+            overrides=overrides,
+        )
+    except (OSError, formats.FormatError, ValueError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    for artifact in result.artifacts:
+        print(f"generated {args.output_dir / artifact.name}")
+    return 0
+
+
+def _validate(args) -> int:
+    try:
+        overrides = _parse_overrides(args.overrides)
+        diagnostics = diagnose_request(
+            args.provider,
+            input_path=[str(path) for path in args.input],
+            input_format=args.format,
+            overrides=overrides,
+        )
+    except (OSError, formats.FormatError, ValueError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+    if args.json:
+        print(json.dumps([item.as_dict() for item in diagnostics], indent=2))
+
+    errors = [item for item in diagnostics if item.severity == "error"]
+    if errors:
+        if not args.json:
+            for item in errors:
+                print(f"invalid: {item.message}", file=sys.stderr)
+        return 1
+    if not args.json:
+        sources = ", ".join(str(path) for path in args.input)
+        print(f"{sources}: valid")
+    return 0
+
+
+def _schema(args) -> int:
+    try:
+        steps = describe_provider(args.provider)
+    except (OSError, formats.FormatError, ValueError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    print(json.dumps([step.as_dict() for step in steps], indent=2))
+    return 0
+
+
+def _init(args) -> int:
+    from .interactive import run_interactive_wizard
+
+    input_path = str(args.input) if args.input else None
+    return run_interactive_wizard(
+        args.provider,
+        input_path=input_path,
+        output_dir=str(args.output_dir),
+        output_format=args.format,
+    )
+
+
+def _ui(args) -> int:
+    from .web_ui import run_web_ui
+
+    run_web_ui(
+        host=args.host,
+        port=args.port,
+        open_browser=not args.no_browser,
+        workspace_root=args.workspace,
+    )
+    return 0
+
+
+def main(argv=None) -> int:
+    args = build_parser().parse_args(argv)
+    return args.handler(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

devconfig_gen/engine.py

@@ -0,0 +1,217 @@
+"""Provider-independent generation orchestration.
+
+Every entry point in this module funnels into :func:`generate`, so the CLI and
+the Python API share one validation, generation, and persistence path.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Mapping, Optional, Sequence, Union
+
+from . import formats
+from .models import (
+    Diagnostic,
+    GeneratedArtifact,
+    GenerationRequest,
+    GenerationResult,
+    ProviderStep,
+)
+from .registry import ProviderRegistry, default_registry
+
+
+def generate(
+    provider: str,
+    request: GenerationRequest,
+    registry: Optional[ProviderRegistry] = None,
+    output_dir: Optional[str] = None,
+) -> GenerationResult:
+    """Validate, generate, and optionally persist provider artifacts."""
+
+    selected = (registry or default_registry).get(provider)
+    errors = tuple(selected.validate(request))
+    if errors:
+        raise ValueError("; ".join(errors))
+    result = selected.generate(request)
+    if output_dir is not None:
+        _persist(result, output_dir)
+    return result
+
+
+def _set_nested(target: dict, path: str, value: Any) -> None:
+    parts = path.split(".")
+    current = target
+    for part in parts[:-1]:
+        if part not in current or not isinstance(current[part], dict):
+            current[part] = {}
+        current = current[part]
+    current[parts[-1]] = value
+
+
+def build_request(
+    *,
+    context: Any = None,
+    input_path: Optional[Union[str, Path, Sequence[Any]]] = None,
+    options: Optional[Mapping[str, Any]] = None,
+    input_format: Optional[str] = None,
+    overrides: Optional[Mapping[str, Any]] = None,
+) -> GenerationRequest:
+    """Build a request from an in-memory context and/or multiple input files with overrides."""
+
+    merged_context = dict(context) if isinstance(context, Mapping) else (context or {})
+    if input_path is not None:
+        if isinstance(input_path, (str, Path)):
+            paths = [input_path]
+        elif isinstance(input_path, Sequence):
+            paths = list(input_path)
+        else:
+            paths = [input_path]
+
+        for p in paths:
+            loaded = formats.load_file(p, input_format)
+            if isinstance(merged_context, Mapping) and isinstance(loaded, Mapping):
+                merged_context = formats.deep_merge(merged_context, loaded)
+            else:
+                merged_context = loaded
+
+    if overrides:
+        if not isinstance(merged_context, dict):
+            merged_context = {}
+        for key, val in overrides.items():
+            _set_nested(merged_context, key, val)
+
+    return GenerationRequest(context=merged_context, options=dict(options or {}))
+
+
+def generate_pipeline(
+    provider: str,
+    *,
+    context: Any = None,
+    input_path: Optional[Union[str, Path, Sequence[Any]]] = None,
+    options: Optional[Mapping[str, Any]] = None,
+    output_dir: Optional[str] = None,
+    output_format: Optional[str] = None,
+    input_format: Optional[str] = None,
+    registry: Optional[ProviderRegistry] = None,
+    overrides: Optional[Mapping[str, Any]] = None,
+) -> GenerationResult:
+    """Run the full pipeline from multi-source inputs to optional output."""
+
+    merged = dict(options or {})
+    if output_format is not None:
+        merged["format"] = output_format
+    request = build_request(
+        context=context,
+        input_path=input_path,
+        options=merged,
+        input_format=input_format,
+        overrides=overrides,
+    )
+    return generate(provider, request, registry=registry, output_dir=output_dir)
+
+
+def generate_from_file(
+    provider: str,
+    input_path: str,
+    *,
+    output_dir: Optional[str] = None,
+    output_format: Optional[str] = None,
+    options: Optional[Mapping[str, Any]] = None,
+    registry: Optional[ProviderRegistry] = None,
+) -> GenerationResult:
+    """Convenience wrapper around :func:`generate_pipeline` for file input."""
+
+    return generate_pipeline(
+        provider,
+        input_path=input_path,
+        output_dir=output_dir,
+        output_format=output_format,
+        options=options,
+        registry=registry,
+    )
+
+
+def validate_request(
+    provider: str,
+    *,
+    context: Any = None,
+    input_path: Optional[Union[str, Path, Sequence[Any]]] = None,
+    options: Optional[Mapping[str, Any]] = None,
+    input_format: Optional[str] = None,
+    overrides: Optional[Mapping[str, Any]] = None,
+    registry: Optional[ProviderRegistry] = None,
+) -> Sequence[str]:
+    """Return provider validation errors without generating or writing output."""
+
+    request = build_request(
+        context=context,
+        input_path=input_path,
+        options=options,
+        input_format=input_format,
+        overrides=overrides,
+    )
+    selected = (registry or default_registry).get(provider)
+    return tuple(selected.validate(request))
+
+
+def diagnose_request(
+    provider: str,
+    *,
+    context: Any = None,
+    input_path: Optional[Union[str, Path, Sequence[Any]]] = None,
+    options: Optional[Mapping[str, Any]] = None,
+    input_format: Optional[str] = None,
+    overrides: Optional[Mapping[str, Any]] = None,
+    registry: Optional[ProviderRegistry] = None,
+) -> Sequence[Diagnostic]:
+    """Return structured diagnostics without generating or writing output."""
+
+    request = build_request(
+        context=context,
+        input_path=input_path,
+        options=options,
+        input_format=input_format,
+        overrides=overrides,
+    )
+    selected = (registry or default_registry).get(provider)
+    diagnose = getattr(selected, "diagnose", None)
+    if callable(diagnose):
+        return tuple(diagnose(request))
+    return tuple(Diagnostic(field="", message=message) for message in selected.validate(request))
+
+
+def describe_provider(
+    provider: str,
+    registry: Optional[ProviderRegistry] = None,
+) -> Sequence[ProviderStep]:
+    """Return a provider's declarative step/field metadata."""
+
+    selected = (registry or default_registry).get(provider)
+    describe = getattr(selected, "describe_schema", None)
+    if callable(describe):
+        return tuple(describe())
+    return tuple(getattr(selected, "steps", ()))
+
+
+def _persist(result: GenerationResult, output_dir: str) -> None:
+    destination = Path(output_dir)
+    destination.mkdir(parents=True, exist_ok=True)
+    for artifact in result.artifacts:
+        relative_name = Path(artifact.name)
+        if relative_name.is_absolute() or ".." in relative_name.parts:
+            raise ValueError(f"artifact name escapes output directory: {artifact.name!r}")
+        path = destination / relative_name
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(_serialize_artifact(artifact), encoding="utf-8")
+
+
+def _serialize_artifact(artifact: GeneratedArtifact) -> str:
+    if isinstance(artifact.content, str):
+        return artifact.content
+    try:
+        fmt = formats.format_from_media_type(artifact.media_type)
+    except formats.FormatError as exc:
+        raise ValueError(
+            f"cannot persist media type {artifact.media_type!r} for {artifact.name!r}"
+        ) from exc
+    return formats.dumps(artifact.content, fmt)