steppy-dev 0.3.0__tar.gz

steppy_dev-0.3.0/.claude/launch.json

@@ -0,0 +1,41 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "player-dev",
+      "runtimeExecutable": "python",
+      "runtimeArgs": [
+        "-m",
+        "http.server",
+        "8099",
+        "--directory",
+        "packages/player"
+      ],
+      "port": 8099
+    },
+    {
+      "name": "tour-demo",
+      "runtimeExecutable": "python",
+      "runtimeArgs": [
+        "fixtures/tour-demo/serve.py",
+        "--port",
+        "8770"
+      ],
+      "port": 8770
+    },
+    {
+      "name": "tour-demo-angular",
+      "runtimeExecutable": "python",
+      "runtimeArgs": [
+        "fixtures/tour-demo/serve.py",
+        "--port",
+        "8772",
+        "--style-src",
+        "'unsafe-inline'",
+        "--app-dir",
+        "fixtures/tour-demo-angular/app/dist/tour-demo-angular/browser"
+      ],
+      "port": 8772
+    }
+  ]
+}

steppy_dev-0.3.0/.dockerignore

@@ -0,0 +1,54 @@
+# Build context for the worker image (see Dockerfile). The image build only
+# needs: pyproject.toml, hatch_build.py, src/, templates/, skills/,
+# CHANGELOG.md. Everything else is excluded to keep `docker build` fast and
+# to keep local secrets/state from being sent to the Docker daemon.
+
+# VCS / editor
+.git/
+.github/
+.claude/
+
+# Secrets — never leave the host
+.auth/
+credentials.yaml
+credentials.yml
+
+# Runtime state / generated output
+.steppy/
+output/
+tests/e2e/
+
+# Python caches / envs
+__pycache__/
+**/__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Node workspaces — the built player bundle is vendored at
+# src/steppy/_player_bundle/, so packages/ isn't needed for the image build.
+packages/
+node_modules/
+**/node_modules/
+
+# Project/dev files not needed to pip-install the steppy package
+tests/
+fixtures/
+scenarios/
+seed/
+config.yaml
+credentials.yaml.example
+steppy.guide.config.ts
+steppy-config.schema.json
+docker-compose*.yml
+Dockerfile
+.dockerignore
+README.md
+SECURITY.md
+CONTRIBUTING.md
+NEW_COMMANDS.md
+PROJECT.md

steppy_dev-0.3.0/.gitattributes

@@ -0,0 +1,22 @@
+# LF everywhere, on every OS. Several guard tests compare files byte for byte
+# (the _totp_now / _base_language / sanitise_nodeid mirrors, the generated
+# JSON schemas, the vendored bundles), and a CRLF checkout on Windows turns
+# those into diffs nobody made.
+* text=auto eol=lf
+
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.webp binary
+*.ico binary
+*.pdf binary
+*.mp4 binary
+*.wav binary
+*.zip binary
+
+# Build outputs committed on purpose (so `pip install git+...` needs no Node).
+# Collapsed in diffs and left out of GitHub's language statistics.
+src/steppy/_player_bundle/*.js linguist-generated=true
+src/steppy/_player_bundle/*.js.map linguist-generated=true
+fixtures/demo-guide/public/assets/**/steppy-player.js linguist-generated=true

steppy_dev-0.3.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,77 @@
+name: Bug report
+description: Something in Steppy behaves differently from what the docs say.
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report this. A security vulnerability goes
+        through a private advisory instead (see SECURITY.md), never a public issue.
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - Scenarios, validate or generate
+        - Running tests (steppy run)
+        - Parallel runs (--workers)
+        - Guides, build, PDF or video
+        - In-app tours
+        - Report, bundle or coverage
+        - Recording (steppy record)
+        - "@steppy/player"
+        - "@steppy/angular"
+        - Something else
+    validations:
+      required: true
+
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: Include the full error. Re-running with `--verbose` (or `STEPPY_DEBUG=1`) prints the traceback.
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduce
+    attributes:
+      label: How to reproduce
+      description: |
+        The command you ran, and the smallest scenario or `config.yaml` excerpt that shows the
+        problem. Use the neutral example domain if you can.
+      render: markdown
+    validations:
+      required: true
+
+  - type: input
+    id: steppy-version
+    attributes:
+      label: Steppy version
+      description: Output of `python -c "import steppy; print(steppy.__version__)"`, or the npm package version.
+    validations:
+      required: true
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Operating system, Python version, Playwright version, and Node version if the problem involves `steppy build` or an npm package.
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: redaction
+    attributes:
+      label: Before you submit
+      options:
+        - label: I removed credentials, tokens, internal URLs and personal data from the logs, config and screenshots above.
+          required: true

steppy_dev-0.3.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Report a security vulnerability
+    url: https://github.com/Steppy-dev/steppy/security/advisories/new
+    about: Report it privately through a security advisory, never in a public issue.

steppy_dev-0.3.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,41 @@
+name: Feature request
+description: Suggest a new capability or a change to an existing one.
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: The problem
+      description: What are you trying to do, and what gets in the way today? A scenario excerpt helps.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: What you would like
+      description: How it could work from your side, such as a new step field, action, config key or command.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: What you do today instead
+      description: "For example an `action: custom` block or a `call` helper you had to write."
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - Scenarios, validate or generate
+        - Running tests (steppy run)
+        - Parallel runs (--workers)
+        - Guides, build, PDF or video
+        - In-app tours
+        - Report, bundle or coverage
+        - Recording (steppy record)
+        - "@steppy/player"
+        - "@steppy/angular"
+        - Something else

steppy_dev-0.3.0/.github/pull_request_template.md

@@ -0,0 +1,13 @@
+## What this changes
+
+<!-- What the change does and why. Link the issue it closes, if any. -->
+
+## Checklist
+
+- [ ] `python -m pytest tests/ --ignore=tests/e2e -q` passes
+- [ ] `ruff check . && ruff format --check .` passes
+- [ ] Templates were edited in `templates/` only, never in the generated `src/steppy/templates/`
+- [ ] If `packages/player/src/` changed: `npm --prefix packages/player test` passes, and the bundles were rebuilt and re-vendored into `src/steppy/_player_bundle/`
+- [ ] A user-visible change has an entry under `[Unreleased]` in `CHANGELOG.md`, and the docs and skills say the same thing
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for the guard tests and what each one protects. By opening this pull request you agree that your contribution is licensed under the Apache License 2.0, as described there.

steppy_dev-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,218 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # Ruff comes from the `dev` dependency group (pyproject.toml), never from
+      # whatever happens to be on PATH — see CONTRIBUTING.md for why that matters.
+      - uses: astral-sh/setup-uv@v6
+
+      - name: Lint
+        run: uv run --only-group dev ruff check .
+
+      - name: Format
+        run: uv run --only-group dev ruff format --check .
+
+  python:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package (editable) + extras
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e '.[report,retry,bundle]'
+
+      - name: Run unit tests
+        run: python -m pytest tests/ --ignore=tests/e2e -q
+
+  player:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: packages/player/package-lock.json
+
+      - name: Install player workspace
+        run: npm --prefix packages/player ci
+
+      - name: Run player tests
+        run: npm --prefix packages/player test
+
+      # The bundles under src/steppy/_player_bundle/ are committed so that
+      # `pip install git+...` needs no Node toolchain. The build is reproducible,
+      # so a mismatch means someone changed packages/player/src/ without
+      # rebuilding and re-vendoring — and every git install would ship the old player.
+      - name: Vendored bundles match the source
+        run: |
+          npm --prefix packages/player run build
+          fail=0
+          for f in steppy-player.js steppy-cursor-legacy.js steppy-video.js; do
+            for g in "$f" "$f.map"; do
+              if ! cmp -s "packages/player/dist/$g" "src/steppy/_player_bundle/$g"; then
+                echo "::error file=src/steppy/_player_bundle/$g::stale vendored bundle — run the player build and copy dist/ into src/steppy/_player_bundle/"
+                fail=1
+              fi
+            done
+          done
+          exit $fail
+
+      # The in-app tour overlay (dist/steppy-tour.js) ships to apps through
+      # npm, not the wheel, so it is not compared above. It has a size budget
+      # instead; the build above already produced it.
+      - name: Tour overlay size budget
+        run: npm --prefix packages/player run size:tour
+
+      # Publish-readiness: every file package.json points at is in the tarball.
+      - name: npm pack contents
+        run: npm --prefix packages/player run check:pack
+
+  # In-app tours in a real browser: the overlay in the demo app (top layer,
+  # focus, keyboard, remote loading with CORS and SRI, a built guide site as
+  # the remote origin) and the generated tour replays — including the one this
+  # feature exists for: a renamed test-id fails the build, naming tour, step
+  # and test-id. happy-dom covers the logic; only Chromium covers this.
+  tour-e2e:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: packages/player/package-lock.json
+
+      - name: Build the tour overlay
+        run: |
+          npm --prefix packages/player ci
+          npm --prefix packages/player run build
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install package (editable) + Chromium
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+          playwright install chromium --with-deps
+
+      - name: Run the tour browser tests
+        env:
+          STEPPY_TOUR_E2E: '1'
+        run: python -m pytest tests/integration/test_tour_replay_it.py tests/integration/test_tour_player_it.py -q
+
+      - name: Keep the failure evidence
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: tour-e2e-failure
+          path: |
+            /tmp/pytest-of-*/pytest-*/**/tests/e2e/**
+            /tmp/pytest-of-*/pytest-*/**/output/**
+          if-no-files-found: ignore
+          retention-days: 7
+
+  # @steppy/angular: the zoneless and the zone.js unit suites, the
+  # ng-packagr build, and what `npm publish ./dist` would ship. The adapter
+  # type-checks against the overlay's declarations, so the player is built first.
+  angular-adapter:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+          cache-dependency-path: |
+            packages/player/package-lock.json
+            packages/angular/package-lock.json
+
+      - name: Build the player
+        run: |
+          npm --prefix packages/player ci
+          npm --prefix packages/player run build
+
+      - name: Test and build the adapter
+        run: |
+          npm --prefix packages/angular ci
+          npm --prefix packages/angular test
+          npm --prefix packages/angular run build
+          npm pack --dry-run ./packages/angular/dist
+
+  # In-app tours in a real Angular + PrimeNG + ngx-translate app, through the
+  # adapter: the plain demo's scenarios and their generated replays run
+  # unchanged against it, plus the router bridge, zone hygiene and i18n.
+  tour-angular-e2e:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+          cache-dependency-path: |
+            packages/player/package-lock.json
+            packages/angular/package-lock.json
+            fixtures/tour-demo-angular/app/package-lock.json
+
+      - name: Build the player, the adapter and the demo
+        run: |
+          npm --prefix packages/player ci
+          npm --prefix packages/player run build
+          npm --prefix packages/angular ci
+          npm --prefix packages/angular run build
+          npm --prefix fixtures/tour-demo-angular/app ci
+          npm --prefix fixtures/tour-demo-angular/app run build
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install package (editable) + Chromium
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+          playwright install chromium --with-deps
+
+      - name: Run the Angular tour browser tests
+        env:
+          STEPPY_TOUR_ANGULAR_E2E: '1'
+        run: python -m pytest tests/integration/test_tour_angular_it.py -q
+
+      - name: Keep the failure evidence
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: tour-angular-e2e-failure
+          path: |
+            /tmp/pytest-of-*/pytest-*/**/tests/e2e/**
+            /tmp/pytest-of-*/pytest-*/**/output/**
+          if-no-files-found: ignore
+          retention-days: 7

steppy_dev-0.3.0/.github/workflows/release.yml

@@ -0,0 +1,200 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+
+jobs:
+  build-and-release:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Verify tag matches all package versions
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          PROJECT_VERSION=$(grep -E '^version = ' pyproject.toml | head -1 | sed -E 's/version = "(.*)"/\1/')
+          TYPES_VERSION=$(python -c "import json;print(json.load(open('packages/steppy/package.json'))['version'])")
+          PLAYER_VERSION=$(python -c "import json;print(json.load(open('packages/player/package.json'))['version'])")
+          ANGULAR_VERSION=$(python -c "import json;print(json.load(open('packages/angular/package.json'))['version'])")
+          echo "Tag:     $TAG_VERSION"
+          echo "pyproject.toml:              $PROJECT_VERSION"
+          echo "packages/steppy/package.json: $TYPES_VERSION"
+          echo "packages/player/package.json: $PLAYER_VERSION"
+          echo "packages/angular/package.json: $ANGULAR_VERSION"
+          fail=0
+          for name_ver in "pyproject.toml=$PROJECT_VERSION" "packages/steppy=$TYPES_VERSION" "packages/player=$PLAYER_VERSION" "packages/angular=$ANGULAR_VERSION"; do
+            name="${name_ver%%=*}"; ver="${name_ver##*=}"
+            if [ "$TAG_VERSION" != "$ver" ]; then
+              echo "::error::Tag $GITHUB_REF_NAME does not match $name version $ver"
+              fail=1
+            fi
+          done
+          [ "$fail" = 0 ]
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: packages/player/package-lock.json
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install player workspace
+        run: npm --prefix packages/player ci
+
+      - name: Build player bundles
+        run: npm --prefix packages/player run build
+
+      # The tour overlay ships through npm only: its size budget and the
+      # package's contents are checked here, before anything is released.
+      - name: Tour overlay size budget and npm pack contents
+        run: |
+          npm --prefix packages/player run size:tour
+          npm --prefix packages/player run check:pack
+
+      - name: Vendor player bundles into Python package
+        run: |
+          cp packages/player/dist/steppy-player.js          src/steppy/_player_bundle/
+          cp packages/player/dist/steppy-player.js.map      src/steppy/_player_bundle/
+          cp packages/player/dist/steppy-cursor-legacy.js   src/steppy/_player_bundle/
+          cp packages/player/dist/steppy-cursor-legacy.js.map src/steppy/_player_bundle/
+          cp packages/player/dist/steppy-video.js           src/steppy/_player_bundle/
+          cp packages/player/dist/steppy-video.js.map       src/steppy/_player_bundle/
+          ls -la src/steppy/_player_bundle/
+
+      - name: Install build tools
+        run: pip install --upgrade build twine
+
+      - name: Build wheel + sdist
+        run: python -m build
+
+      # The README becomes the PyPI project page; a description PyPI cannot
+      # render is refused at upload, after the GitHub Release already exists.
+      - name: Check the metadata PyPI will render
+        run: twine check --strict dist/*
+
+      - name: Verify wheel contains vendored bundles
+        run: |
+          WHEEL=$(ls dist/*.whl | head -1)
+          echo "Inspecting $WHEEL"
+          python -m zipfile -l "$WHEEL" | tee /tmp/wheel-contents.txt
+          for f in steppy-player.js steppy-cursor-legacy.js steppy-video.js THIRD_PARTY_LICENSES.txt; do
+            if ! grep -q "steppy/_player_bundle/$f" /tmp/wheel-contents.txt; then
+              echo "::error::$f missing from wheel"
+              exit 1
+            fi
+          done
+          for f in LICENSE NOTICE; do
+            if ! grep -q "dist-info/licenses/$f" /tmp/wheel-contents.txt; then
+              echo "::error::$f missing from wheel"
+              exit 1
+            fi
+          done
+          # The tour replay helper is copied next to conftest.py by `generate`;
+          # the tour overlay itself is never vendored (it ships through npm).
+          if ! grep -q "steppy/templates/_steppy_tours.py" /tmp/wheel-contents.txt; then
+            echo "::error::templates/_steppy_tours.py missing from wheel"
+            exit 1
+          fi
+          if grep -q "steppy-tour.js" /tmp/wheel-contents.txt; then
+            echo "::error::steppy-tour.js must not be vendored into the wheel"
+            exit 1
+          fi
+
+      # The PyPI job publishes these exact files rather than building again.
+      - name: Keep the distributions for the PyPI job
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-dist
+          path: dist/
+          if-no-files-found: error
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release create "$GITHUB_REF_NAME" \
+            --title "$GITHUB_REF_NAME" \
+            --generate-notes \
+            dist/*.whl dist/*.tar.gz
+
+      - name: PyPI publishing is off
+        if: vars.PYPI_PUBLISH != 'true'
+        run: echo "::notice::The PYPI_PUBLISH repository variable is not 'true'; steppy-dev is not published to PyPI"
+
+  # steppy-dev on PyPI, through Trusted Publishing: PyPI trusts this workflow
+  # in this repository and the `pypi` environment, so no token is stored.
+  # Skipped until the PYPI_PUBLISH repository variable is 'true', which is set
+  # once the trusted publisher exists (CONTRIBUTING.md, "Releasing").
+  publish-pypi:
+    needs: build-and-release
+    if: vars.PYPI_PUBLISH == 'true'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/steppy-dev/
+    permissions:
+      id-token: write  # Trusted Publishing
+    # Every step here can mint the token that uploads to PyPI, so each action
+    # is pinned to a commit rather than a tag its owner could move.
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4.3.0
+        with:
+          name: python-dist
+          path: dist/
+
+      - name: Publish steppy-dev
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33  # v1.14.2
+
+  # @steppy/player (the guide player and the in-app tour overlay) and
+  # @steppy/angular. Skipped until an NPM_TOKEN secret exists; the player
+  # goes first because the adapter names it as a peer at the same version.
+  publish-npm:
+    needs: build-and-release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write  # npm provenance
+    env:
+      NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+    steps:
+      - name: No npm token
+        if: env.NODE_AUTH_TOKEN == ''
+        run: echo "::notice::NPM_TOKEN is not set; the npm packages are not published"
+
+      - uses: actions/checkout@v4
+        if: env.NODE_AUTH_TOKEN != ''
+
+      - uses: actions/setup-node@v4
+        if: env.NODE_AUTH_TOKEN != ''
+        with:
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Build the player and the Angular adapter
+        if: env.NODE_AUTH_TOKEN != ''
+        run: |
+          npm --prefix packages/player ci
+          npm --prefix packages/player run build
+          npm --prefix packages/player run check:pack
+          npm --prefix packages/angular ci
+          npm --prefix packages/angular run build
+
+      - name: Publish @steppy/player
+        if: env.NODE_AUTH_TOKEN != ''
+        run: npm publish ./packages/player --provenance --ignore-scripts
+
+      - name: Publish @steppy/angular
+        if: env.NODE_AUTH_TOKEN != ''
+        run: npm publish ./packages/angular/dist --provenance