infralink 0.6.15__tar.gz

infralink-0.6.15/.gitignore

@@ -0,0 +1,50 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Testing
+.coverage
+.pytest_cache/
+htmlcov/
+.tox/
+.nox/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Local working files (prod analysis, generated output)
+local/
+output/
+
+.worktrees/

infralink-0.6.15/BACKLOG.md

@@ -0,0 +1,51 @@
+# Infralink Product Backlog
+
+Current package version: `0.5.6`.
+
+## Completed Foundation
+
+- [x] Typed registry, services, roles, and edges.
+- [x] Resolver endpoints and safe connection templates.
+- [x] TCP, HTTP, and Redis health checks.
+- [x] Stable CLI envelopes, bounded outputs, cursors, and exit codes.
+- [x] Bounded topology and application queries.
+- [x] Deterministic diagram and documentation artifacts.
+- [x] Opaque secret values and declared-reference inventory.
+- [x] Optional read-only hosted BWS adapter and metadata audit.
+- [x] Strict typing, Ruff, branch coverage, schema, and package gates.
+- [x] Deterministic public-data boundary and package policy.
+- [x] Manual main-bound Woodpecker release contract.
+- [x] Release candidate, publisher request, and attestation contracts through v3.
+- [x] Offline observation contracts, diagnostics, readiness suites, and profile-scoped operations views.
+
+## Current Next Work
+
+- [ ] Keep contributor and agent onboarding docs current as command surfaces change.
+- [ ] Add optional private compatibility diagnostics in Woodpecker without weakening public CI.
+- [ ] Run canary validation against sanitized topology fixtures.
+- [ ] Migrate consumers from legacy URL helpers to connection templates.
+- [ ] Migrate consumers to structured CLI envelopes and cursors.
+- [ ] Add PostgreSQL and MySQL query checks.
+- [ ] Add retry and timeout policy controls.
+- [ ] Add registry diff and impact analysis.
+- [ ] Add Prometheus metrics and configuration generation.
+- [ ] Add Jinja2 integration for safe templates.
+- [ ] Evaluate custom BWS endpoints only after the hosted-only boundary has a design and tests.
+
+## Deferred
+
+- Dynamic service discovery.
+- Deployment orchestration.
+- Secret writes or arbitrary secret lookup.
+- Automatic or non-main publication and production deployment.
+- Non-POSIX support for transactional artifact commands.
+
+## Historical Notes
+
+The `v0.2` foundation and migration inventory remain useful history. See
+[docs/compatibility/v0.2.md](docs/compatibility/v0.2.md) and
+[docs/releases/](docs/releases/) for version-specific notes. Do not trigger old
+release versions from backlog text; release publication requires explicit human
+approval through the protected Woodpecker workflow.
+
+*Last updated: 2026-08-17*

infralink-0.6.15/PKG-INFO

@@ -0,0 +1,310 @@
+Metadata-Version: 2.5
+Name: infralink
+Version: 0.6.15
+Summary: Infrastructure topology modeling with UUID-based nodes and typed edges
+Project-URL: Homepage, https://github.com/cyberstorm-dev/infralink
+Project-URL: Issues, https://github.com/cyberstorm-dev/infralink/issues
+Project-URL: Source, https://github.com/cyberstorm-dev/infralink
+Author: Infrastructure Team
+License-Expression: MIT
+Keywords: documentation,gitops,graph,infrastructure,monitoring,topology
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Requires-Dist: agent-surface[mcp]==0.1.5
+Requires-Dist: click>=8.0
+Requires-Dist: jinja2>=3.0
+Requires-Dist: mcp<3,>=2
+Requires-Dist: pydantic<3,>=2.11
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Provides-Extra: bws
+Requires-Dist: bitwarden-sdk<3,>=2.1; extra == 'bws'
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: jsonschema>=4.23; extra == 'dev'
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: tomli>=2.0; (python_version < '3.11') and extra == 'dev'
+Requires-Dist: twine>=5.1; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.0; extra == 'docs'
+Requires-Dist: mkdocs>=1.5; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# Infralink
+
+Infralink is a Python library and agent-oriented CLI for modeling infrastructure
+topology with UUID-based hosts, typed edges, bounded queries, health checks,
+safe connection templates, offline observation contracts, diagrams, generated
+documentation, and release evidence inspection.
+
+Current package version: `0.5.8`.
+
+## Public Boundary
+
+Infralink is the public CLI, schema, and Python API layer. It models declared
+infrastructure data, validates files, emits bounded command envelopes, and
+generates documentation or release evidence.
+
+Private host-runtime helpers live in the `cyberstorm-dev/infralink-ops`
+consumer repository.
+That repo packages controller image primitives such as registry checkout,
+template rendering, config projection, BWS-backed secret rendering, image
+retention, firewall verification, and the `infralink-host` reconciler timer.
+
+```mermaid
+flowchart LR
+    public["infralink public CLI/API"] --> registry["declared registry data"]
+    registry --> ops["infralink-ops private controller runtime"]
+    ops --> host["managed host evidence"]
+```
+
+Do not use the public Infralink package as a deployment controller by itself.
+It can inspect, validate, and model; environment-specific controllers select
+registry revisions and activate services.
+
+## Install
+
+Infralink supports Python 3.10 through 3.12. Artifact-generating commands require POSIX/Linux
+filesystem semantics and are validated on Linux in CI.
+
+```bash
+python -m pip install infralink
+python -m pip install "infralink[bws]"  # optional hosted BWS audit
+```
+
+For local development, see [CONTRIBUTING.md](CONTRIBUTING.md). Coding agents
+should also read [AGENTS.md](AGENTS.md).
+
+## Public Example
+
+```yaml
+# registry.yml
+hosts:
+  d1b9e5d5-36b0-459d-a556-96622811fbd5:
+    canonical_name: database.example.com
+    status: active
+    group: production
+    cloud: example-cloud
+    tailscale_ip: 192.0.2.10
+    services:
+      postgresql:
+        port: 5432
+        protocol: postgresql
+        exposure: internal
+```
+
+```yaml
+# edges.yml
+schema_version: "1.0"
+edges:
+  - id: 058e29ff-57b9-47c8-b6fa-0914ac03e25c
+    type: database
+    from:
+      hosts: [fa2b9872-d94c-4b20-a73a-57a205560769]
+      service: api
+    to:
+      host: d1b9e5d5-36b0-459d-a556-96622811fbd5
+      service: postgresql
+      port: 5432
+    protocol: postgresql
+    auth:
+      type: password
+      secret_ref: example/database-password
+```
+
+Validate and inspect explicit sources:
+
+```bash
+infralink --registry registry.yml --edges edges.yml validate
+infralink --registry registry.yml --edges edges.yml info
+infralink --registry registry.yml --edges edges.yml host show \
+  d1b9e5d5-36b0-459d-a556-96622811fbd5
+infralink --registry registry.yml --edges edges.yml resolve \
+  058e29ff-57b9-47c8-b6fa-0914ac03e25c --user app --database app
+```
+
+Resolution returns endpoint metadata, declared secret references, and safe
+templates such as:
+
+```text
+postgresql://app:${secret:example/database-password}@192.0.2.10:5432/app
+```
+
+The CLI never returns resolved secret values and accepts no arbitrary secret
+identifier lookup.
+
+## CLI Contract
+
+Every invocation writes exactly one structured envelope to stdout. YAML is the
+default for topology and offline observation commands; use `--output json` for
+explicit compact JSON. Envelopes include `ok`, a shallow parsed command view, a
+typed `result` or redacted `error`, and bounded next actions. Lists use explicit
+limits and opaque cursors.
+
+Topology commands use `infralink.cli/v1`. Offline observation commands use
+`agent-cli.response.v1`.
+
+## MCP
+
+The same installed executable can serve typed operator tools to an MCP client:
+
+```toml
+[mcp_servers.infralink]
+command = "/usr/local/bin/infralink"
+args = ["mcp", "serve"]
+
+[mcp_servers.infralink.env]
+INFRALINK_REGISTRY = "/var/lib/infralink/registry"
+```
+
+The server exposes `infralink_command`. Pass an argv array such as
+`["doctor", "host", "cyberstorm-watchtower"]`; its structured result is the
+same `infralink.cli/v1` envelope returned by the CLI. It accepts no shell
+syntax, while existing explicit `--write` and `--apply` gates remain in force.
+
+Useful discovery commands:
+
+```bash
+infralink capabilities
+infralink help
+infralink help resolve
+infralink --output json help resolve
+infralink explain schema-version-unsupported
+```
+
+### Operator Context
+
+For direct operator use, configure one registry checkout root in
+`$XDG_CONFIG_HOME/infralink/config.yml` (default:
+`~/.config/infralink/config.yml`):
+
+```yaml
+registry: /srv/infra-registry
+```
+
+The checkout must contain `hosts/`. With that one local selector, Doctor
+derives the standard edges and observation inputs from the checkout and keeps
+their resolved paths in its response:
+
+```bash
+infralink doctor host relayos-staging
+```
+
+Explicit `--registry`, `INFRALINK_REGISTRY`, and per-source flags override the
+local config. Gatus URL and token remain process configuration, so an MCP may
+set `INFRALINK_REGISTRY` and its Gatus environment without duplicating CLI
+logic. The local config never selects a registry revision or desired state.
+
+Offline observation examples:
+
+```bash
+AS_OF=2026-08-17T00:00:00Z
+infralink validate --source examples/observation --as-of "$AS_OF"
+infralink project observation --source examples/observation --as-of "$AS_OF"
+infralink project secrets --source examples/observation --as-of "$AS_OF"
+infralink project view service-overview --source examples/observation --as-of "$AS_OF"
+infralink project readiness ci-release --source examples/observation --as-of "$AS_OF"
+```
+
+Observation documents declare `schema_version: infralink.observation/v1` and may
+be validated against packaged schemas under
+`src/infralink/schemas/observation/v1` and
+`src/infralink/schemas/observation/v2`.
+
+In v2, a service profile may declare `configuration_slots` for non-secret
+render or materialization inputs. A slot is profile-wide by default and may
+optionally name a component owner. Instances supply exactly one typed
+`configuration_binding` for each required slot. Supported values are strings,
+integers, booleans, string lists, records, and record lists with explicitly
+declared fields; record fields are limited to scalars and string lists. The
+cross-document loader validates the binding against the profile contract, and
+`plan_v2_configuration_bindings()` returns the normalized, deterministically
+ordered renderer input. Secrets continue to use `resource_slots` and secret
+references rather than configuration bindings.
+
+## Exit Codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Positive domain result |
+| `1` | Completed negative domain result |
+| `2` | Usage error |
+| `3` | Input, schema, or entity error |
+| `4` | Provider or authentication failure |
+| `69` | Unsupported platform |
+| `70` | Unexpected internal failure |
+| `74` | Artifact I/O failure or retained recovery state |
+
+Exit `74` uses `artifact_io_failed` for storage failures and
+`artifact_recovery_required` when recovery state is retained. `internal_error`
+is reserved for exit `70`.
+
+## Python API
+
+```python
+from infralink import EdgeResolver, EdgeSet, Registry
+
+registry = Registry.load("registry.yml")
+edges = EdgeSet.load("edges.yml")
+resolver = EdgeResolver(registry, edges)
+
+endpoint = resolver.get_target_endpoint("058e29ff-57b9-47c8-b6fa-0914ac03e25c")
+template = resolver.get_connection_template(
+    "058e29ff-57b9-47c8-b6fa-0914ac03e25c",
+    user="app",
+    database="app",
+)
+```
+
+Legacy Python URL helpers remain available for compatibility but are
+deprecated. New integrations should use secret references and connection
+templates.
+
+## Development And Operations
+
+- Contribution flow and canonical checks: [CONTRIBUTING.md](CONTRIBUTING.md)
+- Agent instructions: [AGENTS.md](AGENTS.md)
+- Architecture/navigation: [docs/architecture.md](docs/architecture.md)
+- Public/private runtime split: [docs/architecture.md#public-and-private-runtime-boundary](docs/architecture.md#public-and-private-runtime-boundary)
+- Observable topology and metric contracts: [docs/observable-model.md](docs/observable-model.md)
+- Security boundaries: [docs/security-boundaries.md](docs/security-boundaries.md)
+- Release workflow: [docs/release-operator-workflow.md](docs/release-operator-workflow.md)
+- v0.2 migration history: [docs/compatibility/v0.2.md](docs/compatibility/v0.2.md)
+- Current and historical release notes: [docs/releases/](docs/releases/)
+
+## Release Adoption And Rollback
+
+Woodpecker is the only CI release executor. The manual release step runs only
+for `main` on Python 3.12 after all three parallel Python-version quality gates.
+It requires `RELEASE_VERSION` to match the package version and the pipeline
+commit to equal the current `main` commit. It rebuilds and publishes exactly the
+wheel, sdist, `SHA256SUMS`, and `SHA256SUMS.sigstore.json` to the matching
+GitHub Release tag. Existing tags or releases stop the process for operator
+inspection.
+
+Consumers verify the Cosign bundle and `SHA256SUMS` before installing the
+wheel, then record the source commit and wheel digest in consumer configuration.
+Rollback restores the previously verified release revision and digest; it does
+not rebuild old source or mutate the existing public release.
+
+Managed-host adoption is a consumer workflow. For private host controller
+runtime, adopt the verified wheel into the `infralink-ops` consumer repository,
+publish the controller image there, and select that image through the
+environment registry.
+
+## License
+
+MIT

infralink-0.6.15/PRD.md

@@ -0,0 +1,153 @@
+# Infralink Product Requirements
+
+Current package version: `0.5.6`.
+
+## Purpose
+
+Infralink makes infrastructure dependencies explicit, reviewable, and safe to
+consume by humans, agents, CI systems, and operators. It loads declarative host,
+edge, observation, and release data; validates contracts; answers bounded
+queries; resolves endpoints without resolving secrets; checks health; and
+generates deterministic artifacts.
+
+The public package is provider-neutral at its domain boundary. Optional adapters
+may integrate with external providers only through constrained, documented,
+read-only or explicitly authorized operations.
+
+## Current Requirements
+
+- Support Python 3.10 through 3.12.
+- Validate on Linux/POSIX for artifact-generating commands that rely on
+  transactional filesystem semantics.
+- Keep UUID-based host identity and typed, validated edges as the topology
+  foundation.
+- Emit exactly one structured CLI envelope per invocation.
+- Preserve stable `infralink.cli/v1` and `agent-cli.response.v1` result/error
+  contracts, bounded collections, opaque continuation cursors, and actionable
+  next steps.
+- Preserve stable exit codes for domain results, contract failures, platform
+  support, artifact I/O, and unexpected failures.
+- Return safe connection templates containing declared `secret_ref`
+  placeholders, never resolved credentials.
+- Provide offline declared-secret inventory and optional read-only hosted BWS
+  metadata audit.
+- Provide offline observation documents, diagnostics, service/profile operations
+  views, readiness suites, and packaged observation schemas.
+- Provide local host bootstrap/apply planning, status, logs, and verifier
+  surfaces with bounded sanitized output and explicit operator authority for
+  mutations.
+- Provide release candidate, publisher request, and attestation validation
+  surfaces without turning local commands into a publisher.
+- Generate deterministic diagram, documentation, CLI schema, observation schema,
+  and release schema artifacts.
+- Protect public examples and docs from private topology or secret leakage.
+- Keep Woodpecker as the only release executor.
+
+## CLI Surface
+
+The command tree includes:
+
+```text
+infralink
+|-- help [command ...]
+|-- version
+|-- info
+|-- hosts
+|-- host create|list|show|bootstrap|verifier|apply|status|logs
+|-- services
+|-- service list|show
+|-- edges-list
+|-- edge list|show
+|-- app list|show
+|-- validate
+|-- check
+|-- resolve <edge-id>
+|-- analyze --output <directory>
+|-- diagram --output <directory>
+|-- docs --output <directory>
+|-- secrets inspect|audit
+|-- capabilities
+|-- project observation|secrets|view|readiness
+|-- explain <code>
+|-- release inspect|validate-candidate|render-publisher-request|inspect-attestation
+`-- registry host get|patch
+```
+
+Topology commands require declared sources through flags or environment
+variables. Packaged examples are explicit demo and test inputs only.
+
+## Exit Codes
+
+| Code | Meaning |
+| --- | --- |
+| `0` | Positive domain result |
+| `1` | Completed negative domain result |
+| `2` | Usage error |
+| `3` | Input, schema, or entity error |
+| `4` | Provider or authentication failure |
+| `69` | Unsupported platform |
+| `70` | Unexpected internal failure |
+| `74` | Artifact I/O failure or retained recovery state |
+
+Exit `74` uses `artifact_io_failed` for storage failures and
+`artifact_recovery_required` when recovery state is retained. `internal_error`
+is reserved for exit `70`.
+
+## Secret Boundary
+
+Topology stores references such as `example/database-password`, not values.
+`resolve` may return:
+
+```text
+postgresql://app:${secret:example/database-password}@192.0.2.10:5432/app
+```
+
+`secrets inspect` reports declared references and source locations only.
+`secrets audit --provider bws` may inspect hosted Bitwarden metadata for those
+declared references, but cannot accept arbitrary secret IDs and never retrieves
+values. Production audit requires `BWS_ACCESS_TOKEN` and `BWS_ORGANIZATION_ID`.
+Custom BWS endpoints remain out of scope until explicitly designed.
+
+## Release Boundary
+
+Woodpecker is the only CI release executor. Its manual release step runs for
+`main` on Python 3.12 only after all three Python-version quality gates succeed.
+It requires the requested version to equal the package version and requires the
+pipeline commit to equal the current `main` commit. It publishes exactly:
+
+```text
+infralink-<version>-py3-none-any.whl
+infralink-<version>.tar.gz
+SHA256SUMS
+SHA256SUMS.sigstore.json
+```
+
+GitHub is the public source and release destination. The step fails if the tag
+or release already exists, builds the packages, checks them with Twine, writes
+canonical checksums, and signs the checksum file with Cosign. Local release
+scripts are validators and asset assemblers; they are not an alternate release
+path.
+
+## Non-Goals
+
+- Dynamic service discovery.
+- Secret storage, writes, resolved credential output, or arbitrary secret lookup.
+- Public disclosure of private topology.
+- Automatic release, non-main publication, or production rollout.
+- Running live host or provider mutations without explicit operator authority.
+
+## Success Criteria
+
+- Every public CLI response validates against its checked-in schema.
+- No secret value crosses a serialization boundary.
+- Generated schemas are deterministic and clean after regeneration.
+- Release assets correspond to the exact protected `main` source commit.
+- Public docs and examples contain only deliberate example topology.
+- Compatibility changes have an explicit migration path.
+
+## Historical Context
+
+The `v0.2` foundation remains documented for migration and release-history
+purposes. Keep that history in [docs/compatibility/v0.2.md](docs/compatibility/v0.2.md)
+and [docs/releases/](docs/releases/) rather than using it as the current
+top-level product frame.