trailsign 0.1.0__tar.gz

trailsign-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,20 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for PyPI Trusted Publishing (OIDC) -- no API token stored
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

trailsign-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,21 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[test]"
+      - run: pytest -v

trailsign-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+*.egg-info/
+.venv/
+build/
+dist/
+
+# Local-only infrastructure notes (real IPs, SSH key paths, live OCIDs) --
+# must NEVER be committed. See tools/verify_oracle_vault.py, which reads
+# only from CLI args/env, never from this file directly, and stays
+# secret-free so it's safe to commit.
+local-infra/

trailsign-0.1.0/CLAUDE.md

@@ -0,0 +1,81 @@
+# CLAUDE.md
+
+Guidance for Claude Code working in this repo. Kept short — detail
+lives in `docs/design.md` and `README.md`, not here.
+
+## Overview
+
+Trailsign is a small, language-independent library for resolving
+application settings from a declarative, self-describing config, where
+each value declares its own source (a literal, an environment variable,
+a vault secret, ...) instead of the caller assuming where to look.
+**Python package built out as of 2026-09-01** — `src/trailsign/` is a
+real installable package (`pyproject.toml`, src layout) with a test
+suite (`tests/`). MIT licensed, public on GitHub
+(https://github.com/nankma/trailsign), CI (`.github/workflows/test.yml`)
+runs on push/PR, `main` requires a passing PR before merge. A
+`.github/workflows/publish.yml` exists for PyPI Trusted Publishing but
+the project hasn't been published there yet — see "Immediate next
+work". A port to a second language is the other remaining open work.
+
+Extracted from a Telegram news-trend bot (Auguring, formerly Argus)
+where this design started — see `docs/design.md`'s own "Origin" section
+for why it moved here instead of staying bot-specific.
+
+## Landmines
+
+- **`trailsign-resolve:` is the only dispatch key — never rename it back
+  to a bare `resolve`, and never let it collide with `type:` or any
+  other field.** Two real bugs already happened this way (an overloaded
+  `type:` field, then a plain `resolve:` that was still a generic
+  collision risk) before landing here — see `docs/design.md`'s "Fixing
+  an ambiguity" section before touching the dispatch key.
+- **This library never constructs consumer objects, only resolves values
+  to plain data.** Turning a resolved config block into a live object
+  (an adaptor, a client, anything) is always the *consumer's* own
+  factory, never this library's job — see `docs/design.md`'s "Two jobs,
+  two owners" section. Don't add object-construction here even if it
+  seems convenient for a first real consumer.
+- **`OracleKeyVaultResolver` uses instance-principal auth
+  (`_oci_secrets_client()` in `src/trailsign/settings.py`) — not a
+  static config file, not an explicit key.** Verified 2026-09-01 against
+  a real OCI Vault secret from a compute instance (see
+  `tools/verify_oracle_vault.py`); only works from inside an OCI compute
+  instance (requires a dynamic-group IAM policy granting `read
+  secret-bundles` — a real gap hit during that verification, not a code
+  bug). `credential_sources`' `region`/`vault_ocid`/`compartment_ocid`
+  fields are validated to exist via `source:` but are **not** actually
+  consumed by this auth shape — don't assume they're load-bearing if
+  refactoring this resolver; see `docs/design.md`'s correction note
+  under "The converged design".
+- **`OracleKeyVaultResolver.resolve()` validates the node's own fields
+  (`source`, `secret_ocid`) *before* `import oci`.** This was a real bug
+  found while writing tests: `import oci` used to run first, so a
+  missing `secret_ocid` raised `ModuleNotFoundError` instead of
+  `SettingsError` whenever the `oci` package wasn't installed — breaking
+  the "no oci dependency needed unless actually used" guarantee for the
+  validation-error paths, not just the happy path. Keep the import after
+  field validation if this method is touched again.
+- **Secret hygiene**: never commit real infrastructure values (VM IPs,
+  SSH key paths, live OCIDs). `local-infra/infrastructure.yaml` holds
+  them and is gitignored; `tools/verify_oracle_vault.py` takes everything
+  sensitive via CLI arg only and stays secret-free so it's safe to
+  commit. Before this repo ever goes from private to public, run the
+  global `audit-before-going-public` skill first.
+
+## Where to look
+
+| Need | Where |
+|---|---|
+| Full design: data flow, diagrams, resolved/still-open questions | `docs/design.md` |
+| Python reference implementation | `src/trailsign/settings.py` |
+| Test suite | `tests/` (`conftest.py` has the shared fixture config) |
+| Project status, what's built vs. not | `README.md` |
+| How to write/extend design docs like `docs/design.md` | the `writing-system-design-docs` skill (global, not repo-local) |
+
+## Immediate next work
+
+Not built yet, in rough order:
+1. First PyPI publish: register the pending Trusted Publisher on pypi.org (Owner `nankma`, repo `trailsign`, workflow `publish.yml`, environment `pypi` — see `.github/workflows/publish.yml`), then cut a GitHub Release to trigger it
+2. Resolve `docs/design.md`'s remaining "Still open" items as they come up in practice, not speculatively (a non-instance-principal OCI auth shape, for consumers running outside an OCI compute instance, is the main one left)
+3. Consider a port to a second language now that the Python package is solid, since the whole design's point is being language-independent, not just Python

trailsign-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nankang Ma
+
+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.

trailsign-0.1.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.5
+Name: trailsign
+Version: 0.1.0
+Summary: Resolves a declarative, self-describing config into plain values
+Project-URL: Homepage, https://github.com/nankma/trailsign
+Project-URL: Repository, https://github.com/nankma/trailsign
+Author-email: Nankang Ma <jjkkma@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Nankang Ma
+        
+        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.
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Trailsign
+
+A small, language-independent library for resolving application
+settings from a declarative, self-describing config — where each value
+states its own source (a literal, an environment variable, a vault
+secret, ...) instead of the calling code assuming where to look.
+
+```yaml
+api-key:
+  trailsign-resolve: environment-variable
+  name: GNEWS_API_KEY
+```
+
+`trailsign-resolve:` is a reserved, namespaced key — deliberately not a
+bare word like `resolve` — so it can never collide with a consuming
+project's own field names. It dispatches to a pluggable resolver;
+whatever it resolves to is handed to the consumer as a plain value, with
+no trace of where it came from left in the shape.
+
+## Status
+
+**Python package built out, as of 2026-09-01.** `src/trailsign/` is a
+real installable package (`pyproject.toml`, src layout) with a test
+suite covering the resolve walk, the three built-in resolvers
+(`OracleKeyVaultResolver` verified against a real OCI Vault secret —
+see `tools/verify_oracle_vault.py`), `validate()`'s combined-error
+behavior, and the `trailsign-resolve` vs. `type` non-collision
+regression. MIT licensed (see `LICENSE`). Public on GitHub; CI runs the
+test suite on every push/PR. Not yet published to PyPI. A port to at
+least one other language is still open, since the design's whole point
+is being language-independent, not just Python.
+
+### Installing it
+
+Not on PyPI yet — until then, install straight from GitHub, ideally
+pinned to a tag once one exists:
+
+```
+pip install git+https://github.com/nankma/trailsign.git@main
+```
+
+Install for development on this repo: `pip install -e ".[test]"`, then
+`pytest`.
+
+## Start here
+
+- [`docs/design.md`](docs/design.md) — the core design: the config
+  shape, the resolve/dispatch contract (holds equally for a Go
+  `interface`, a Rust `trait`, or a Python `typing.Protocol`), why it's
+  shaped this way, two worked examples with diagrams, and what's still
+  undecided.
+- [`src/trailsign/settings.py`](src/trailsign/settings.py) — the Python
+  reference implementation, matching `docs/design.md` exactly.
+- [`tests/`](tests/) — the test suite; `tests/conftest.py` has a shared
+  fixture config mirroring `docs/design.md`'s worked examples.
+- the `writing-system-design-docs` skill (global, not repo-local) — the
+  doc-writing convention `docs/design.md` follows, carried over
+  from where this project started in case future design docs here want
+  the same discipline (language-independent contracts, diagrams, a
+  "still open" section that's actually kept honest).
+
+## Origin
+
+This design started inside a Telegram news-trend bot (Auguring, formerly
+Argus) while building a settings abstraction so that bot could run
+standalone as well as on its current cloud deployment. The design turned
+out to be genuinely content-independent — nothing in it assumes anything
+bot-specific — so it's being extracted into its own project rather than
+staying bot-only. `docs/design.md`'s own "Origin" section has the
+originating project's actual settings inventory, kept for context on why
+the design has the shape it has.
+
+## The split that makes this portable
+
+Two jobs, two owners, and only one of them is this library's job:
+
+1. **Resolving a marked value to a plain value** — Trailsign's job, and
+   only Trailsign's job. Nothing here knows or cares what the resolved
+   value is *for*.
+2. **Turning a resolved config block into a live object** — never
+   Trailsign's job. Each consumer owns its own small factory (a plain
+   name→constructor map) that builds whatever it needs from the
+   already-resolved values this library hands it.
+
+Full reasoning for the split, plus two complete worked examples (a news
+source's API key from an environment variable, a telemetry backend's
+credential from a vault) with diagrams, is in `docs/design.md`.
+
+## What's not decided yet
+
+See `docs/design.md`'s own "Still open" section for full detail:
+
+- A non-instance-principal auth shape for `oracleKeyVault` (today it only
+  works from inside an OCI compute instance)
+- Validation-timing default (eager vs. lazy)
+- A port to a second language

trailsign-0.1.0/README.md

@@ -0,0 +1,96 @@
+# Trailsign
+
+A small, language-independent library for resolving application
+settings from a declarative, self-describing config — where each value
+states its own source (a literal, an environment variable, a vault
+secret, ...) instead of the calling code assuming where to look.
+
+```yaml
+api-key:
+  trailsign-resolve: environment-variable
+  name: GNEWS_API_KEY
+```
+
+`trailsign-resolve:` is a reserved, namespaced key — deliberately not a
+bare word like `resolve` — so it can never collide with a consuming
+project's own field names. It dispatches to a pluggable resolver;
+whatever it resolves to is handed to the consumer as a plain value, with
+no trace of where it came from left in the shape.
+
+## Status
+
+**Python package built out, as of 2026-09-01.** `src/trailsign/` is a
+real installable package (`pyproject.toml`, src layout) with a test
+suite covering the resolve walk, the three built-in resolvers
+(`OracleKeyVaultResolver` verified against a real OCI Vault secret —
+see `tools/verify_oracle_vault.py`), `validate()`'s combined-error
+behavior, and the `trailsign-resolve` vs. `type` non-collision
+regression. MIT licensed (see `LICENSE`). Public on GitHub; CI runs the
+test suite on every push/PR. Not yet published to PyPI. A port to at
+least one other language is still open, since the design's whole point
+is being language-independent, not just Python.
+
+### Installing it
+
+Not on PyPI yet — until then, install straight from GitHub, ideally
+pinned to a tag once one exists:
+
+```
+pip install git+https://github.com/nankma/trailsign.git@main
+```
+
+Install for development on this repo: `pip install -e ".[test]"`, then
+`pytest`.
+
+## Start here
+
+- [`docs/design.md`](docs/design.md) — the core design: the config
+  shape, the resolve/dispatch contract (holds equally for a Go
+  `interface`, a Rust `trait`, or a Python `typing.Protocol`), why it's
+  shaped this way, two worked examples with diagrams, and what's still
+  undecided.
+- [`src/trailsign/settings.py`](src/trailsign/settings.py) — the Python
+  reference implementation, matching `docs/design.md` exactly.
+- [`tests/`](tests/) — the test suite; `tests/conftest.py` has a shared
+  fixture config mirroring `docs/design.md`'s worked examples.
+- the `writing-system-design-docs` skill (global, not repo-local) — the
+  doc-writing convention `docs/design.md` follows, carried over
+  from where this project started in case future design docs here want
+  the same discipline (language-independent contracts, diagrams, a
+  "still open" section that's actually kept honest).
+
+## Origin
+
+This design started inside a Telegram news-trend bot (Auguring, formerly
+Argus) while building a settings abstraction so that bot could run
+standalone as well as on its current cloud deployment. The design turned
+out to be genuinely content-independent — nothing in it assumes anything
+bot-specific — so it's being extracted into its own project rather than
+staying bot-only. `docs/design.md`'s own "Origin" section has the
+originating project's actual settings inventory, kept for context on why
+the design has the shape it has.
+
+## The split that makes this portable
+
+Two jobs, two owners, and only one of them is this library's job:
+
+1. **Resolving a marked value to a plain value** — Trailsign's job, and
+   only Trailsign's job. Nothing here knows or cares what the resolved
+   value is *for*.
+2. **Turning a resolved config block into a live object** — never
+   Trailsign's job. Each consumer owns its own small factory (a plain
+   name→constructor map) that builds whatever it needs from the
+   already-resolved values this library hands it.
+
+Full reasoning for the split, plus two complete worked examples (a news
+source's API key from an environment variable, a telemetry backend's
+credential from a vault) with diagrams, is in `docs/design.md`.
+
+## What's not decided yet
+
+See `docs/design.md`'s own "Still open" section for full detail:
+
+- A non-instance-principal auth shape for `oracleKeyVault` (today it only
+  works from inside an OCI compute instance)
+- Validation-timing default (eager vs. lazy)
+- A port to a second language