scriptcast 0.1.0__tar.gz → 0.3.0__tar.gz

scriptcast-0.3.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,38 @@
+---
+name: Bug report
+about: Something isn't working
+labels: bug
+---
+
+## Describe the bug
+
+<!-- A clear description of what the bug is. -->
+
+## Steps to reproduce
+
+1. Script content (`.sh` file):
+
+```sh
+# paste your script here
+```
+
+2. Command run:
+
+```bash
+scriptcast ...
+```
+
+3. Expected behaviour:
+
+4. Actual behaviour:
+
+## Environment
+
+- scriptcast version: <!-- `pip show scriptcast` -->
+- Python version: <!-- `python --version` -->
+- OS:
+- Shell:
+
+## .sc file (if available)
+
+<!-- Attach or paste the `.sc` file generated before the error, if relevant. -->

scriptcast-0.3.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,25 @@
+---
+name: Feature request
+about: Suggest a new directive or capability
+labels: enhancement
+---
+
+## Use case
+
+<!-- What are you trying to do that scriptcast doesn't support today? -->
+
+## Proposed directive syntax
+
+<!-- If this is a new directive, show how it would look in a script: -->
+
+```sh
+: SC myfeature arg1 arg2
+```
+
+## Expected behaviour in the cast
+
+<!-- What should the generated cast look like? -->
+
+## Alternatives considered
+
+<!-- Any workarounds or alternative approaches you've thought of? -->

scriptcast-0.3.0/.github/pull_request_template.md

@@ -0,0 +1,14 @@
+## What does this PR do?
+
+<!-- One sentence summary. -->
+
+## Checklist
+
+- [ ] `make all` passes locally (lint + typecheck + tests)
+- [ ] New behaviour is covered by tests
+- [ ] `DIRECTIVES.md` updated (if directive added or changed)
+- [ ] `CHANGELOG.md` has an entry (or I'm relying on the auto-changelog PR)
+
+## Related issues
+
+<!-- Closes #123 -->

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

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+    branches: [main, dev]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install ruff
+      - run: ruff check .
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      - run: mypy scriptcast/
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest --cov=scriptcast --cov-report=xml
+      - uses: codecov/codecov-action@v4
+        if: matrix.python-version == '3.12'
+        with:
+          files: coverage.xml
+          fail_ci_if_error: false

scriptcast-0.3.0/.github/workflows/publish-pages.yml

@@ -0,0 +1,51 @@
+# Sample workflow for building and deploying a Jekyll site to GitHub Pages
+name: Deploy GitHub Pages
+on:
+  workflow_run:
+    workflows: ["Publish to PyPI"]
+    types: [completed]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    if: ${{ github.event.workflow_run.conclusion == 'success' || github.event_name == 'workflow_dispatch' }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - name: Build with Jekyll
+        uses: actions/jekyll-build-pages@v1
+        with:
+          source: ./
+          destination: ./_site
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

scriptcast-0.3.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,26 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

scriptcast-0.3.0/.gitignore

@@ -0,0 +1,180 @@
+# Created by https://www.toptal.com/developers/gitignore/api/python
+# Edit at https://www.toptal.com/developers/gitignore?templates=python
+
+### Python ###
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+### Python Patch ###
+# Poetry local configuration file - https://python-poetry.org/docs/configuration/#local-configuration
+poetry.toml
+
+# ruff
+.ruff_cache/
+
+# LSP config files
+pyrightconfig.json
+
+# End of https://www.toptal.com/developers/gitignore/api/python
+
+# Git worktrees
+.worktrees/
+uv.lock

scriptcast-0.3.0/CHANGELOG.md

@@ -0,0 +1,58 @@
+## [0.3.0] - 2026-04-07
+
+### Added
+
+- Fix default theme loading and zsh xtrace ESC byte corruption ([#1](https://github.com/dacrystal/scriptcast/issues/1))
+
+## [0.2.0] - 2026-04-06
+
+### Added
+
+- Add --version, ASCII banner, hatch-fancy-pypi-readme, and GitHub Pages workflow
+
+## [0.1.0] - 2026-04-06
+
+### Added
+
+- SC mock/expect directives, InputLine event, single-cast default
+- Add expect example to basic.sh; fix recorder cwd and send_user newline
+- JSONL .sc format, streaming generator, expect session improvements
+- FilterDirective subprocess command; add CommentDirective
+- Open source readiness — directive plugin system, CLI fix, CI/CD, community files
+- Typing_word_speed, GIF frame overlay, dev tooling
+- Frame layout system with CLI flags for title bar, shadow, background, and watermark
+- Add theme system, scriptcast watermark, and frame layout refactor
+- SVG-based chrome renderer with APNG output support
+- PIL fallback frame parity — content masking, APNG, GIF palette fix
+- Replace gif subcommand with export — content-first compositor
+- Add terminal content pre-processing pipeline
+- Frame bool, dark theme full config, CLI cleanup, DM Sans watermark
+- CLI simplification
+- Export format png, temp gif, aurora/light themes, aurora FrameConfig defaults
+- Complete basic.sh, README demo, and xtrace quoting fixes
+- Unify config pipeline — ThemeConfig nested in ScriptcastConfig, theme.py deleted
+- *(examples)* Redesign demo — showcase.sh, tutorial.sh, fake-myapp
+- Multi-pass directive pipeline redesign
+- Verbatim xtrace capture + PTY recording
+- Unified CLI — single entry point, --no-export flag, config resolved before recording
+- HelpersDirective + PTY read simplification + three bug fixes
+- --xtrace-log flag + export progress bar + frame-bar-title fix
+
+### Changed
+
+- Remove _handle_passthrough; directives own SC syntax matching
+- Replace SVG chrome rendering with PIL-only chrome+mask approach
+- Codebase cleanup and best-practices refactor
+
+### Fixed
+
+- CI test failure and ruff lint errors from recent features
+- Ignore missing PIL stubs in mypy (Pillow is optional)
+- Stable GIF palette across frames — eliminates chrome color flickering
+- Reserve palette slots for exact chrome colors in GIF output
+- Frame rendering bug fixes — shadow, border, theme parsing, SVG filter
+- Decode \xNN and \NNN escape sequences in SC directive xtrace lines
+- *(filter)* Apply filter to trace/cmd lines and decouple from ExpectDirective
+- Resolve CI test failures
+- Resolve all mypy errors in scriptcast/
+

scriptcast-0.3.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,41 @@
+# 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, caste, color, 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:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information without explicit permission
+* Other conduct which could reasonably be considered inappropriate
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainer at dacrystal@users.noreply.github.com.
+All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

scriptcast-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing to scriptcast
+
+## Dev Setup
+
+```bash
+git clone https://github.com/dacrystal/scriptcast.git
+cd scriptcast
+pip install -e ".[dev]"
+```
+
+## Running Tests
+
+```bash
+make test          # pytest with coverage
+make lint          # ruff
+make typecheck     # mypy
+make all           # all three
+```
+
+All three must pass before opening a PR. CI enforces this.
+
+## Commit Messages
+
+Use conventional commits — the changelog is generated from them:
+
+- `feat: add SC highlight directive`
+- `fix: expect session drops last output line`
+- `docs: clarify filter-add chaining`
+- `chore: bump ruff version`
+
+## Writing a Directive
+
+See [DIRECTIVES.md](DIRECTIVES.md) for the full guide.
+
+## Pull Request Checklist
+
+- [ ] Tests pass locally (`make all`)
+- [ ] New behaviour is covered by tests
+- [ ] CHANGELOG.md has an entry (or the auto-PR from CI will add one)
+- [ ] DIRECTIVES.md updated if you added or changed a directive
+
+## Release Process (maintainers only)
+
+1. Ensure `CHANGELOG.md` is up to date
+2. Bump version in `pyproject.toml`
+3. `git tag v0.X.0 && git push --tags`
+4. The `release.yml` workflow publishes to PyPI and creates a GitHub Release
+
+PyPI uses Trusted Publisher (OIDC) — no API key needed. Configure at:
+pypi.org → your project → Publishing → Add publisher (environment: `release`)

scriptcast-0.3.0/DIRECTIVES.md

@@ -0,0 +1,163 @@
+# Writing Directives
+
+Directives are the extension point in scriptcast. Each directive is a Python
+class that participates in one or more of the three pipeline phases:
+
+| Phase | Method | When it runs |
+|-------|--------|-------------|
+| Pre | `pre(queue)` | Before the shell script is executed — rewrites script lines |
+| Post | `post(queue)` | After execution — transforms raw xtrace lines into JSONL events |
+| Gen | `gen(event, queue, active, cursor)` | During cast generation — emits asciinema cast lines |
+
+A directive can implement any combination of these phases by overriding the
+corresponding method. The base `Directive` class provides no-op defaults for all
+three, so you only override what you need.
+
+## The Directive Base Class
+
+```python
+from scriptcast.directives import Directive
+
+class MyDirective(Directive):
+    priority: int = 50        # lower = runs earlier in the chain
+    handles: str | None = None  # gen phase only: directive name in .sc events
+```
+
+### priority
+
+Directives are sorted by `priority` before being placed in the processing chain.
+Lower values run first. Core directive priorities:
+
+| Directive | Priority | Notes |
+|-----------|----------|-------|
+| RecordDirective | 10 | Must absorb pause/resume before anything else |
+| MockDirective | 20 | Must absorb mock markers before expect or sc catch them |
+| ExpectDirective | 30 | Owns all lines in an expect session; must precede filter |
+| FilterDirective | 40 | Applies to output lines after expect releases them |
+| CommentDirective | 45 | Must precede ScDirective (catch-all) |
+| SetDirective | 50 | Gen phase only |
+| SleepDirective | 50 | Gen phase only |
+| ScDirective | 99 | Catch-all for any remaining `: SC` line — always last |
+
+Pick a priority between 50 and 98 for most new directives.
+
+### handles
+
+Used in the gen phase only. Set `handles = "myname"` and your directive's `gen()`
+method will be called when a `directive` event with text `myname ...` appears in the
+`.sc` file. If `handles` is `None`, `gen()` is never called automatically.
+
+## Phase Details
+
+### pre(queue: deque[str]) → list[str] | None
+
+Called for each line of the script before it is run. The queue contains the
+remaining unprocessed script lines.
+
+- **Return None** if this line is not for you — the next directive gets a chance.
+- **Return a list of strings** (replacement lines) to consume from the queue and
+  substitute. You are responsible for `queue.popleft()` on lines you consume.
+
+```python
+def pre(self, queue):
+    if not queue[0].startswith(f": {self.dp} mything"):
+        return None
+    queue.popleft()
+    return ["echo 'replaced'\n"]
+```
+
+### post(queue: deque[tuple[float, str]]) → list[str] | None
+
+Called for each (timestamp, content) item in the raw xtrace output. The queue
+contains remaining unprocessed items.
+
+- **Return None** if this item is not for you.
+- **Return a list of JSONL strings** (or `[]` to consume without emitting).
+- Use `json.dumps([ts, "cmd"|"output"|"input"|"directive", text])` to produce events.
+
+```python
+import json
+
+def post(self, queue):
+    ts, content = queue[0]
+    if content != f"{self.tp} : {self.dp} mything":
+        return None
+    queue.popleft()
+    return [json.dumps([ts, "directive", "mything"])]
+```
+
+### gen(event, queue, active, cursor) → tuple[float, list[str]]
+
+Called during cast generation when a `directive` event matches `self.handles`.
+
+- `event` — `(timestamp: float, "directive", text: str)`
+- `queue` — remaining events (you may peek/consume ahead)
+- `active` — current `ScriptcastConfig` (mutable — you can change timing settings)
+- `cursor` — current time position in the cast (seconds)
+- **Return** `(updated_cursor, list_of_cast_json_lines)`
+
+```python
+import json
+
+class MySleepDirective(Directive):
+    handles = "mysleep"
+
+    def gen(self, event, queue, active, cursor):
+        _, _, text = event
+        parts = text.split()
+        if len(parts) >= 2:
+            cursor += int(parts[1]) / 1000.0
+        return cursor, []
+```
+
+## Registering a Third-Party Directive
+
+In your package's `pyproject.toml`:
+
+```toml
+[project.entry-points."scriptcast.directives"]
+my-directive = "mypkg.directives:MyDirective"
+```
+
+After `pip install` your package alongside scriptcast, your directive is
+automatically loaded and sorted into the processing chain by priority.
+
+## Worked Example: SC pause directive
+
+This adds a `SC pause <ms>` recorder directive that inserts a `sleep` event
+into the `.sc` file, causing the generator to pause for the given milliseconds.
+
+```python
+# mypkg/directives.py
+import json
+import re
+from scriptcast.directives import Directive
+
+
+class PauseDirective(Directive):
+    """SC pause <ms> — insert a pause into the cast.
+
+    Script syntax:  : SC pause 500
+    Records as:     [ts, "directive", "sleep 500"]
+    """
+    priority = 48  # between CommentDirective (45) and ScDirective (99)
+
+    def __init__(self, dp="SC", tp="+"):
+        super().__init__(dp, tp)
+        self._re = re.compile(rf"^{re.escape(tp)} : {re.escape(dp)} pause (\d+)$")
+
+    def post(self, queue):
+        ts, content = queue[0]
+        m = self._re.match(content)
+        if not m:
+            return None
+        queue.popleft()
+        ms = m.group(1)
+        return [json.dumps([ts, "directive", f"sleep {ms}"])]
+```
+
+```toml
+# mypkg/pyproject.toml
+[project.entry-points."scriptcast.directives"]
+pause = "mypkg.directives:PauseDirective"
+```