nexolith 0.2.0__tar.gz

nexolith-0.2.0/.env.example

@@ -0,0 +1,6 @@
+# Non-sensitive local Docker Compose defaults. Never reuse them in production.
+DATABASE_URL=postgresql+psycopg://nexolith:nexolith@localhost:5432/nexolith
+POSTGRES_DB=nexolith
+POSTGRES_USER=nexolith
+POSTGRES_PASSWORD=nexolith
+POSTGRES_PORT=5432

nexolith-0.2.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,34 @@
+name: Bug report
+description: Report reproducible incorrect behavior
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: What happened, and what did you expect?
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Reproduction
+      description: Include a minimal sanitized pipeline and command.
+    validations:
+      required: true
+  - type: input
+    id: versions
+    attributes:
+      label: Versions
+      description: Nexolith, Python, and operating system versions.
+    validations:
+      required: true
+  - type: checkboxes
+    id: security
+    attributes:
+      label: Security
+      options:
+        - label: This report contains no credentials or private vulnerability details.
+          required: true
+

nexolith-0.2.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/Reiver56/Nexolith/security/advisories/new
+    about: Report vulnerabilities privately.

nexolith-0.2.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,20 @@
+name: Feature request
+description: Propose an improvement to Nexolith
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What user problem should this solve?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: Describe the smallest useful solution and alternatives considered.
+    validations:
+      required: true
+

nexolith-0.2.0/.github/pull_request_template.md

@@ -0,0 +1,12 @@
+## Summary
+
+Describe what changed and why.
+
+## Validation
+
+- [ ] `uv run ruff format --check .`
+- [ ] `uv run ruff check .`
+- [ ] `uv run mypy src`
+- [ ] `uv run pytest`
+- [ ] Documentation updated where needed
+

nexolith-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,80 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          enable-cache: true
+      - name: Install Python
+        run: uv python install 3.12
+      - name: Install dependencies
+        run: uv sync --extra dev
+      - name: Check formatting
+        run: uv run ruff format --check .
+      - name: Lint
+        run: uv run ruff check .
+      - name: Type check
+        run: uv run mypy src
+      - name: Test
+        run: uv run pytest
+
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+      - name: Install build Python
+        run: uv python install 3.12
+      - name: Build wheel and source distribution
+        run: uv build --python 3.12
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+          if-no-files-found: error
+          retention-days: 1
+
+  install:
+    name: Install / Python ${{ matrix.python-version }}
+    needs: build
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+      - name: Install built wheel
+        run: python -m pip install --disable-pip-version-check dist/*.whl
+      - name: Verify package import
+        run: python -c "import nexolith; print(nexolith.__version__)"
+      - name: Verify version output
+        run: nexolith --version
+      - name: Validate service-free pipeline
+        run: nexolith validate examples/pipelines/completed_orders.yaml
+      - name: Run service-free pipeline
+        run: nexolith run examples/pipelines/completed_orders.yaml

nexolith-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,74 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build and validate distributions
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out tagged source
+        uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Verify tag belongs to master
+        run: |
+          if ! git merge-base --is-ancestor "${GITHUB_SHA}" "origin/master"; then
+            echo "::error::Release tags must point to a commit contained in master."
+            exit 1
+          fi
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+      - name: Install build environment
+        run: uv sync --frozen --extra dev --python 3.12
+      - name: Validate release metadata
+        run: uv run python -m nexolith.release_validation --tag "${GITHUB_REF_NAME}"
+      - name: Build wheel and source distribution
+        run: uv build --python 3.12
+      - name: Validate distribution metadata
+        run: uv run twine check dist/*
+      - name: Validate distribution set
+        run: >-
+          uv run python -m nexolith.release_validation
+          --tag "${GITHUB_REF_NAME}"
+          --dist-dir dist
+      - name: Store validated distributions
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5
+        with:
+          name: release-distributions
+          path: dist/
+          if-no-files-found: error
+          retention-days: 1
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/nexolith
+    permissions:
+      id-token: write
+    steps:
+      - name: Download validated distributions
+        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6
+        with:
+          name: release-distributions
+          path: dist/
+      - name: Publish distributions with Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+        with:
+          packages-dir: dist/
+          verify-metadata: false
+          attestations: true

nexolith-0.2.0/.gitignore

@@ -0,0 +1,18 @@
+.env
+.venv/
+.uv-cache/
+.uv-python/
+__pycache__/
+*.py[cod]
+*.db
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.idea/
+.vscode/
+.coverage
+coverage.xml
+htmlcov/
+dist/
+build/
+*.egg-info/

nexolith-0.2.0/CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+All notable user-facing changes to Nexolith are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and Nexolith
+follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+Changes targeting releases after 0.2.0 will be recorded here.
+
+## [0.2.0] - 2026-07-31
+
+### Added
+
+- Added a tag-driven PyPI release workflow using short-lived Trusted Publishing credentials,
+  protected-environment approval, one-time artifact builds, and fail-closed release validation.
+- Added `nexolith diagnostics`, a deterministic and secret-safe environment report for issue
+  submissions. It includes Nexolith, Python, platform, installation, dependency, SQLite, and
+  PostgreSQL driver availability without exposing local paths or environment values
+  ([PR #4](https://github.com/Reiver56/Nexolith/pull/4)).
+- Added a service-free zero-to-first-pipeline tutorial with a CSV example that covers installation,
+  validation, execution, and output inspection
+  ([PR #2](https://github.com/Reiver56/Nexolith/pull/2)).
+- Added an opt-in Docker Compose workflow and integration coverage for PostgreSQL connection,
+  reading, writing, destination modes, and CSV-to-PostgreSQL execution
+  ([PR #1](https://github.com/Reiver56/Nexolith/pull/1)).
+
+### Changed
+
+- Standardized expected failures under configuration, connector, transformation, and execution
+  domain errors. CLI diagnostics now use stable categories and preserve original causes for API
+  callers ([PR #3](https://github.com/Reiver56/Nexolith/pull/3)).
+- Declared Python 3.12, 3.13, and 3.14 as the supported versions. CI now builds the distribution
+  once, installs the wheel on every supported version, and verifies import plus the first CLI
+  workflow ([PR #5](https://github.com/Reiver56/Nexolith/pull/5)).
+- Made the Docker Compose PostgreSQL host port configurable through `POSTGRES_PORT`
+  ([PR #1](https://github.com/Reiver56/Nexolith/pull/1)).
+
+### Fixed
+
+- Expected YAML, configuration, CSV, SQL, and transformation failures now produce actionable
+  messages without an expected-error traceback. Unexpected programming errors continue to
+  propagate for debugging ([PR #3](https://github.com/Reiver56/Nexolith/pull/3)).
+- Explicit PostgreSQL test runs now fail clearly when `DATABASE_URL` is missing or PostgreSQL is
+  unreachable, while the standard service-free suite remains independent of Docker
+  ([PR #1](https://github.com/Reiver56/Nexolith/pull/1)).
+
+### Security
+
+- Redacted credentials, authenticated connection URLs, and raw driver details from expected CLI
+  failures. Environment diagnostics do not collect or report usernames, hostnames, environment
+  values, or local paths
+  ([PR #3](https://github.com/Reiver56/Nexolith/pull/3),
+  [PR #4](https://github.com/Reiver56/Nexolith/pull/4)).
+
+### Breaking changes and migrations
+
+- **CLI exit codes changed.** Scripts that previously expected exit code `1` for every failure must
+  use `2` for configuration or validation failures and `3` for execution, connector, or
+  transformation failures ([PR #3](https://github.com/Reiver56/Nexolith/pull/3)).
+- **Python 3.15 and newer are outside the supported range.** Package metadata now requires
+  `>=3.12,<3.15`. Use Python 3.12, 3.13, or 3.14 before installing Nexolith 0.2.0
+  ([PR #5](https://github.com/Reiver56/Nexolith/pull/5)).
+- No pipeline YAML, connector configuration, or stored-data migration is required. The
+  `ComponentNotFoundError` import and the result-returning default of `PipelineRunner.run()` remain
+  available for compatibility ([PR #3](https://github.com/Reiver56/Nexolith/pull/3)).
+
+## [0.1.0] - 2026-07-31
+
+### Added
+
+- Initial open-source Nexolith project with declarative YAML pipelines, CSV and SQL connectors,
+  built-in transformations, a Typer CLI, and service-free execution.

nexolith-0.2.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,56 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a
+harassment-free experience for everyone, regardless of age, body size, visible or invisible
+disability, ethnicity, sex characteristics, gender identity and expression, level of
+experience, education, socio-economic status, nationality, personal appearance, race,
+religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse,
+inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment include demonstrating
+empathy, respecting differing viewpoints, accepting constructive feedback, taking
+responsibility, and focusing on what is best for the community.
+
+Unacceptable behavior includes sexualized language or imagery, trolling or insulting
+comments, public or private harassment, publishing others' private information without
+permission, and other conduct reasonably considered inappropriate in a professional setting.
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing standards of acceptable
+behavior and will take appropriate and fair corrective action in response to behavior they
+deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces and when an individual is officially
+representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported through
+the private channel described in `SECURITY.md`. All complaints will be reviewed and
+investigated promptly and fairly. Community leaders will respect the privacy and security of
+the reporter.
+
+## Enforcement Guidelines
+
+Community leaders will follow these guidelines in determining consequences:
+
+1. **Correction** — A private warning and clarification for inappropriate behavior.
+2. **Warning** — A warning with consequences for continued behavior.
+3. **Temporary Ban** — A temporary ban from interaction with the community.
+4. **Permanent Ban** — Permanent removal for sustained or severe violations.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1.
+
+[homepage]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+

nexolith-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,66 @@
+# Contributing to Nexolith
+
+Thank you for helping make Nexolith better.
+
+## Set up the project
+
+Fork and clone the repository, then install Python 3.12, 3.13, or 3.14, uv, and the development
+dependencies:
+
+```bash
+uv sync --extra dev
+```
+
+Create a focused branch from an up-to-date `main`:
+
+```bash
+git switch -c fix/short-description
+```
+
+## Quality checks
+
+Run the complete local check suite before submitting a pull request:
+
+```bash
+uv run ruff format .
+uv run ruff check .
+uv run mypy src
+uv run pytest
+```
+
+Code should be typed, small, readable, and separated by responsibility. Prefer explicit
+domain errors, avoid global mutable state, never execute pipeline content as code, and add
+tests for changed behavior. Ruff is the source of truth for formatting and lint rules.
+
+## Issues and proposals
+
+Search existing issues before filing a report. Bug reports should include a minimal pipeline,
+the command used, expected and actual behavior, Nexolith and Python versions, and sanitized
+logs. Feature proposals should explain the user problem and why it belongs in the focused
+core. Do not include credentials or security vulnerabilities in public issues; follow
+`SECURITY.md`.
+
+## Pull requests
+
+Keep pull requests focused and explain both what changed and why. Add or update tests and
+documentation, complete the pull request template, and ensure CI passes. Maintainers may ask
+for changes to preserve the small, modular architecture. Use clear commit messages; merge
+strategy is determined by the maintainers.
+
+## Changelog
+
+Update `CHANGELOG.md` for every user-facing addition, behavior change, fix, deprecation, removal,
+or security improvement. Group entries by Keep a Changelog category, link the relevant issue or
+pull request when useful, and state breaking changes plus required migrations explicitly.
+
+Version headings must use the exact form `## [X.Y.Z] - status-or-date`, without a leading `v`.
+Release automation maps a tag such as `v0.2.0` to the `[0.2.0]` heading and fails when that section
+is absent. Use `Unreleased` while preparing a version, then replace it with an ISO date such as
+`2026-07-31` when publishing the release.
+
+## Releases
+
+Maintainers must follow [RELEASING.md](RELEASING.md). Releases originate from reviewed `master`
+commits and exact `vX.Y.Z` tags. Never store a PyPI password or API token in GitHub: publication
+uses the protected `pypi` environment and PyPI Trusted Publishing.
+

nexolith-0.2.0/FIRST_PIPELINE.md

@@ -0,0 +1,141 @@
+# Your first Nexolith pipeline
+
+This tutorial takes you from a fresh clone to a verified CSV output. It uses only local files: no
+database, Docker, credentials, `.env`, or external service is required. Allow about five minutes
+after Python and `uv` are installed.
+
+## Prerequisites
+
+Install:
+
+- [Git](https://git-scm.com/)
+- Python 3.12, 3.13, or 3.14
+- [uv](https://docs.astral.sh/uv/getting-started/installation/)
+
+Confirm that the tools are available:
+
+```bash
+git --version
+uv --version
+```
+
+`uv` creates and manages the Python environment, so you do not need to activate a virtual
+environment manually.
+
+## 1. Clone and install
+
+```bash
+git clone https://github.com/Reiver56/Nexolith.git
+cd Nexolith
+uv sync --extra dev
+uv run nexolith --version
+```
+
+The last command should print:
+
+```text
+Nexolith 0.2.0
+```
+
+`uv sync` creates `.venv` when needed and installs Nexolith plus its development dependencies from
+the lock file.
+
+## 2. Meet the example
+
+The tutorial uses two committed files:
+
+```text
+examples/
+├── data/
+│   └── orders.csv
+└── pipelines/
+    └── completed_orders.yaml
+```
+
+[`orders.csv`](examples/data/orders.csv) contains five orders: three have `completed` status, one
+is `pending`, and one is `cancelled`.
+[`completed_orders.yaml`](examples/pipelines/completed_orders.yaml) defines this flow:
+
+1. The `csv` **source** reads all five rows from `examples/data/orders.csv`.
+2. The ordered **transformations** keep rows whose `status` equals `completed`, select `id`,
+   `customer_id`, and `total`, then rename `total` to `order_total`.
+3. The `csv` **destination** writes the three remaining rows to
+   `build/completed_orders.csv`. Nexolith creates the `build` directory if necessary and
+   overwrites the CSV on later runs.
+
+Open the small YAML file before continuing if you want to see the complete declarative pipeline.
+Run all following commands from the repository root because its paths are relative to that
+directory.
+
+## 3. Validate
+
+Validation checks the YAML structure and configuration without reading input or writing output:
+
+```bash
+uv run nexolith validate examples/pipelines/completed_orders.yaml
+```
+
+Expected output:
+
+```text
+Pipeline 'completed_orders' is valid.
+```
+
+## 4. Run
+
+```bash
+uv run nexolith run examples/pipelines/completed_orders.yaml
+```
+
+The duration varies, but the meaningful output is:
+
+```text
+Pipeline: completed_orders
+Status: succeeded
+Rows read: 5
+Rows written: 3
+Duration: <varies>s
+```
+
+Informational log lines may also appear. A failed pipeline exits with a non-zero status and prints
+an error.
+
+## 5. Inspect the output
+
+Use Python's standard CSV reader for the same check in PowerShell, Command Prompt, bash, and other
+common shells:
+
+```bash
+uv run python -c "import csv; print(*csv.DictReader(open('build/completed_orders.csv', newline='', encoding='utf-8')), sep='\n')"
+```
+
+Expected rows:
+
+```text
+{'id': '1', 'customer_id': '101', 'order_total': '49.90'}
+{'id': '3', 'customer_id': '103', 'order_total': '125.00'}
+{'id': '5', 'customer_id': '105', 'order_total': '75.25'}
+```
+
+The header and those three rows are the entire generated file. The source remains unchanged.
+Because `build/` is ignored by Git, this output will not be committed accidentally.
+
+## Troubleshooting
+
+- **`uv` is not recognized:** install `uv`, restart the shell so its installation directory is on
+  `PATH`, and run `uv --version`.
+- **Unsupported Python version:** install Python 3.12, 3.13, or 3.14 (for example,
+  `uv python install 3.12`), then repeat `uv sync --extra dev`.
+- **Pipeline file not found or input CSV cannot be read:** return to the cloned repository root and
+  run the commands there. Confirm that both files shown in the tree above exist.
+- **Validation fails:** use the reported field path to check the YAML. Spaces matter in YAML; do
+  not replace indentation with tabs.
+- **The output differs after editing the example:** rerun validation and execution. The
+  destination is overwritten on each successful run.
+
+## Next step
+
+Copy `completed_orders.yaml`, change the filter or selected columns, and give the destination a
+different path under `build/`. Then review the supported
+[connectors and transformations](README.md#connectors). When you need a database destination,
+start with SQLite before moving to the optional PostgreSQL example.