narratty 0.1.0__tar.gz

narratty-0.1.0/.codespellignore

@@ -0,0 +1,5 @@
+# codespell ignore list: words that are not typos in this project.
+narratty
+astroid
+hiden
+widht

narratty-0.1.0/.dockerignore

@@ -0,0 +1,13 @@
+.git
+.venv
+.nox
+.mypy_cache
+.ruff_cache
+.pytest_cache
+**/__pycache__
+site
+out
+dist
+tests
+docs
+*.mp4

narratty-0.1.0/.github/workflows/docker.yml

@@ -0,0 +1,96 @@
+name: Docker image
+# PRs: build and test the image (amd64, not pushed).
+# main: push :edge / :edge-kokoro.  Release tags v*: push :<version>, :latest (and -kokoro).
+on:
+  pull_request:
+  push:
+    branches: [main]
+    tags: ["v[0-9]+.[0-9]+.[0-9]*"]
+concurrency:
+  group: docker-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+permissions:
+  contents: read
+env:
+  IMAGE: ghcr.io/${{ github.repository_owner }}/narratty
+jobs:
+  image:
+    name: Image (${{ matrix.variant }})
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - variant: base
+            target: base
+            suffix: ""
+          - variant: kokoro
+            target: kokoro
+            suffix: "-kokoro"
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0 # the version comes from git tags
+      - uses: astral-sh/setup-uv@v7
+      - name: Version
+        id: version
+        run: echo "version=$(uvx --from setuptools-scm python -m setuptools_scm)" >> "$GITHUB_OUTPUT"
+      - uses: docker/setup-qemu-action@v4
+        if: github.event_name != 'pull_request'
+      - uses: docker/setup-buildx-action@v4
+      - uses: docker/metadata-action@v6
+        id: meta
+        with:
+          images: ${{ env.IMAGE }}
+          flavor: |
+            latest=false
+            suffix=${{ matrix.suffix }},onlatest=true
+          tags: |
+            type=edge,branch=main
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=raw,value=latest,enable=${{ startsWith(github.ref, 'refs/tags/v') }}
+            type=ref,event=pr
+      - name: Log in to GHCR
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Build (and push outside PRs)
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          target: ${{ matrix.target }}
+          build-args: NARRATTY_VERSION=${{ steps.version.outputs.version }}
+          platforms: ${{ github.event_name == 'pull_request' && 'linux/amd64' || 'linux/amd64,linux/arm64' }}
+          push: ${{ github.event_name != 'pull_request' }}
+          load: ${{ github.event_name == 'pull_request' }}
+          tags: ${{ github.event_name == 'pull_request' && format('narratty:test{0}', matrix.suffix) || steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha,scope=${{ matrix.variant }}
+          cache-to: type=gha,mode=max,scope=${{ matrix.variant }}
+      - name: Smoke test
+        if: github.event_name == 'pull_request'
+        run: |
+          docker run --rm narratty:test${{ matrix.suffix }} --version
+          docker run --rm narratty:test${{ matrix.suffix }} doctor --runtime native
+          docker run --rm narratty:test${{ matrix.suffix }} voices --installed
+      - uses: actions/setup-python@v6
+        if: github.event_name == 'pull_request' && matrix.variant == 'base'
+        with:
+          python-version: "3.12"
+      - name: Install ffprobe (the test checks the video on the host)
+        if: github.event_name == 'pull_request' && matrix.variant == 'base'
+        run: sudo apt-get update && sudo apt-get install -y --no-install-recommends ffmpeg
+      - name: Build a video through the container runtime and test the sandbox network
+        if: github.event_name == 'pull_request' && matrix.variant == 'base'
+        env:
+          NARRATTY_IMAGE: narratty:test
+        run: |
+          uv tool install nox
+          nox -s integration -- -k "container or sandbox_network"

narratty-0.1.0/.github/workflows/main.yml

@@ -0,0 +1,79 @@
+name: Main
+on:
+  push:
+    branches: [main]
+concurrency:
+  group: main-${{ github.ref }}
+  cancel-in-progress: true
+permissions:
+  contents: read
+jobs:
+  # ── 1. Full quality gates ───────────────────────────────────────────────────
+  quality:
+    name: Quality gates (3.12)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v7
+      - name: Install nox
+        run: uv tool install nox
+      - name: Run all quality gates
+        run: nox --no-error-on-missing-interpreters
+  # ── 2. Tests: multi-Python matrix, macOS best effort ────────────────────────
+  tests:
+    name: Tests (${{ matrix.os }}, Python ${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    continue-on-error: ${{ matrix.os == 'macos-latest' }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.12", "3.13", "3.14"]
+        include:
+          - os: macos-latest
+            python-version: "3.12"
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          allow-prereleases: true
+      - uses: astral-sh/setup-uv@v7
+      - name: Install nox
+        run: uv tool install nox
+      - name: Unit tests
+        run: nox -s tests-${{ matrix.python-version }}
+  # ── 3. Deploy docs `latest` to GitHub Pages ─────────────────────────────────
+  docs-deploy:
+    name: Deploy docs (latest)
+    runs-on: ubuntu-latest
+    needs: [quality, tests]
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v7
+      - name: Install docs deps
+        run: uv pip install -e ".[docs]" --system
+      - name: Configure git for mike
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+      - name: Deploy latest docs
+        env:
+          NO_MKDOCS_2_WARNING: "1"
+        run: |
+          mike deploy --push --update-aliases latest
+          mike set-default --push latest

narratty-0.1.0/.github/workflows/pr.yml

@@ -0,0 +1,156 @@
+name: PR
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, edited]
+concurrency:
+  group: pr-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+permissions:
+  contents: read
+  pull-requests: read
+jobs:
+  # ── 1. Conventional Commits PR-title lint (primary gate for squash merges) ──
+  lint-title:
+    name: Lint PR title
+    runs-on: ubuntu-latest
+    steps:
+      - uses: amannn/action-semantic-pull-request@v6
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          types: |
+            feat
+            fix
+            docs
+            refactor
+            perf
+            test
+            build
+            ci
+            chore
+            revert
+          requireScope: false
+          subjectPattern: ^[a-z].+[^.]$
+          subjectPatternError: |
+            Subject must start lowercase and not end with a period.
+  # ── 2. Code quality ─────────────────────────────────────────────────────────
+  quality:
+    name: Quality gates (3.12)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0 # hatch-vcs needs tags for the version
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v7
+      - name: Install nox
+        run: uv tool install nox
+      - name: Syntax check
+        run: nox -s check_syntax
+      - name: Lint
+        run: nox -s lint
+      - name: Type check
+        run: nox -s check_types
+      - name: Import analysis
+        run: nox -s necessary_imports
+      - name: Dead code
+        run: nox -s dead_code
+      - name: Duplicate code
+        run: nox -s duplicates
+      - name: Cyclic imports
+        run: nox -s cyclic_imports
+  # ── 3. Tests: multi-Python matrix, macOS best effort ────────────────────────
+  tests:
+    name: Tests (${{ matrix.os }}, Python ${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    continue-on-error: ${{ matrix.os == 'macos-latest' }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.12", "3.13", "3.14"]
+        include:
+          # macOS is optional: smoke-test the primary Python, never block.
+          - os: macos-latest
+            python-version: "3.12"
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          allow-prereleases: true
+      - uses: astral-sh/setup-uv@v7
+      - name: Install nox
+        run: uv tool install nox
+      - name: Unit tests
+        run: nox -s tests-${{ matrix.python-version }}
+  # ── 4. Integration: real voices, VHS and ffmpeg ─────────────────────────────
+  integration:
+    name: Integration (3.12)
+    runs-on: ubuntu-latest
+    env:
+      NARRATTY_DATA_DIR: ${{ github.workspace }}/.narratty-data
+      VHS_VERSION: "0.12.1"
+      # Chromium's sandbox is blocked by Ubuntu's user-namespace restrictions on runners.
+      VHS_NO_SANDBOX: "true"
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v7
+      - name: Cache voices and models
+        uses: actions/cache@v5
+        with:
+          path: .narratty-data
+          key: narratty-voices-${{ hashFiles('src/narratty/data/voices.toml') }}
+      - name: Install ffmpeg, ttyd and VHS
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends ffmpeg ttyd
+          curl -fsSL -o "$RUNNER_TEMP/vhs.deb" \
+            "https://github.com/charmbracelet/vhs/releases/download/v${VHS_VERSION}/vhs_${VHS_VERSION}_amd64.deb"
+          sudo apt-get install -y "$RUNNER_TEMP/vhs.deb"
+          vhs --version
+      - name: Install nox
+        run: uv tool install nox
+      - name: Integration tests
+        run: nox -s integration
+  # ── 5. CLI cold-start performance budgets ───────────────────────────────────
+  performance:
+    name: Performance budgets (3.12)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v7
+      - name: Install nox
+        run: uv tool install nox
+      - name: Performance budgets
+        run: nox -s performance
+  # ── 6. Docs build (strict) ──────────────────────────────────────────────────
+  docs-build:
+    name: Docs build (strict)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v7
+      - name: Install nox
+        run: uv tool install nox
+      - name: Build docs
+        run: nox -s docs

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

@@ -0,0 +1,134 @@
+name: Release
+on:
+  push:
+    tags:
+      - "v[0-9]+.[0-9]+.[0-9]*"
+permissions:
+  contents: write # create GitHub Release
+  id-token: write # OIDC Trusted Publishing (PyPI + TestPyPI)
+jobs:
+  # ── 1. Build sdist + wheel ───────────────────────────────────────────────────
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0 # hatch-vcs needs full history
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v7
+      - name: Install hatch
+        run: uv tool install hatch
+      - name: Build
+        run: hatch build
+      - name: Extract version
+        id: version
+        run: echo "version=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+  # ── 2. Publish to TestPyPI (dry-run gate) ───────────────────────────────────
+  publish-test:
+    name: Publish to TestPyPI
+    runs-on: ubuntu-latest
+    needs: build
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/narratty
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          print-hash: true
+          verbose: true
+      - name: Verify install from TestPyPI
+        run: |
+          uv tool install \
+            --index-url https://test.pypi.org/simple/ \
+            --extra-index-url https://pypi.org/simple/ \
+            "narratty==${{ needs.build.outputs.version }}"
+          narratty --version
+  # ── 3. Publish to PyPI (production) ─────────────────────────────────────────
+  publish-pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: [build, publish-test]
+    environment:
+      name: pypi
+      url: https://pypi.org/p/narratty
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          print-hash: true
+  # ── 4. Create GitHub Release ─────────────────────────────────────────────────
+  github-release:
+    name: Create GitHub Release
+    runs-on: ubuntu-latest
+    needs: [build, publish-pypi]
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v7
+      - name: Install commitizen
+        run: uv tool install commitizen
+      - name: Extract changelog for this version
+        run: |
+          cz changelog --dry-run "${{ needs.build.outputs.version }}" > /tmp/release-notes.md || \
+          echo "Release ${{ needs.build.outputs.version }}" > /tmp/release-notes.md
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v3
+        with:
+          body_path: /tmp/release-notes.md
+          files: dist/*
+          fail_on_unmatched_files: true
+  # ── 5. Deploy versioned docs ─────────────────────────────────────────────────
+  docs-deploy:
+    name: Deploy versioned docs
+    runs-on: ubuntu-latest
+    needs: [build, github-release]
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v7
+      - name: Install docs deps
+        run: uv pip install -e ".[docs]" --system
+      - name: Configure git for mike
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+      - name: Deploy versioned docs
+        run: |
+          VERSION="${{ needs.build.outputs.version }}"
+          mike deploy --push --update-aliases "$VERSION" stable
+          mike set-default --push stable

narratty-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+# generated files
+src/narratty/_version.py
+
+# Byte-compiled / caches
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Environments
+.venv/
+venv/
+.env
+
+# Tooling caches
+.nox/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Editor
+.idea/
+*.swp
+
+
+
+
+# MkDocs build output
+site/
+
+# narratty render output
+out/

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

@@ -0,0 +1,54 @@
+default_install_hook_types: [pre-commit, commit-msg]
+default_stages: [pre-commit, manual]
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks.git
+    rev: v6.0.0
+    hooks:
+      - id: check-added-large-files
+        args: [--maxkb=500]
+      - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: check-symlinks
+      - id: check-toml
+      - id: check-yaml
+        args: [--unsafe]  # mkdocs.yml uses custom tags
+      - id: end-of-file-fixer
+      - id: mixed-line-ending
+        args: [--fix=lf]
+      - id: trailing-whitespace
+        args: [--markdown-linebreak-ext=md]
+      - id: detect-private-key
+
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.4.2
+    hooks:
+      - id: codespell
+        args: [--ignore-words=.codespellignore, --quiet-level=2]
+
+  # Quality gates mirror the nox sessions and run in isolated uv envs, so
+  # versions come from the pyproject extras rather than host tools.
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: ruff check
+        entry: uv run --isolated --extra lint ruff check --fix
+        language: system
+        types: [python]
+      - id: ruff-format
+        name: ruff format
+        entry: uv run --isolated --extra lint ruff format
+        language: system
+        types: [python]
+      - id: mypy
+        name: mypy
+        entry: uv run --isolated --extra type-check mypy
+        language: system
+        pass_filenames: false
+        args: [--package, narratty]
+
+  - repo: https://github.com/commitizen-tools/commitizen
+    rev: v4.16.4
+    hooks:
+      - id: commitizen
+        stages: [commit-msg]

narratty-0.1.0/AGENTS.md

@@ -0,0 +1,29 @@
+# AGENTS.md
+
+`narratty` is a Python CLI (command and import package `narratty`) that turns a
+`.narratty.yaml` spec into a narrated terminal video. The design and milestones live in
+`docs/contributor-guide/design.md`; read it before adding features.
+
+## Tooling
+
+- **uv** manages the environment (`uv sync --extra dev` creates `.venv`), **nox** runs the
+  quality gates. `noxfile.py` is the authoritative command list.
+- Lint and format: ruff only (`nox -s lint`, `nox -s format`). Types: mypy (`nox -s check_types`).
+- Unit tests: `nox -s tests` or `.venv/bin/pytest`. Performance budgets are marked
+  `performance` and deselected by default; run them with `nox -s performance`.
+- Docs: `nox -s docs` (mkdocs `--strict`, zero warnings).
+
+## Conventions
+
+- One module per subcommand under `src/narratty/cli/commands/`. Import heavy dependencies
+  inside the command function so `--help` and shell completion stay under their budgets.
+- Errors are `NarrattyError` subclasses carrying an `ExitCode` and an optional `hint`;
+  never renumber `ExitCode`.
+- Data goes to stdout, logs and errors to stderr (`narratty.ui.console`).
+- Commits and PR titles follow Conventional Commits.
+
+## Gotchas
+
+- The version comes from git tags via hatch-vcs; shallow clones without tags report
+  `0.1.devN`. CI checks out with `fetch-depth: 0`.
+- `nox` without `NOX_CI=1` runs `format` first, which edits files.

narratty-0.1.0/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Conventional Commits](https://www.conventionalcommits.org/) and is maintained by
+commitizen.
+
+## v0.1.0 (2026-09-30)
+
+### Feat
+
+- **end-card**: close videos with a "Created with narratty" card and QR code
+- **sandbox**: add workspace modes, network allowlist and sandbox consent
+- **container**: add the narratty image, GHCR publishing and a container runtime
+- **build**: render narrated videos with VHS and ffmpeg
+- **tts**: add Piper and Kokoro providers with voice catalog and audio cache
+- **init**: point the schema header at the installed version's schema
+- **spec**: add spec format v1 with init, validate and schema commands
+- project scaffold with doctor command and shell completion
+
+### Fix
+
+- **container**: install ttyd from its release binary