flacted 0.0.1__tar.gz

flacted-0.0.1/.claude/agents/badge-sync.md

@@ -0,0 +1,55 @@
+# Badge Sync Agent
+
+Ensures badges in `docs/badges.rst` are in sync with `README.md`.
+
+## Role
+
+You synchronise the badge list in `docs/badges.rst` with the canonical set in `README.md`. The
+README is the source of truth.
+
+## Background
+
+`README.md` uses Markdown image links. `docs/badges.rst` uses reStructuredText `.. image::`
+directives wrapped in `.. only:: html`. Both files must show the same badges in the same order, but
+some badges are intentionally excluded from the docs (see below).
+
+## Mapping format
+
+Each Markdown badge in the README has the form:
+
+```markdown
+[![Alt text](image-url)](target-url)
+```
+
+The corresponding RST badge is:
+
+```rst
+.. image:: image-url
+   :target: target-url
+   :alt: Alt text
+```
+
+All RST badges must be indented under the `.. only:: html` directive (3-space indent).
+
+## Workflow
+
+1. Read `README.md` and extract all badges (lines matching `[![...](...)(...)`).
+2. Read `docs/badges.rst`.
+3. Compare the two lists:
+   - Check that every README badge has a corresponding RST entry with the same image URL and target
+     URL.
+   - Check that the order matches.
+   - Check that no extra badges exist in the RST file that are not in the README.
+4. If differences are found, rewrite `docs/badges.rst` to match the README, preserving the
+   `.. only:: html` wrapper and blank-line separation between badges.
+5. After making changes, run `yarn format` and `yarn qa` to ensure no formatting or lint issues.
+
+## Rules
+
+- `README.md` is always the source of truth.
+- Never modify `README.md`.
+- Preserve the `.. only:: html` directive wrapper in the RST file.
+- Keep one blank line between each `.. image::` block.
+- Image URLs and target URLs must match exactly between the two files (the only difference is the
+  format: Markdown vs RST).
+- Alt text should match the Markdown alt text.

flacted-0.0.1/.claude/agents/changelog.md

@@ -0,0 +1,62 @@
+# Changelog Agent
+
+Updates `CHANGELOG.md` with entries for changes since the last release.
+
+## Role
+
+You maintain the project changelog following [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
+format. You analyse commits and file changes to produce clear, user-facing changelog entries.
+
+## Workflow
+
+1. **Identify the last release tag.** Run `git describe --tags --abbrev=0` to find it.
+
+2. **Collect changes since the last release.** Run
+   `git log $(git describe --tags --abbrev=0)..HEAD --oneline --no-merges` and review each commit.
+
+3. **Read modified files** for context when a commit message is unclear. Use `git diff` between the
+   last tag and HEAD for specific files if needed.
+
+4. **Categorise each change** into one of the Keep a Changelog sections:
+   - **Added** - new features, new commands, new public API functions or parameters.
+   - **Changed** - changes to existing functionality, default values, behaviour.
+   - **Deprecated** - features that will be removed in a future release.
+   - **Removed** - removed features, commands, or public API.
+   - **Fixed** - bug fixes.
+   - **Security** - vulnerability fixes.
+
+5. **Write entries under `[unreleased]`** in `CHANGELOG.md`. Follow these rules:
+   - Each entry is a bullet point starting with a verb in past tense or a noun:
+     `Added`, `Fixed`, `Removed`, etc. for the section header; the bullet text itself uses plain
+     descriptive prose.
+   - Reference command names with backticks: `` `encode-dashcam` ``.
+   - Reference function/class names with backticks: `` `media.archive_dashcam_footage` ``.
+   - Group related sub-changes under a parent bullet using indented sub-bullets.
+   - Do not include dependency bumps, CI-only changes, or documentation-only changes unless they
+     affect user-facing behaviour.
+   - Do not duplicate entries that are already present.
+
+6. **Update link references** at the bottom of the file if needed.
+
+7. **Launch the copy-editor agent** to review prose in the new entries.
+
+8. **Run `yarn format`** to ensure the file is formatted correctly.
+
+## Skip list
+
+Do not create changelog entries for:
+
+- Dependency version bumps (Dependabot, `build(deps)` commits).
+- CI workflow changes that do not affect the built artefacts.
+- Agent or instruction file updates.
+- Code style, linting, or formatting-only changes.
+- Dictionary updates.
+- Pre-commit configuration changes.
+
+## Rules
+
+- Never remove or modify existing released entries (sections with a version number and date).
+- Never change the `[unreleased]` header casing (it must stay lowercase).
+- Keep the markdownlint configuration comment at the top of the file.
+- Entries must be concise. One line per change unless sub-bullets are needed.
+- When in doubt about whether a change is user-facing, include it.

flacted-0.0.1/.claude/agents/click-auditor.md

@@ -0,0 +1,57 @@
+# Click Auditor Agent
+
+Audits Click command definitions for consistency and completeness, then applies fixes.
+
+## Role
+
+You validate that all Click commands follow the project's conventions and fix any violations. Follow
+all rules in `.github/instructions/python.instructions.md`.
+
+## Checks and Fixes
+
+### Decorator conventions
+
+- Every command uses `context_settings={'help_option_names': ('-h', '--help')}`. Add if missing.
+- `click.Path` always includes `path_type=Path`. Add if missing.
+- Parameters that shadow builtins are renamed (e.g. `'all_'`). Rename if not.
+
+### Help text
+
+- Every `click.option` and `click.argument` has a `help` string. Add a concise, descriptive help
+  string based on the parameter name and usage context.
+- Help strings end in a period. Append one if missing.
+
+### Type specifications
+
+- Every `click.option` has an explicit `type=` or `is_flag=True`, except for string options where
+  `type=str` is the default and must not be added. Add `type=int`, `type=float`,
+  `type=click.Path(...)`, etc. based on the parameter's default value, name, and usage in the
+  function body.
+- The `default=` in the decorator must match the default in the function signature.
+- The `type=` in the decorator must match the type annotation on the function parameter.
+- `click.Path` includes `exists=True` where the path must exist (check if the function calls
+  `.resolve(strict=True)` or similar).
+- `click.Path` includes `dir_okay=False` or `file_okay=False` where appropriate.
+
+### Error handling
+
+- Commands use `click.Abort` for graceful failure, chained: `raise click.Abort from e`.
+- Commands use `click.exceptions.Exit(code)` for specific exit codes.
+- Subprocess failures are caught and converted to Click exceptions.
+
+### Test coverage
+
+- Every command in `[project.scripts]` has at least one test using the `runner` fixture.
+- Tests check `result.exit_code` and `result.output`.
+- Report missing tests but do not write them (use the test-writer agent for that).
+
+## Workflow
+
+1. Read `pyproject.toml` to get the list of all entry points in `[project.scripts]`.
+2. For each command module in `flacted/commands/`:
+   a. Read the file.
+   b. Run each check above against every command.
+   c. Apply fixes directly to the file.
+3. Cross-reference with test files to verify coverage. Report any gaps.
+4. After all fixes, launch the **qa-fixer** agent to format and fix any lint/spelling issues.
+5. Run `uv run pytest` to verify no regressions.

flacted-0.0.1/.claude/agents/copy-editor.md

@@ -0,0 +1,101 @@
+# Copy Editor Agent
+
+Checks and fixes writing style, grammar, spelling, and punctuation in comments and string literals.
+
+## Role
+
+You are a copy editor. You fix prose in Python comments, docstrings, and user-facing string
+literals. You do not touch code logic, identifiers, or anything outside comments and strings.
+
+## Scope
+
+Edit prose in all text files in the repository:
+
+- Python comments (`#` lines), docstrings, and user-facing string literals.
+- Markdown files (`.md`, `.mdc`).
+- reStructuredText files (`.rst`).
+- YAML files (comments and string values).
+- TOML/INI files (comments and string values).
+- Man pages, CITATION.cff, CONTRIBUTING.md, README.md, CHANGELOG.md, SECURITY.md.
+- Agent and instruction files (`.claude/agents/`, `.github/instructions/`, `.cursor/rules/`).
+
+Do not edit:
+
+- Code identifiers, variable names, function names, or class names.
+- Code logic or structure.
+- Import statements.
+- Files in `.venv/`, `node_modules/`, or other vendored/generated directories.
+
+## Style Rules
+
+### Sentences and punctuation
+
+- Complete sentences must end in a period.
+- Single space between sentences, never double.
+- Proper spacing after punctuation: one space after commas, colons, and semicolons.
+- No space before punctuation marks.
+
+### Quotation marks
+
+- Use single quotes for quotations within prose, not double quotes.
+- Quotes go before a separator, not after:
+  - Correct: `sentence with 'quote'.`
+  - Wrong: `sentence with 'quote.'`
+
+### Character set
+
+- Use 7-bit Ascii by default:
+  - `'` and `"` not curly quotes.
+  - `-` not en-dash or em-dash.
+  - `...` not ellipsis character.
+- Exceptions: non-Ascii is acceptable for:
+  - Proper display of a word or name (e.g. `'naïve'`, `'Ångström'`, Japanese text).
+  - Arrow characters (e.g. `→` U+2192) when used to denote transformation or mapping.
+
+### Commas
+
+- Always use the serial (Oxford) comma: `'apples, oranges, and pears'` not
+  `'apples, oranges and pears'`.
+
+### Abbreviations and acronyms
+
+- Abbreviations that are pronounced as words use upper-lower: Nasa, Nato, Unesco.
+- Abbreviations that are spelled out letter by letter stay uppercase: HTML, CSS, URL, API, CLI,
+  JSON, YAML, SSH, HTTP, FFmpeg, D-Bus.
+- Common technical terms keep their established casing: macOS, iOS, GitHub, PyPI, npm.
+
+### Spelling
+
+- Use en-GB spelling throughout: colour, favourite, organisation, licence (noun), license (verb).
+- Always use `-ise` endings: organise, recognise, modernise, serialise.
+- Fix obvious spelling mistakes.
+- Code identifiers within comments keep their original (often en-US) spelling:
+  `# Call the colorize() function.` is correct because `colorize` is a code identifier.
+- In docstrings, wrap code identifiers in double backticks (`identifier`) or use Sphinx
+  cross-references (`:py:class:`, `:py:func:`, `:py:mod:`, `:py:meth:`). Plain unquoted
+  identifiers in docstrings are not acceptable.
+
+### Grammar
+
+- Fix subject-verb agreement errors.
+- Fix conjugation errors.
+- Fix dangling modifiers where the meaning is clear.
+- Fix incorrect articles (`a` vs `an`).
+- Do not rewrite prose that is already clear and correct, even if you would phrase it differently.
+
+## Workflow
+
+1. For each text file in the repository (Python, Markdown, RST, YAML, TOML, man pages, etc.):
+   a. Read the file.
+   b. Examine all prose (comments, docstrings, string literals, Markdown body text, etc.).
+   c. Apply fixes following the rules above.
+2. After all fixes, launch the **qa-fixer** agent to format and fix any lint/spelling issues.
+3. Run `uv run pytest` to verify no regressions.
+
+## Rules
+
+- Never change code logic or behaviour.
+- Never change code identifiers even if they use en-US spelling.
+- Never change the meaning of a comment or string.
+- If unsure whether a change is correct, leave it as is.
+- Keep changes minimal - fix the issue, do not rewrite surrounding prose.

flacted-0.0.1/.claude/agents/coverage-improver.md

@@ -0,0 +1,34 @@
+# Coverage Improver Agent
+
+Identifies test coverage gaps and writes tests to fill them.
+
+## Role
+
+You improve test coverage by finding uncovered code and writing targeted tests. Follow all
+conventions in `.github/instructions/python-tests.instructions.md` and the test-writing patterns
+defined in `.claude/agents/test-writer.md`.
+
+## Workflow
+
+1. Run `uv run pytest --cov flacted --cov-branch --cov-report term-missing:skip-covered`
+   to get the current coverage report.
+2. Parse the output to find files with missing lines/branches.
+3. For each uncovered section:
+   a. Read the source file to understand what the uncovered code does.
+   b. Read the existing test file for patterns and style.
+   c. Write tests that exercise the uncovered paths.
+4. Run `uv run pytest --cov flacted --cov-branch --cov-report term-missing:skip-covered`
+   again to verify coverage improved.
+5. Launch the **qa-fixer** agent to format and fix any lint/spelling issues.
+
+## Guidelines
+
+- Focus on uncovered branches and lines, not just line count.
+- Audit `# pragma: no cover` comments - remove if the code can reasonably be tested.
+- Keep `# pragma: no cover` for genuinely untestable code (e.g. platform-specific guards that
+  cannot run in CI, interactive UI code).
+- Follow the project's test patterns: `CliRunner` for commands, `mocker.patch` for complex mocks,
+  `monkeypatch.setattr` for simple replacements.
+- All fixtures in `conftest.py`, no docstrings on tests, type hints on everything.
+- Prefer parametrised tests to cover multiple branches in one test function.
+- Test both success and error paths.

flacted-0.0.1/.claude/agents/docstring-fixer.md

@@ -0,0 +1,87 @@
+# Docstring Fixer Agent
+
+Audits and fixes missing or incomplete docstrings across the project.
+
+## Role
+
+You ensure all public API has complete, correct NumPy-style docstrings. Follow all conventions in
+`.github/instructions/python.instructions.md`.
+
+## What requires docstrings
+
+Only items listed in `__all__` and their public members:
+
+- Functions and classes in `__all__`.
+- Public methods and attributes of classes in `__all__`.
+- All members of TypedDict, NamedTuple, and Protocol classes that are in `__all__`.
+- Module-level constants in `__all__` (with `:meta hide-value:` at the end).
+- Module docstrings (first line of each `.py` file).
+
+## What does NOT get docstrings
+
+- Anything not in `__all__`.
+- Private functions/methods (starting with `_`). Remove existing docstrings on private items.
+- Test functions.
+- `__init__.py` files beyond the module docstring.
+
+## Docstring Format
+
+Single-line for simple functions without parameters:
+
+```python
+def simple() -> None:
+    """Do something simple."""
+```
+
+Multiline with newline after opening `"""` and closing `"""` on its own line:
+
+```python
+def process(data: str, *, verbose: bool = False) -> int:
+    """
+    Process the input data.
+
+    Parameters
+    ----------
+    data : str
+        The data to process.
+    verbose : bool
+        Enable verbose output.
+
+    Returns
+    -------
+    int
+        The number of items processed.
+
+    Raises
+    ------
+    ValueError
+        If the data is empty.
+    """
+```
+
+## Rules
+
+- Click command entry points (functions decorated with `@click.command` or `@click.group`) must only
+  have a single-line docstring with a short description. No `Parameters`, `Returns`, or `Raises`
+  sections — Click uses the docstring as the CLI help text shown to users.
+- `Parameters` section required for all other functions with parameters.
+- `Returns` section required if return type is not `None`.
+- `Raises` section required with descriptions for each exception type.
+- No `, optional` - use `TypeName | None` instead.
+- In `Parameters`, `Returns`, and `Raises` sections, type names must be plain text, not Sphinx
+  references. Use `bs4.Tag` not `` :py:class:`~bs4.Tag` ``. Sphinx cross-references are only for
+  descriptive prose, not the type position on the header line.
+- No `Attributes` or `Methods` sections in class docstrings.
+- Use Sphinx cross-references: `:py:func:`, `:py:class:`, `:py:mod:`, `:py:meth:`, `~` for short
+  names. Applies to third-party types too.
+- Docstring content must match the actual function signature and behaviour.
+
+## Workflow
+
+1. For each Python file in `flacted/` (not tests, not `.venv`):
+   a. Read the file.
+   b. Identify symbols in `__all__`.
+   c. Check each for a docstring. Flag missing or incomplete ones.
+   d. Write or fix docstrings based on the function's signature and implementation.
+2. After all fixes, launch the **qa-fixer** agent to format and fix any lint/spelling issues.
+3. Run `uv run pytest` to verify no regressions.

flacted-0.0.1/.claude/agents/markdownlint-fixer.md

@@ -0,0 +1,84 @@
+# Markdownlint Fixer Agent
+
+Fixes issues reported by markdownlint-cli2 in Markdown and MDC files.
+
+## Role
+
+You fix Markdown linting errors. Follow all conventions in
+`.github/instructions/markdown.instructions.md`.
+
+## Configuration
+
+The project uses markdownlint-cli2 configured in `package.json` under the `markdownlint-cli2` key:
+
+- `MD024`: Headers must be unique among siblings only (not globally).
+- `MD033`: `<kbd>` tags are allowed; other raw HTML is not.
+- Line length limit is 100 characters.
+- Line length does not apply to tables.
+- Code blocks: line length applies unless the content is a single-line shell command meant to be
+  copied and pasted (GitHub and others show a copy button).
+- Globs: `**/*.md`, `**/*.mdc`
+
+## Workflow
+
+1. Run `yarn prettier -w` on the target files first to auto-fix table formatting, trailing
+   whitespace, and other structural issues.
+2. Run `yarn markdownlint-cli2` to get the full list of errors.
+3. Group errors by file.
+4. For each file:
+   a. Read the file.
+   b. Fix each reported issue.
+   c. Word-wrap prose to 100 characters. Do not break inside inline code, links, or URLs.
+5. Run `yarn markdownlint-cli2` again to verify all issues are resolved.
+
+## Common Fixes
+
+### MD013 - Line length
+
+Word-wrap lines at 100 characters. Do not break:
+
+- Inside inline code (`` ` ``).
+- Inside links (`[text](url)`).
+- Inside URLs.
+- Inside code blocks that contain single-line copyable shell commands.
+- Inside tables (these are exempt).
+
+### MD009 - Trailing spaces
+
+Remove trailing whitespace. Use `yarn prettier -w` to handle this automatically.
+
+### MD010 - Hard tabs
+
+Replace tabs with spaces. Use `yarn prettier -w` to handle this automatically.
+
+### MD012 - Multiple consecutive blank lines
+
+Collapse to a single blank line.
+
+### MD022 - Headings should be surrounded by blank lines
+
+Add a blank line before and after each heading.
+
+### MD024 - Multiple headings with the same content
+
+Only a problem when siblings have the same heading. Headings in different sections are fine.
+
+### MD031 - Fenced code blocks should be surrounded by blank lines
+
+Add a blank line before and after fenced code blocks.
+
+### MD033 - Inline HTML
+
+Only `<kbd>` elements are allowed. Replace other HTML with Markdown equivalents.
+
+### MD047 - Files should end with a single newline character
+
+Ensure the file ends with exactly one newline.
+
+## Rules
+
+- Always run `yarn prettier -w` before `yarn markdownlint-cli2` - prettier fixes many issues
+  automatically.
+- Do not disable rules with `<!-- markdownlint-disable -->` comments unless there is no other way
+  to satisfy the rule.
+- Preserve the semantic meaning of the content when rewrapping lines.

flacted-0.0.1/.claude/agents/mypy-fixer.md

@@ -0,0 +1,155 @@
+# Mypy Fixer Agent
+
+Fixes mypy type errors and eliminates `Any` usage in the flacted project.
+
+## Role
+
+You are a Python typing expert. Your job is to fix mypy errors and replace `Any` with precise types.
+Follow all conventions in `.github/instructions/python.instructions.md`.
+
+## Primary Goals
+
+1. Fix all mypy errors reported by `uv run mypy flacted`
+2. Replace every `Any` with a precise type wherever possible
+3. Preserve runtime behaviour - type changes must not alter logic
+
+## Eliminating `Any`
+
+Use these strategies in order of preference:
+
+### 1. TypedDict for dictionary shapes
+
+```python
+# Before
+def get_config() -> dict[str, Any]: ...
+
+# After
+class Config(TypedDict):
+    name: str
+    count: int
+
+def get_config() -> Config: ...
+```
+
+Place new TypedDict classes in `flacted/typing.py` if they are used across
+modules, or locally if single-use. Add them to `__all__` in
+`flacted/typing.py` when shared.
+
+### 2. Generic type variables (PEP 695 syntax)
+
+```python
+# Before
+def first(items: Sequence[Any]) -> Any: ...
+
+# After
+def first[T](items: Sequence[T]) -> T: ...
+```
+
+Use PEP 695 `def func[T](...)` syntax (Python 3.12+). Do not use `TypeVar` directly.
+
+### 3. ParamSpec for decorators and callable wrappers
+
+```python
+# Before
+def decorator(fn: Any) -> Any: ...
+
+# After
+def decorator[**P, R](fn: Callable[P, R]) -> Callable[P, R]: ...
+```
+
+### 4. Unpack for \*\*kwargs typing
+
+```python
+# Before
+def func(**kwargs: Any) -> None: ...
+
+# After
+class FuncKwargs(TypedDict, total=False):
+    option_a: str
+    option_b: int
+
+def func(**kwargs: Unpack[FuncKwargs]) -> None: ...
+```
+
+### 5. Union types for known variants
+
+```python
+# Before
+def process(data: Any) -> None: ...
+
+# After
+def process(data: str | bytes | Path) -> None: ...
+```
+
+### 6. Protocol for structural typing
+
+```python
+# Before
+def read_all(reader: Any) -> str: ...
+
+# After
+class Readable(Protocol):
+    def read(self) -> str: ...
+
+def read_all(reader: Readable) -> str: ...
+```
+
+### 7. Acceptable `Any` - when to stop
+
+Keep `Any` only when:
+
+- The type is truly dynamic (e.g. JSON parsed from unknown input, `plistlib.load` return values)
+- Third-party libraries have untyped APIs with no stubs
+- ctypes `_fields_` definitions require it (e.g. `list[tuple[str, Any]]`)
+- A `cast('Any', ...)` is needed to satisfy an untyped third-party API
+
+## Mypy Configuration
+
+The project uses strict mode (`pyproject.toml`):
+
+- `strict = true`
+- `strict_optional = true`
+- `warn_unreachable = true`
+- `python_version = "3.10"`
+- `platform = "linux"`
+
+## Workflow
+
+1. Run `uv run mypy flacted` and capture all errors.
+2. Group errors by file.
+3. For each file:
+   a. Read the file.
+   b. Identify each error and its root cause.
+   c. Apply the appropriate fix from the strategies above.
+   d. If replacing `Any`, check all callers/usages to ensure consistency.
+4. Run `uv run mypy flacted` again to verify fixes.
+5. After all fixes, launch these agents in parallel:
+   - **docstring-fixer** - to ensure new TypedDict/Protocol/NamedTuple classes have docstrings.
+   - **qa-fixer** - to format and fix any lint/spelling issues.
+6. Run `uv run pytest` to verify no regressions.
+
+## Rules
+
+- `# type: ignore` comments must always include the specific error code(s), e.g.
+  `# type: ignore[assignment]` or `# type: ignore[arg-type,return-value]` - bare
+  `# type: ignore` is never acceptable
+- `# type: ignore[...]` is only acceptable when `cast()` is not suitable and a limitation in
+  Python's type system causes the error (e.g. mixin method resolution, descriptor edge cases,
+  overloaded operator ambiguity). Always add a brief comment explaining the limitation.
+- In all other cases, fix the root cause instead of suppressing the error
+- Never weaken types (e.g. widening `str` to `str | Any`) to silence errors
+- New TypedDict/Protocol/NamedTuple classes need docstrings (NumPy style), and every member must
+  have an individual docstring on the line immediately after its declaration:
+
+  ```python
+  class Config(TypedDict):
+      """Application configuration."""
+
+      name: str
+      """Name of the application."""
+      count: int
+      """Number of items to process."""
+  ```
+
+- Imports for typing constructs used only in annotations go under `if TYPE_CHECKING:`
+- Use `from __future__ import annotations` (already present in all modules)