wikiops 1.0.0__tar.gz

wikiops-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sebastian Granda Gallego
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

wikiops-1.0.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: wikiops
+Version: 1.0.0
+Summary: Extensible CLI to automate documentation in wiki platforms (Azure DevOps, Confluence, etc.) using Markdown. Built on a plugin and provider architecture, it enables generating, updating, and structuring documentation as code.
+License-Expression: MIT
+License-File: LICENSE
+Author: Sebastian Granda Gallego
+Author-email: sgg10.develop@gmail.com
+Requires-Python: >=3.10,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: httpx (>=0.28.1,<0.29.0)
+Requires-Dist: pydantic (>=2.12.5,<3.0.0)
+Requires-Dist: pyyaml (>=6.0.3,<7.0.0)
+Requires-Dist: typer (>=0.24.1,<0.25.0)
+Requires-Dist: wikiops-sdk (>=1.0.0,<2.0.0)
+Project-URL: Documentation, https://github.com/sgg10/wikiops/tree/main/docs
+Project-URL: Homepage, https://github.com/sgg10/wikiops
+Project-URL: Issues, https://github.com/sgg10/wikiops/issues
+Project-URL: Repository, https://github.com/sgg10/wikiops
+Description-Content-Type: text/markdown
+
+# wikiops
+
+`wikiops` is the host application and CLI runtime for the WikiOps ecosystem.
+
+It orchestrates documentation automation workflows around `wikiops-sdk` by loading configuration, discovering plugins and providers, building execution context, rendering previews, and applying planned changes.
+
+## What This Repository Contains
+
+- A command-line interface for WikiOps execution workflows.
+- The host orchestrator that coordinates planning and apply flows.
+- Runtime loading for plugins and providers through Python entry points.
+- YAML configuration loading for providers, profiles, refs, and plugin config.
+- Document loading, diff rendering, and apply delegation.
+- A built-in Azure DevOps Wiki provider.
+- A strict `pytest` suite with coverage enforcement.
+
+## What This Repository Does Not Contain
+
+- The public extension contracts and shared domain models.
+- A stable SDK-level API surface for plugins and providers.
+- Built-in documentation plugins.
+- Project-specific documentation business logic.
+
+Those concerns belong to `wikiops-sdk` and external plugin repositories.
+
+## Relationship To `wikiops-sdk`
+
+The WikiOps ecosystem is intentionally split across repositories:
+
+```text
+plugin -> sdk <- host
+provider -> sdk <- host
+```
+
+- `wikiops-sdk`
+  - defines the shared contracts, domain models, and compatibility helpers
+- `wikiops`
+  - orchestrates execution around those SDK contracts
+- plugins
+  - implement documentation planning logic
+- providers
+  - implement persistence and read-side infrastructure
+
+Canonical SDK documentation lives in the separate SDK repository:
+
+- [`wikiops-sdk README`](https://github.com/sgg10/wikiops-sdk/blob/main/README.md)
+- [`wikiops-sdk architecture`](https://github.com/sgg10/wikiops-sdk/blob/main/docs/architecture.md)
+- [`wikiops-sdk contracts API`](https://github.com/sgg10/wikiops-sdk/blob/main/docs/api/contracts.md)
+- [`wikiops-sdk domain API`](https://github.com/sgg10/wikiops-sdk/blob/main/docs/api/domain.md)
+
+## Quick Start
+
+Install the host and its runtime dependencies:
+
+```bash
+poetry install --with test
+```
+
+Inspect the currently available extensions:
+
+```bash
+poetry run wikiops plugins
+poetry run wikiops providers
+```
+
+The host currently ships with a built-in provider implementation:
+
+- `azure_devops_wiki`
+
+Plugins are expected to be installed separately through Python packages that expose the `wikiops.plugins` entry point group.
+
+### Example Configuration
+
+The host reads YAML configuration with provider definitions, profiles, refs, and plugin-specific settings.
+
+```yaml
+providers:
+  azdo:
+    type: azure_devops_wiki
+    organization: acme
+    project: engineering
+    wiki: platform
+
+profiles:
+  default:
+    provider: azdo
+    refs:
+      docs_root:
+        provider: azdo
+        kind: path
+        locator:
+          path: /Engineering/Teams
+    plugins:
+      acme.team-docs:
+        parent_alias: docs_root
+```
+
+### Example Input
+
+```yaml
+team_name: Platform
+```
+
+### Plan A Run
+
+Replace `acme.team-docs` with an installed plugin ID shown by `wikiops plugins`.
+
+```bash
+poetry run wikiops run \
+  --config wikiops.yaml \
+  --profile default \
+  --plugin acme.team-docs \
+  --input input.yaml
+```
+
+This prints:
+
+- the planned `ChangeSet` as JSON
+- a preview diff
+
+### Apply A Run
+
+```bash
+poetry run wikiops run \
+  --config wikiops.yaml \
+  --profile default \
+  --plugin acme.team-docs \
+  --input input.yaml \
+  --apply
+```
+
+On apply, the CLI also prints the provider `ApplyResult` and exits with code `1` if any operation failed.
+
+## Plugin Resources
+
+`wikiops` injects a `PluginResourceProvider` when loading plugin entry points.
+
+- Resource paths are relative to the plugin package root.
+- The host does not assume a fixed `resources/` directory.
+- If a plugin stores assets under `resources/`, it should request them as `resources/...`.
+- If a plugin already provides its own `resources` object, the host leaves it untouched.
+
+## Documentation Map
+
+Start here depending on your role:
+
+- New to the host: [`docs/getting-started.md`](docs/getting-started.md)
+- Need the host architecture: [`docs/architecture.md`](docs/architecture.md)
+- Need the runtime execution lifecycle: [`docs/execution-flow.md`](docs/execution-flow.md)
+- Need the YAML configuration model: [`docs/configuration.md`](docs/configuration.md)
+- Need the host/SDK boundary: [`docs/sdk-relationship.md`](docs/sdk-relationship.md)
+- Using the CLI: [`docs/guides/using-the-cli.md`](docs/guides/using-the-cli.md)
+- Building a plugin for this host: [`docs/guides/build-a-plugin.md`](docs/guides/build-a-plugin.md)
+- Building a provider for this host: [`docs/guides/build-a-provider.md`](docs/guides/build-a-provider.md)
+- Need module-level runtime reference: [`docs/reference/core-modules.md`](docs/reference/core-modules.md)
+- Need the built-in Azure DevOps provider reference: [`docs/reference/azure-devops-wiki.md`](docs/reference/azure-devops-wiki.md)
+- Need host internal boundaries: [`docs/reference/internal-boundaries.md`](docs/reference/internal-boundaries.md)
+
+The full host documentation index lives at [`docs/index.md`](docs/index.md).
+
+## Tests
+
+This repository ships with a strict `pytest` suite and coverage threshold.
+
+```bash
+poetry run pytest
+```
+
+The tests are also useful as executable examples of the current host behavior.
+

wikiops-1.0.0/README.md

@@ -0,0 +1,169 @@
+# wikiops
+
+`wikiops` is the host application and CLI runtime for the WikiOps ecosystem.
+
+It orchestrates documentation automation workflows around `wikiops-sdk` by loading configuration, discovering plugins and providers, building execution context, rendering previews, and applying planned changes.
+
+## What This Repository Contains
+
+- A command-line interface for WikiOps execution workflows.
+- The host orchestrator that coordinates planning and apply flows.
+- Runtime loading for plugins and providers through Python entry points.
+- YAML configuration loading for providers, profiles, refs, and plugin config.
+- Document loading, diff rendering, and apply delegation.
+- A built-in Azure DevOps Wiki provider.
+- A strict `pytest` suite with coverage enforcement.
+
+## What This Repository Does Not Contain
+
+- The public extension contracts and shared domain models.
+- A stable SDK-level API surface for plugins and providers.
+- Built-in documentation plugins.
+- Project-specific documentation business logic.
+
+Those concerns belong to `wikiops-sdk` and external plugin repositories.
+
+## Relationship To `wikiops-sdk`
+
+The WikiOps ecosystem is intentionally split across repositories:
+
+```text
+plugin -> sdk <- host
+provider -> sdk <- host
+```
+
+- `wikiops-sdk`
+  - defines the shared contracts, domain models, and compatibility helpers
+- `wikiops`
+  - orchestrates execution around those SDK contracts
+- plugins
+  - implement documentation planning logic
+- providers
+  - implement persistence and read-side infrastructure
+
+Canonical SDK documentation lives in the separate SDK repository:
+
+- [`wikiops-sdk README`](https://github.com/sgg10/wikiops-sdk/blob/main/README.md)
+- [`wikiops-sdk architecture`](https://github.com/sgg10/wikiops-sdk/blob/main/docs/architecture.md)
+- [`wikiops-sdk contracts API`](https://github.com/sgg10/wikiops-sdk/blob/main/docs/api/contracts.md)
+- [`wikiops-sdk domain API`](https://github.com/sgg10/wikiops-sdk/blob/main/docs/api/domain.md)
+
+## Quick Start
+
+Install the host and its runtime dependencies:
+
+```bash
+poetry install --with test
+```
+
+Inspect the currently available extensions:
+
+```bash
+poetry run wikiops plugins
+poetry run wikiops providers
+```
+
+The host currently ships with a built-in provider implementation:
+
+- `azure_devops_wiki`
+
+Plugins are expected to be installed separately through Python packages that expose the `wikiops.plugins` entry point group.
+
+### Example Configuration
+
+The host reads YAML configuration with provider definitions, profiles, refs, and plugin-specific settings.
+
+```yaml
+providers:
+  azdo:
+    type: azure_devops_wiki
+    organization: acme
+    project: engineering
+    wiki: platform
+
+profiles:
+  default:
+    provider: azdo
+    refs:
+      docs_root:
+        provider: azdo
+        kind: path
+        locator:
+          path: /Engineering/Teams
+    plugins:
+      acme.team-docs:
+        parent_alias: docs_root
+```
+
+### Example Input
+
+```yaml
+team_name: Platform
+```
+
+### Plan A Run
+
+Replace `acme.team-docs` with an installed plugin ID shown by `wikiops plugins`.
+
+```bash
+poetry run wikiops run \
+  --config wikiops.yaml \
+  --profile default \
+  --plugin acme.team-docs \
+  --input input.yaml
+```
+
+This prints:
+
+- the planned `ChangeSet` as JSON
+- a preview diff
+
+### Apply A Run
+
+```bash
+poetry run wikiops run \
+  --config wikiops.yaml \
+  --profile default \
+  --plugin acme.team-docs \
+  --input input.yaml \
+  --apply
+```
+
+On apply, the CLI also prints the provider `ApplyResult` and exits with code `1` if any operation failed.
+
+## Plugin Resources
+
+`wikiops` injects a `PluginResourceProvider` when loading plugin entry points.
+
+- Resource paths are relative to the plugin package root.
+- The host does not assume a fixed `resources/` directory.
+- If a plugin stores assets under `resources/`, it should request them as `resources/...`.
+- If a plugin already provides its own `resources` object, the host leaves it untouched.
+
+## Documentation Map
+
+Start here depending on your role:
+
+- New to the host: [`docs/getting-started.md`](docs/getting-started.md)
+- Need the host architecture: [`docs/architecture.md`](docs/architecture.md)
+- Need the runtime execution lifecycle: [`docs/execution-flow.md`](docs/execution-flow.md)
+- Need the YAML configuration model: [`docs/configuration.md`](docs/configuration.md)
+- Need the host/SDK boundary: [`docs/sdk-relationship.md`](docs/sdk-relationship.md)
+- Using the CLI: [`docs/guides/using-the-cli.md`](docs/guides/using-the-cli.md)
+- Building a plugin for this host: [`docs/guides/build-a-plugin.md`](docs/guides/build-a-plugin.md)
+- Building a provider for this host: [`docs/guides/build-a-provider.md`](docs/guides/build-a-provider.md)
+- Need module-level runtime reference: [`docs/reference/core-modules.md`](docs/reference/core-modules.md)
+- Need the built-in Azure DevOps provider reference: [`docs/reference/azure-devops-wiki.md`](docs/reference/azure-devops-wiki.md)
+- Need host internal boundaries: [`docs/reference/internal-boundaries.md`](docs/reference/internal-boundaries.md)
+
+The full host documentation index lives at [`docs/index.md`](docs/index.md).
+
+## Tests
+
+This repository ships with a strict `pytest` suite and coverage threshold.
+
+```bash
+poetry run pytest
+```
+
+The tests are also useful as executable examples of the current host behavior.

wikiops-1.0.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[project]
+name = "wikiops"
+version = "1.0.0"
+description = "Extensible CLI to automate documentation in wiki platforms (Azure DevOps, Confluence, etc.) using Markdown. Built on a plugin and provider architecture, it enables generating, updating, and structuring documentation as code."
+authors = [
+    {name = "Sebastian Granda Gallego",email = "sgg10.develop@gmail.com"}
+]
+license = "MIT"
+license-files = ["LICENSE"]
+readme = "README.md"
+requires-python = ">=3.10,<4.0"
+dependencies = [
+    "pydantic (>=2.12.5,<3.0.0)",
+    "typer (>=0.24.1,<0.25.0)",
+    "pyyaml (>=6.0.3,<7.0.0)",
+    "httpx (>=0.28.1,<0.29.0)",
+    "wikiops-sdk (>=1.0.0,<2.0.0)"
+]
+
+[project.urls]
+Homepage = "https://github.com/sgg10/wikiops"
+Repository = "https://github.com/sgg10/wikiops"
+Documentation = "https://github.com/sgg10/wikiops/tree/main/docs"
+Issues = "https://github.com/sgg10/wikiops/issues"
+
+[project.scripts]
+wikiops = "wikiops.cli.app:app"
+
+[project.entry-points."wikiops.providers"]
+azure_devops_wiki = "wikiops.providers.azure_devops:AzureDevOpsWikiProviderFactory"
+
+[tool.poetry]
+packages = [
+    {include = "wikiops", from = "src"}
+]
+
+[dependency-groups]
+test = [
+    "pytest (>=9.0.3,<10.0.0)",
+    "pytest-cov (>=6.0.0,<7.0.0)"
+]
+
+[tool.pytest.ini_options]
+addopts = "--strict-config --strict-markers -ra --cov=wikiops --cov-branch --cov-report=term-missing --cov-report=xml --cov-fail-under=90"
+testpaths = ["tests"]
+pythonpath = ["src"]
+xfail_strict = true
+required_plugins = ["pytest-cov"]
+
+[tool.coverage.run]
+branch = true
+source = ["wikiops"]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = false

wikiops-1.0.0/src/wikiops/__init__.py

@@ -0,0 +1,8 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("wikiops")
+except PackageNotFoundError:
+    __version__ = "0.0.0+local"
+
+all = ["__version__"]

wikiops-1.0.0/src/wikiops/cli/app.py

@@ -0,0 +1,81 @@
+from typing import Any
+from pathlib import Path
+
+import yaml
+import typer
+
+from wikiops.core.orchestrator import DefaultDocumentationOrchestrator
+
+app = typer.Typer(
+    help="WikiOps CLI - A tool for Markdown-based documentation automation."
+)
+
+
+def _load_yaml(path: str | Path) -> dict[str, Any]:
+    return yaml.safe_load(Path(path).read_text(encoding="utf-8")) or {}
+
+
+@app.command("plugins")
+def list_plugins() -> None:
+    """List discovered plugins."""
+
+    orchestrator = DefaultDocumentationOrchestrator()
+    for plugin in orchestrator.plugin_manager.list():
+        typer.echo(
+            f"- {plugin.manifest.plugin_id} :: {plugin.manifest.display_name} ({plugin.manifest.version})"
+        )
+
+
+@app.command("providers")
+def list_providers() -> None:
+    """List discovered provider types."""
+
+    orchestrator = DefaultDocumentationOrchestrator()
+    for provider_type in orchestrator.provider_manager.list_types():
+        typer.echo(f"- {provider_type}")
+
+
+@app.command("run")
+def run(
+    config: str = typer.Option(
+        ..., "--config", "-c", help="Path to the YAML config file."
+    ),
+    profile: str = typer.Option(
+        ..., "--profile", "-p", help="Profile name to execute."
+    ),
+    plugin: str = typer.Option(
+        ..., "--plugin", help="Plugin identifier or entry point name."
+    ),
+    input: str = typer.Option(
+        ..., "--input", "-i", help="Path to the YAML input file."
+    ),
+    apply: bool = typer.Option(False, "--apply", help="Persist the planned changes."),
+) -> None:
+    """Plan or apply a documentation use case."""
+
+    orchestrator = DefaultDocumentationOrchestrator()
+    raw_input = _load_yaml(input)
+
+    if apply:
+        change_set, apply_result, diff = orchestrator.apply_from_file(
+            config, profile, plugin, raw_input
+        )
+        typer.echo("=== CHANGESET ===")
+        typer.echo(change_set.model_dump_json(indent=2))
+        typer.echo("\n=== DIFF ===")
+        typer.echo(diff or "(No diff available)")
+        typer.echo("\n=== APPLY RESULT ===")
+        typer.echo(apply_result.model_dump_json(indent=2))
+        raise typer.Exit(code=1 if apply_result.has_failures() else 0)
+
+    _, _, change_set, diff = orchestrator.plan_from_file(
+        config, profile, plugin, raw_input, dry_run=True
+    )
+    typer.echo("=== CHANGESET ===")
+    typer.echo(change_set.model_dump_json(indent=2))
+    typer.echo("\n=== DIFF ===")
+    typer.echo(diff or "(No diff generated)")
+
+
+if __name__ == "__main__":
+    app()

wikiops-1.0.0/src/wikiops/core/apply_engine.py

@@ -0,0 +1,10 @@
+from wikiops_sdk.contracts import DocumentProvider
+from wikiops_sdk.domain import ApplyResult, ChangeSet
+
+
+class ApplyEngine:
+    """Persists a planned change set through a provider."""
+
+    def apply(self, provider: DocumentProvider, change_set: ChangeSet) -> ApplyResult:
+        """Applies the given change set using the provided document provider."""
+        return provider.apply_changes(change_set)

wikiops-1.0.0/src/wikiops/core/config_loader.py

@@ -0,0 +1,98 @@
+from pathlib import Path
+from typing import Any, Dict, Union
+
+import yaml
+from pydantic import BaseModel, Field
+
+from wikiops.core.exceptions import ConfigurationError
+from wikiops_sdk.domain import DocumentRef
+
+
+class ProviderDefinition(BaseModel):
+    """Provider configuration entry from the YAML file."""
+
+    type: str
+    settings: Dict[str, Any] = Field(default_factory=dict)
+
+
+class ProfileDefinition(BaseModel):
+    """Execution profile entry from the YAML file."""
+
+    provider: str
+    refs: Dict[str, DocumentRef] = Field(default_factory=dict)
+    plugins: Dict[str, Dict[str, Any]] = Field(default_factory=dict)
+
+
+class AppConfig(BaseModel):
+    """Top-level application configuration."""
+
+    providers: Dict[str, ProviderDefinition] = Field(default_factory=dict)
+    profiles: Dict[str, ProfileDefinition] = Field(default_factory=dict)
+
+
+class ConfigLoader:
+    """Loads and validates YAML application configuration."""
+
+    def _prepare_providers(
+        self, raw_providers: Dict[str, Any]
+    ) -> Dict[str, ProviderDefinition]:
+        """Validates and transforms raw provider definitions into structured ProviderDefinition instances."""
+        providers = {}
+
+        for name, provider in raw_providers.items():
+            provider_type = provider.get("type")
+
+            if not provider_type:
+                raise ConfigurationError(f"Provider '{name}' is missing 'type' field.")
+
+            settings = {k: v for k, v in provider.items() if k != "type"}
+            settings.setdefault("provider_name", name)
+
+            providers[name] = ProviderDefinition(type=provider_type, settings=settings)
+
+        return providers
+
+    def _prepare_profiles(
+        self, raw_profiles: Dict[str, Any]
+    ) -> Dict[str, ProfileDefinition]:
+        """Validates and transforms raw profile definitions into structured ProfileDefinition instances."""
+        profiles = {}
+
+        for name, profile in raw_profiles.items():
+            provider_name = profile.get("provider")
+
+            if not provider_name:
+                raise ConfigurationError(
+                    f"Profile '{name}' is missing 'provider' field."
+                )
+
+            refs_raw = profile.get("refs", {})
+            plugins_raw = profile.get("plugins", {})
+
+            refs = {
+                alias: DocumentRef.model_validate(ref_raw)
+                for alias, ref_raw in refs_raw.items()
+            }
+            profiles[name] = ProfileDefinition(
+                provider=provider_name, refs=refs, plugins=plugins_raw
+            )
+
+        return profiles
+
+    def load(self, path: Union[str, Path]) -> AppConfig:
+        config_path = Path(path)
+
+        if not config_path.exists():
+            raise ConfigurationError(f"Configuration file not found: {config_path}")
+
+        if not config_path.is_file():
+            raise ConfigurationError(f"Configuration path is not a file: {config_path}")
+
+        raw = yaml.safe_load(config_path.read_text(encoding="utf-8")) or {}
+        providers_section = raw.get("providers", {})
+        profiles_section = raw.get("profiles", {})
+
+        providers = self._prepare_providers(providers_section)
+        profiles = self._prepare_profiles(profiles_section)
+
+        return AppConfig(providers=providers, profiles=profiles)

wikiops-1.0.0/src/wikiops/core/diff_engine.py

@@ -0,0 +1,42 @@
+from typing import Dict, List
+from difflib import unified_diff
+
+from wikiops_sdk.domain import ChangeSet, UpdateDocumentOperation
+
+
+class DiffEngine:
+    """Builds preview diffs for update operations."""
+
+    @staticmethod
+    def _find_document(documents: Dict[str, object], ref: object):
+        for document in documents.values():
+            if getattr(document, "ref", None) == ref:
+                return document
+        return None
+
+    def render(self, documents: Dict[str, object], change_set: ChangeSet) -> str:
+        chunks: List[str] = []
+        for op in change_set.operations:
+            if not isinstance(op, UpdateDocumentOperation):
+                chunks.append(
+                    f"# Operation {op.operation_id}\n"
+                    f"Type: {op.operation}\n"
+                    f"This operation creates a new content and has no line diff against an existing document."
+                )
+                continue
+
+            current_doc = self._find_document(documents, op.ref)
+            current_lines = (current_doc.content if current_doc else "").splitlines()
+            new_lines = op.new_content.splitlines()
+
+            diff = unified_diff(
+                current_lines,
+                new_lines,
+                fromfile="current",
+                tofile="planned",
+                lineterm="",
+            )
+
+            chunks.append(f"# Operation {op.operation_id}\n" + "\n".join(diff))
+
+        return "\n\n".join(chunks)