Basic functionality

.github/workflows/check-links.yml

@@ -0,0 +1,32 @@
+name: check-links
+
+on:
+  # Manually trigger the workflow using
+  # gh workflow run check-links.yml # --ref <branch>
+  # gh run list --workflow check-links.yml # --branch <branch>
+  workflow_dispatch:
+  repository_dispatch:
+  schedule:
+    - cron: "00 18 * * 1"
+
+jobs:
+  linkChecker:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write # required for peter-evans/create-issue-from-file
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Link Checker
+        id: lychee
+        uses: lycheeverse/lychee-action@v2
+        with:
+          fail: false
+
+      - name: Create Issue From File
+        if: steps.lychee.outputs.exit_code != 0
+        uses: peter-evans/create-issue-from-file@v5
+        with:
+          title: Link Checker Report
+          content-filepath: ./lychee/out.md
+          labels: report, automated issue

.github/workflows/publish-test.yml

@@ -0,0 +1,56 @@
+name: publish-test
+
+# This workflow is used to test the publish workflow without actually publishing to PyPI. 
+
+# Differences with the publish workflow:
+# - It is triggered manually instead of being triggered by the release workflow and/or tags.
+# - It publishes to https://test.pypi.org/ instead of https://pypi.org/, 
+#   which is a separate instance of the Python Package Index that allows trying distribution tools and processes without affecting the real index
+# - It enables verbose: true in the pypa/gh-action-pypi-publish action to get more detailed logs for debugging
+# - It uses POETRY_DYNAMIC_VERSIONING_BYPASS to bypass the dynamic versioning and use a static version that is accepted by Test PyPI, 
+#   since Test PyPI (and PyPI) reject local versions (+hash) generated by poetry-dynamic-versioning in the absence of tags.
+#
+# Also keep in mind that OIDC authentication does not work with shared workflows, 
+# so the code essentially needs to be duplicated in the `publish.yml` and `publish-test.yml` workflows.
+
+on:
+  # The workflow is usually triggered when the release workflow completes, but it can also be re-triggered manually if needed using
+  # gh workflow run publish-test.yml --ref <tag>
+  # gh run list --workflow publish-test.yml
+  workflow_dispatch:
+  repository_dispatch:
+
+env:
+  MISE_EXPERIMENTAL: true
+  # Test PyPI (and PyPI) reject local versions (+hash) generated by poetry-dynamic-versioning in the absence of tags. 
+  # So the simplest approach for testing is to override the version with a static one that is accepted by Test PyPI.
+  POETRY_DYNAMIC_VERSIONING_BYPASS: "0.0.1.dev0"
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+      - uses: jdx/mise-action@v3
+      - run: mise run ci-build
+  pypi-publish:
+    name: Upload release to Test PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      # cosmetic URL displayed in the GitHub UI for the environment, 
+      # not to be confused with the repository-url used by the pypa/gh-action-pypi-publish action,
+      # which is the actual URL of the repository where the package is published
+      url: https://test.pypi.org/p/nbkp/
+    permissions:
+      id-token: write  # IMPORTANT: this permission is mandatory for trusted publishing
+    steps:
+    - uses: actions/checkout@v6
+    - uses: jdx/mise-action@v3
+    - run: mise run ci-build
+    - name: Publish package distributions to Test PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        repository-url: https://test.pypi.org/legacy/
+        verbose: true

.github/workflows/publish.yml

@@ -0,0 +1,50 @@
+name: publish
+
+# Test this workflow by making similar changes to `publish-test.yml` and triggering it manually
+#
+# OIDC authentication does not work with shared workflows, 
+# so the code essentially needs to be duplicated in the `publish.yml` and `publish-test.yml` workflows.
+
+on:
+  push:
+    tags:
+      - 'v*'
+  # Tags created by a workflow using GITHUB_TOKEN do not trigger other workflows
+  workflow_run:
+    workflows: ["release"]
+    types:
+      - completed
+  # The workflow is usually triggered when the release workflow completes, but it can also be re-triggered manually if needed using
+  # gh workflow run publish.yml --ref <tag>
+  # gh run list --workflow publish.yml
+  workflow_dispatch:
+  repository_dispatch:
+
+env:
+  MISE_EXPERIMENTAL: true
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+      - uses: jdx/mise-action@v3
+      - run: mise run ci-build
+  pypi-publish:
+    name: Upload release to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      # cosmetic URL displayed in the GitHub UI for the environment, 
+      # not to be confused with the repository-url used by the pypa/gh-action-pypi-publish action, 
+      # which is the actual URL of the repository where the package is published
+      url: https://pypi.org/p/nbkp/
+    permissions:
+      id-token: write  # IMPORTANT: this permission is mandatory for trusted publishing
+    steps:
+    - uses: actions/checkout@v6
+    - uses: jdx/mise-action@v3
+    - run: mise run ci-build
+    - name: Publish package distributions to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/release.yml

@@ -0,0 +1,27 @@
+name: release
+on:
+  # Manually trigger the workflow using
+  # gh workflow run release.yml # --ref <branch>
+  # gh run list --workflow release.yml
+  workflow_dispatch:
+  repository_dispatch:
+  # push:
+  #   branches:
+  #     - main
+
+jobs:
+  bump-version:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Bump version and push tag
+        id: tag-version
+        uses: mathieudutour/github-tag-action@v6.2
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+      - name: Create a GitHub release
+        uses: ncipollo/release-action@v1
+        with:
+          tag: ${{ steps.tag-version.outputs.new_tag }}
+          name: ${{ steps.tag-version.outputs.new_tag }}
+          body: ${{ steps.tag-version.outputs.changelog }}

.github/workflows/test.yml

@@ -0,0 +1,38 @@
+name: test
+
+on:
+  # Manually trigger the workflow using
+  # gh workflow run test.yml # --ref <branch>
+  # gh run list --workflow test.yml # --branch <branch>
+  workflow_dispatch:
+  repository_dispatch:
+  pull_request:
+  push:
+    tags:
+      - "*"
+    branches:
+      - "main"
+
+# concurrency:
+#   group: ${{ github.workflow }}-${{ github.ref }}
+#   cancel-in-progress: true
+
+concurrency:
+  # On main/release, we don't want any jobs cancelled so the sha is used to name the group
+  # On PR branches, we cancel the job if new commits are pushed
+  # Additionally, we want the workflow for each aggregate project to run independently
+  # More info: https://stackoverflow.com/a/68422069/253468
+  group: ${{ github.workflow }}-${{ (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/master' || github.ref == 'refs/heads/release' ) && format('{0}-main-{1}', github.workflow, github.sha) || format('{0}-main-{1}', github.workflow, github.ref) }}
+  cancel-in-progress: true
+
+env:
+  MISE_EXPERIMENTAL: true
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+      - uses: jdx/mise-action@v3
+      - run: mise run ci-test

CLAUDE.md

@@ -0,0 +1,23 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Architecture
+
+Detailed overview of the architecture, design patterns, and execution flow: @docs/architecture.md
+
+## Concepts
+
+Explanations of key concepts such as volumes, syncs, and the configuration model: @docs/concepts.md
+
+## Conventions
+
+Coding conventions, testing practices, and other guidelines for contributing to the codebase: @docs/conventions.md
+
+## Build & Test Commands
+
+Instructions on how to run unit and integration tests, as well as formatting and linting checks: @docs/building-and-testing.md
+
+## Releasing and Publishing
+
+Instructions on how to create new releases and publish the package to PyPI: @docs/releasing-and-publishing.md