lely 0.1.0__tar.gz

lely-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  # ruff and the tests on every supported Python — the same gate for every
+  # Kostavo tool, kept in one place.
+  python:
+    uses: kostavo-oss/.github/.github/workflows/python-ci.yml@main
+
+  # `mise run check` also runs ty, which the shared gate doesn't: so here it is,
+  # and the gate in CI is the gate at a desk.
+  types:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v7
+      - run: uv sync
+      - name: Type check (ty)
+        run: uv run ty check

lely-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,60 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "CONTRIBUTING.md"
+      - "CHANGELOG.md"
+      - ".github/workflows/docs.yml"
+  pull_request:
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "CONTRIBUTING.md"
+      - "CHANGELOG.md"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+# allow the GITHUB_TOKEN to deploy to Pages, and serialise deploys
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: build site
+    runs-on: ubuntu-latest
+    env:
+      NO_MKDOCS_2_WARNING: "1" # we pin mkdocs < 2; suppress the advisory banner
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+      - name: Build (mkdocs)
+        run: uv run --group docs mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: site
+
+  deploy:
+    name: deploy to Pages
+    needs: build
+    if: github.event_name != 'pull_request' # build-only on PRs; deploy from main
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v5

lely-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,131 @@
+name: release
+
+# A release is a version. Bump `version` in pyproject.toml and move the
+# CHANGELOG's [Unreleased] notes under it, in a pull request — merging that pull
+# request is the release. The same way stevin and caland are released.
+#
+# This workflow notices a version on main that isn't out yet, runs the gate on
+# it, publishes to PyPI with Trusted Publishing (repository kostavo-oss/lely,
+# workflow release.yml, environment pypi — no token), and creates the GitHub
+# release, which is what makes the `vX.Y.Z` tag.
+#
+# A version that is already tagged, or already on PyPI, is not a release: the
+# run says so and stops. So is a push that leaves the version as it was. A
+# pyproject.toml change that isn't a bump is free.
+
+on:
+  push:
+    branches: [main]
+    paths: ["pyproject.toml"]
+  workflow_dispatch: # to pick a release up again after a failure
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    name: is this a new version?
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.read.outputs.version }}
+      release: ${{ steps.read.outputs.release }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0 # the tags, to tell what is already out
+          persist-credentials: false
+      - id: read
+        name: The version, and whether it is already released
+        env:
+          EVENT: ${{ github.event_name }}
+        run: |
+          version=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+          if git rev-parse -q --verify "refs/tags/v$version" >/dev/null; then
+            echo "v$version is already tagged — nothing to release."
+            echo "release=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          if curl -fsS -o /dev/null "https://pypi.org/pypi/lely/$version/json"; then
+            echo "lely $version is already on PyPI — nothing to release."
+            echo "release=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          # Before the first release no version is tagged, so "not out yet" is true
+          # of every push. A push that leaves the version as it was is not a bump.
+          # (Started by hand, this is skipped: that is how a release is picked up
+          # again after a failure.)
+          if [ "$EVENT" = push ]; then
+            before=$(git show "HEAD^:pyproject.toml" 2>/dev/null | python3 -c "import sys, tomllib; print(tomllib.loads(sys.stdin.read())['project']['version'])" 2>/dev/null || true)
+            if [ "$before" = "$version" ]; then
+              echo "The version is $version, as it was — nothing to release."
+              echo "release=false" >> "$GITHUB_OUTPUT"
+              exit 0
+            fi
+          fi
+          if ! grep -q "^## \[$version\]" CHANGELOG.md; then
+            echo "::error::CHANGELOG.md says nothing about $version — move the [Unreleased] notes under a '## [$version] - <date>' heading"
+            exit 1
+          fi
+          echo "releasing $version"
+          echo "release=true" >> "$GITHUB_OUTPUT"
+
+  gate:
+    name: gate
+    needs: check
+    if: needs.check.outputs.release == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v7
+      - run: uv sync
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run ty check
+      - run: uv run pytest
+
+  release:
+    name: publish v${{ needs.check.outputs.version }}
+    needs: [check, gate]
+    if: needs.check.outputs.release == 'true'
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: write # the GitHub release and its tag
+      id-token: write # PyPI Trusted Publishing (OIDC)
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@v7
+      - name: Build
+        run: uv build
+      - name: Publish to PyPI
+        # First, because it is the step that can't be undone: a tag without a
+        # release can be pushed again, a release without a tag can't.
+        run: uv publish --trusted-publishing always --check-url https://pypi.org/simple/
+      - name: Release notes from CHANGELOG
+        env:
+          VERSION: ${{ needs.check.outputs.version }}
+        run: |
+          awk -v v="$VERSION" '
+            index($0, "## [" v "]") == 1 { f=1; next }
+            f && index($0, "## [") == 1 { exit }
+            f { print }
+          ' CHANGELOG.md > notes.md || true
+      - name: Create the GitHub release, which makes the tag
+        env:
+          GH_TOKEN: ${{ github.token }}
+          VERSION: ${{ needs.check.outputs.version }}
+        run: |
+          args=(--title "v$VERSION" --target "$GITHUB_SHA")
+          if [ -s notes.md ]; then args+=(--notes-file notes.md); else args+=(--generate-notes); fi
+          # 0.1.0a1, 0.2.0rc1 … are PEP 440 pre-releases: say so on GitHub too.
+          if [[ "$VERSION" =~ (a|b|rc)[0-9]+$ ]]; then args+=(--prerelease); fi
+          gh release create "v$VERSION" dist/* "${args[@]}"

lely-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.DS_Store
+.pytest_cache/
+.ruff_cache/
+plan.json
+site/

lely-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,8 @@
+# `uvx pre-commit install` once, and ruff runs on every commit.
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.9 # the ruff uv.lock has, so a commit is checked as ci checks it
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format

lely-0.1.0/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-07
+
+The first release, as alpha: this is what is built.
+
+### Added
+
+- **One plan for a whole deploy.** `lely.yml`, or `[tool.lely]` in `pyproject.toml`, lists
+  steps in the order they run; each is done by a plugin. A step takes what a step above it
+  gives (`${steps.<name>.<output>}`) and values from the environment (`${env.NAME}`, always a
+  secret). `lely validate` checks all of it offline and prints the wiring.
+- **`lely plan`** plans every step and changes nothing. Each step is ready, waiting — it
+  takes something that doesn't exist yet — or skipped, and the plan says which and why.
+  `--destroy` plans a teardown, from the bottom up.
+- **`lely apply` and `lely destroy`** run a plan: a reviewed file (`lely plan -o plan.json`),
+  or planned on the spot with `-t`. Nothing runs unasked — a terminal to answer at, or
+  `--yes` — and a destructive change needs `--allow-destructive`. Every step is planned
+  again right before it runs, and may do nothing the approved plan didn't show.
+- **A plan file is held to what it was made for**: the workspace, the steps as written, and
+  the git tree of a clean checkout. It keeps no secret.
+- **`lely status`** lists what exists because of each step, with links; `lely show` shows a
+  saved plan; `lely doctor` says which tools and which workspace lely finds.
+- **Plugins.** `bundle` deploys a Databricks Asset Bundle with the Databricks CLI's direct
+  engine; `command` runs commands you give it, with an optional plan and destroy command;
+  `bundle.run` runs a job or pipeline of a bundle step. A class in the repo
+  (`./ops/steps.py:Class`) or in an installed package is a plugin too. `lely steps` lists
+  them, `lely schema` writes a JSON Schema of the config for editors, and `lely.testing`
+  holds a plugin to the contract.
+- **GitHub.** With `--github`, in a GitHub Actions run, the plan is one comment on the pull
+  request, kept current, and the run's page says what was planned or done. `-f md` prints
+  the same Markdown. `docs/GITHUB.md` has workflows to copy.
+- **A page.** `lely ui plan.json` makes one HTML file of a plan — or of a run's record,
+  written by `apply -o` and `destroy -o` — with nothing to fetch and nothing that runs. A
+  plugin can give its plan a view of its own; the bundle shows every resource by type.
+
+### Known limits
+
+- Tried on a real workspace and on GitHub a few times, with small bundles: a first proof,
+  not a track record. `README.md`, "What has been tried", says what was and wasn't.
+- The `stevin` plugin plans and can't apply yet.

lely-0.1.0/CLAUDE.md

@@ -0,0 +1,105 @@
+# CLAUDE.md
+
+`lely`: one plan for a whole Databricks deploy. It plans, applies and destroys an ordered list
+of steps, each done by a plugin, and keeps no state. The Asset Bundle is one of those plugins.
+
+`spec/` says *what* each piece of work must deliver and when it is done; `docs/DESIGN.md` says
+*how* it is built. Read the spec of a piece before working on it. Since 2026-10-05 the two
+agree: if they disagree, or the code disagrees with either, flag it instead of silently picking
+one. Don't build past a "To decide" that is still open — those are the owner's to answer.
+
+## Rules
+
+- The core is pure: config, references, the wiring, plan assembly, the approval check and the
+  renderers do no I/O, no SDK calls, no clock, no env. I/O lives at the edges: the plugins, the
+  Databricks CLI runner, the workspace client, `git`, the command line.
+- No module outside `src/lely/steps/` knows a plugin by name — the bundle included.
+- Domain model: frozen, slotted stdlib dataclasses with tuples.
+- The bundle is the Databricks CLI's: the `bundle` plugin asks it
+  (`bundle summary/plan -o json`, `deploy --plan`, `destroy`) and never reimplements what it
+  resolves. Not `bundle validate`: on a real workspace it creates a folder, and a plan changes
+  nothing. If a bundle resource can manage something, no plugin does.
+- A step is given its own options and a way to reach the workspace, nothing else. What it takes
+  from another step is `${steps.<name>.<output>}` in its `with:`, from a step above it.
+- A plugin declares its outputs, touches only what its options name, and destroys only what it
+  can show is its own.
+- No destructive change without `destructive`, and none applied without `--allow-destructive`.
+- Nothing that changes a workspace runs unasked. A refusal is a `Refused` (exit 2); a failure
+  is any other `LelyError` (exit 1).
+- Plan files carry no secrets. A value from the environment is a `Secret`.
+- Nothing a plan says is Markdown or markup where it is shown: in a terminal its control
+  characters are made visible, on GitHub it stands in a block or a code span, on the page it
+  is escaped — and a plugin's view is written again from a short list of elements.
+- Showing a plan runs none of the project's code: `show` and `ui` load no plugin.
+- No raw invisible character in any file: write its escape. A test holds the repository to it.
+- A file lely writes is written beside its place and moved there (`cli._write`): never
+  through a link, never half. What is no file — a device, a pipe — is written to as it is.
+- With `--github` lely knows the run's token, and no line it says holds it (`cli._hide`); a
+  plan that holds it is shown by no command (`cli._holds_no_token`). A new place that prints
+  goes through one of the two.
+- Every Databricks behaviour assumption gets a test and a link to the docs in its
+  docstring. If unsure, say so and add a `TODO(verify)` — do not guess.
+- Small PR-sized commits, conventional commit messages.
+- **A change to `version` in `pyproject.toml`, merged to `main`, publishes to PyPI**
+  (`.github/workflows/release.yml`). Never bump it in passing: a release is a pull request of
+  its own, opened when the owner says.
+
+## Docs
+
+`docs/` is the site (MkDocs Material; `mkdocs.yml`), deployed from `main` to
+<https://kostavo-oss.github.io/lely/>. `mise run docs:build` builds it in strict mode: a
+broken link fails. A link out of `docs/` goes to the repository by its full address — the
+site has only what is in `docs/`. The pictures of the page in `docs/assets/` are made from
+the shared scenario; remake them when the page changes how it looks.
+
+## Commands
+
+Tooling is mise + the Astral stack (uv, ruff, ty) — same as `stevin` and `caland`.
+Never use pip/virtualenv, black/flake8/isort, or mypy.
+
+`mise run check` is the gate (lint, format check, types, unit tests). `ruff format` also
+formats the Python in Markdown code blocks, so the gate covers `docs/` and `spec/`. When
+chaining the gate in a shell, a pipe hides a failing test: check the test count, not the exit
+code of `tail`.
+
+## Status
+
+**Phases one and two are built, and lely was run on a real workspace twice (2026-10-06).** `validate`, `steps`, `schema`, `plan`,
+`show`, `apply`, `destroy`, `status` and `doctor`; the `bundle`, `command` and `bundle.run`
+plugins and plugins from a repo file; the config in `lely.yml` or `pyproject.toml`.
+
+Not built, or not proven:
+
+- **Two runs on a real workspace are a first proof, not a track record.** What it settled, what
+  it corrected (the CLI goes to the bundle's host with the credentials at hand; `bundle
+  validate` writes, so the plugin uses `bundle summary`) and what it couldn't show is in
+  `spec/004-asset-bundle.md`, "Run on a workspace". What is still assumed is a `TODO(verify)`
+  in `src/lely/steps/bundle.py`.
+- **`stevin` is parked** (`spec/006-stevin.md`): its plan half works; `apply` refuses a project
+  that uses it. The owner takes it up separately — don't extend it.
+- **GitHub is built (2026-10-06) and has run once for real**: `--github` and `-f md`
+  (`spec/008-github-actions.md`, `docs/GITHUB.md`), tested against `tests/fake_github.py`,
+  and run through all three workflows in a private repository (`kostavo-oss/lely-proof`).
+  Not tried there: OIDC sign-in, environments, a fork — see `docs/GITHUB.md`.
+- **The page is built (2026-10-06)**: `lely ui`, `StepPlan.view`, a run's record with
+  `apply -o` (`spec/007-ui.md`). Looked at in a browser and reviewed once. Whether a plugin's
+  view stays in its frame is asked of a real browser: `uv run pytest tests/browser`. It needs
+  Chrome and skips without it; `mise run check` doesn't run it, CI does (its runners have
+  Chrome). Run it after any change to `render/html.py`.
+
+There is no Databricks CLI or workspace in the unit suite:
+
+- `tests/fake_databricks.py` is the CLI as a fake, as a program and in process. It answers from
+  recordings, or simulates a bundle in a workspace kept in a folder: `plan`, `deploy`,
+  `summary`, `destroy`, `run`. What it simulates is what lely *believes* the CLI does.
+- `tests/fixtures/cli/` holds the CLI's own recorded outputs, from its acceptance tests.
+- `tests/fake_github.py` is a pull request's comments in memory, and a run's environment. What
+  it simulates is what lely *believes* GitHub does.
+- `tests/fixtures/stevin-*.json` are real stevin plan files, written by stevin against its fake
+  warehouse; `tests/fake_stevin.py` answers from them.
+- `tests/project.py` is the scenario most tests share.
+
+**lely was sluis** until 2026-10-05, when the suite took its names from Dutch engineers
+(stevin, lely, and caland — which was maeslant for a day, until the owner wanted a person's
+name there too). It had never been published, so nothing answers to the old name. The recorded plans in `tests/fixtures/stevin-*.json` still carry `deltaplan.managed` —
+that is the property stevin really writes onto tables, and it kept its name on purpose.

lely-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,78 @@
+# Contributing to lely
+
+Issues and pull requests are welcome.
+
+`lely` is alpha: everything in the specs is built, and it has run for real only a few
+times. `spec/` says what each piece must deliver, `docs/DESIGN.md` how it is built. If the
+code disagrees with either, that is a bug in one of them — please say which.
+
+## How a change lands
+
+Every change is a pull request against `main`, merged by a maintainer once its checks pass.
+
+- **`ci`** — lint, format, types, and the tests on Python 3.11–3.13. Required.
+- Small commits with [conventional](https://www.conventionalcommits.org) messages. New
+  behaviour comes with a test; a fix comes with the test that would have caught it.
+- A change to what lely shows, asks or refuses updates the spec's "As built" and, where a
+  user would notice, `CHANGELOG.md`.
+
+Some parts decide what may run, or handle what isn't trusted: `approval.py`, `running.py`,
+`source.py`, `planfile.py`, `cli.py`, `github.py`, and the renderers. **A change there is
+reviewed by someone who didn't write it before it is opened as a pull request** — in this
+project's short history, most defects in those files came in with the fix for another.
+
+## Toolchain
+
+[`mise`](https://mise.jdx.dev) pins the tools, and the stack is Astral's:
+[`uv`](https://docs.astral.sh/uv/), [`ruff`](https://docs.astral.sh/ruff/) and
+[`ty`](https://docs.astral.sh/ty/).
+
+```sh
+mise install     # the pinned Python and uv (optional but recommended)
+uv sync          # .venv with dependencies and dev tools
+mise run check   # the gate: lint, format check, types, unit tests
+```
+
+## Day to day
+
+```sh
+uv run lely                    # the CLI
+uv run pytest tests/unit       # the unit tests: no workspace, no network
+uv run pytest tests/browser    # a plugin's view, as Chrome reads it (needs Chrome)
+uv run ruff check . && uv run ruff format .
+uv run ty check
+mise run docs                  # the docs site, at localhost:8000
+```
+
+`ruff format` also formats the Python in Markdown code blocks, so the gate covers `docs/` and
+`spec/`. When you chain the gate in a shell, a pipe hides a failing test: read the test
+count, not the exit code of `tail`.
+
+The unit suite never reaches a workspace or GitHub: `tests/fake_databricks.py` and
+`tests/fake_github.py` stand in, and simulate what lely *believes* those do. What has been
+seen on the real things is written down in `spec/004-asset-bundle.md` and `docs/GITHUB.md`;
+a new assumption about either gets a test, a link to the docs it rests on, and — until it has
+been seen — a `TODO(verify)`.
+
+## Rules the code keeps
+
+`CLAUDE.md` lists them. The ones a contributor trips over first:
+
+- The core is pure. I/O lives at the edges: the plugins, the Databricks CLI runner, `git`,
+  GitHub, the command line.
+- No module outside `src/lely/steps/` knows a plugin by name — the bundle included.
+- Nothing that changes a workspace runs unasked, and nothing destructive without
+  `--allow-destructive`.
+- Nothing a plan says is obeyed where it is shown — a terminal, Markdown, the page.
+- A plan file carries no secret.
+
+## Releases
+
+A release is a version, the same way as for stevin and caland: a pull request bumps
+`version` in `pyproject.toml` and moves the changelog's *Unreleased* notes under a
+`## [X.Y.Z] - <date>` heading, and merging it is the release. `.github/workflows/release.yml`
+notices the new version on `main`, runs the gate, publishes to PyPI with Trusted Publishing —
+no token — and makes the GitHub release and its tag. A change to `pyproject.toml` that isn't a
+new version releases nothing.
+
+The first release was 0.1.0, on 2026-10-07.