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.

