rms-picmaker 1.0.0__tar.gz

rms_picmaker-1.0.0/.cursor/rules/bug_report.mdc

@@ -0,0 +1,79 @@
+---
+description: Standards for writing clear, reproducible bug reports with severity, evidence, and environment details.
+alwaysApply: false
+---
+
+# Bug Report Standards
+
+## 1. Core Components
+
+Every bug report MUST include:
+
+- **Clear title** — Describes the symptom and its location (e.g., "`Profile.from_file` raises KeyError on valid FITS header").
+- **Reproduction steps** — Numbered, minimal steps (ideally a short script) anyone can follow.
+- **Expected vs. actual behavior** — Side-by-side comparison.
+- **Environment** — Python version, OS, package version, relevant dependency versions.
+- **Severity** — Assessed per the scale below.
+- **Evidence** — Tracebacks, log output, or screenshots of incorrect results.
+
+## 2. Severity Scale
+
+| Level | Criteria |
+|-------|----------|
+| **Critical** | Crash, data corruption, silent wrong results, or security vulnerability. |
+| **High** | Major feature broken or blocking for many users. |
+| **Medium** | Non-critical feature broken or produces degraded results. |
+| **Low** | Minor issue, documentation error, or cosmetic problem. |
+| **Trivial** | Very minor issue with negligible user impact. |
+
+## 3. Report Template
+
+```markdown
+# Bug Report: [Concise title]
+
+## Description
+[1-2 sentences: what is broken and its impact.]
+
+## Environment
+- **Python version**: [e.g., 3.12.4]
+- **OS**: [e.g., Ubuntu 24.04, macOS 14.5, Windows 11]
+- **Package version**: [e.g., rms-picmaker 0.3.1]
+- **Key dependency versions**: [e.g., numpy 2.2.1, scipy 1.14.0]
+- **Installation method**: [e.g., pip install rms-picmaker, editable install]
+
+## Severity
+[Level] — [Brief justification]
+
+## Steps to Reproduce
+1. Install: `pip install rms-picmaker==0.3.1`
+2. Run:
+   (Example)
+3. Observe the error.
+
+## Expected Behavior
+[What should happen.]
+
+## Actual Behavior
+[What actually happens, including the full traceback.]
+
+## Traceback / Logs
+[Paste full traceback or relevant log output here]
+
+## Additional Notes
+[Workarounds, frequency, related issues.]
+
+## Possible Fix
+[Optional: suspected root cause or fix direction.]
+```
+
+## 4. Writing Guidelines
+
+1. Be objective and factual — no blame or subjective language.
+2. One issue per report.
+3. Include exact version numbers and full tracebacks.
+4. Keep reproduction steps as short as possible while remaining unambiguous.
+5. Verify the bug is reproducible before submitting.
+
+## 5. Adaptation
+
+Adjust the template for the project's GitHub Issues and add project-specific fields (e.g., affected data set, mission, instrument).

rms_picmaker-1.0.0/.cursor/rules/dependency_management.mdc

@@ -0,0 +1,53 @@
+---
+alwaysApply: true
+description: Standards for declaring, installing, and maintaining Python project dependencies.
+---
+
+# Dependency Management
+
+## 1. Single Source of Truth
+
+- Declare ALL dependencies in **`pyproject.toml`** under `[project]` (PEP 621).
+- Do NOT maintain a separate hand-written `requirements.txt` for runtime dependencies. If a `requirements.txt` is kept, it should contain only `-e .` for backward compatibility.
+
+## 2. Dependency Groups
+
+| Group | Section | Install command | Purpose |
+|-------|---------|-----------------|---------|
+| **Runtime** | `[project].dependencies` | `pip install .` | Required for the package to function. |
+| **Dev** | `[project.optional-dependencies].dev` | `pip install -e ".[dev]"` | Testing, linting, type-checking, coverage. |
+| **Docs** | `[project.optional-dependencies].docs` | `pip install -e ".[docs]"` | Sphinx and documentation extensions. |
+
+## 3. Version Constraints
+
+- Specify **minimum** compatible versions for direct dependencies (e.g., `numpy>=2.2.0`).
+- Do NOT pin exact versions (`==`) in library projects; exact pinning belongs in lock files or application deployments.
+- For dev/docs dependencies, specify minimum versions to ensure consistent tool behavior across contributors.
+
+## 4. Adding or Updating Dependencies
+
+1. Add the dependency to the correct section in `pyproject.toml`.
+2. Run `pip install -e ".[dev]"` (or the relevant group) to verify installation.
+3. Run the full test suite and type-check to confirm compatibility.
+4. Commit the `pyproject.toml` change with a `build:` commit type.
+
+## 5. Security and Maintenance
+
+- Run `pip audit` in CI to catch known vulnerabilities.
+- Enable automated dependency update tooling (Dependabot, Renovate).
+- Review update PRs for breaking changes before merging.
+- Periodically remove unused dependencies to reduce attack surface.
+
+## 6. Tooling Configuration
+
+Consolidate all tool configuration into `pyproject.toml` where supported:
+
+| Tool | Section |
+|------|---------|
+| pytest | `[tool.pytest.ini_options]` |
+| coverage | `[tool.coverage.run]`, `[tool.coverage.report]` |
+| mypy | `[tool.mypy]`, `[[tool.mypy.overrides]]` |
+| ruff | `[tool.ruff]`, `[tool.ruff.lint]` — use explicit `select = [...]` for E, F, W, I, UP, B, SIM, C4, A, N, PT, RUF (see python_best_practices) |
+| setuptools_scm | `[tool.setuptools_scm]` |
+
+Do NOT create separate config files (`.coveragerc`, `.mypy.ini`, `.flake8`, `setup.cfg`) when the tool supports `pyproject.toml`.

rms_picmaker-1.0.0/.cursor/rules/documentation.mdc

@@ -0,0 +1,65 @@
+---
+alwaysApply: true
+description: Standards for Python library documentation using Sphinx, ReadTheDocs, and docstrings.
+---
+
+# Documentation Standards
+
+## 1. Documentation System
+
+- Use **Sphinx** for all project documentation, hosted on **ReadTheDocs**.
+- After any code or doc change, run `sphinx-build` on the full documentation tree and fix all warnings and errors before delivering.
+
+## 2. Documentation Standard
+
+- Always use one space between the period at the end of a sentence and the next sentence.
+- Always use American spelling instead of British spelling (e.g. color instead of colour).
+
+## 3. Required Documentation
+
+| Document | Contents | Keep up-to-date? |
+|----------|----------|-------------------|
+| **Module index** | Every module that exists or is planned (placeholders for future modules). | Yes |
+| **Architecture overview** | Class hierarchy, public API surface, and interface contracts. | Yes |
+| **Install guide** | `pip install` instructions, supported Python versions, optional dependencies. | Yes |
+| **Usage examples** | Common workflows with code snippets and expected output. | Yes |
+| **README** | Project summary, PyPI/ReadTheDocs badges, quickstart, and links to full docs. | Yes |
+
+## 4. Docstrings
+
+- EVERY class, method, function, and module MUST have a descriptive docstring.
+- Follow **PEP 257** using **Google style** with `Parameters:` (not `Args:`).
+- Include `Returns:` and `Raises:` only if there are return values or exceptions raised.
+- Include behavioral notes sufficient to write a black-box test but do not reference the internal details of the code.
+- Wrap docstring text to **90** characters.
+
+## 5. Cross-Reference Completeness
+
+- EVERY mention of a class, method, function, module, attribute, or data
+  constant in narrative prose MUST use the appropriate Sphinx cross-reference
+  role:
+    - `:class:`~nav.path.module.Class``
+    - `:meth:`~nav.path.module.Class.method``
+    - `:func:`~nav.path.module.func``
+    - `:mod:`nav.path.module``
+    - `:attr:`~nav.path.module.Class.attr``
+    - `:data:`~nav.path.module.NAME``
+- Bare CamelCase or `module.symbol` text in narrative prose is a violation,
+  even when wrapped in inline literals (`` `` ``). Inline literals are for
+  YAML/JSON keys, file paths, CLI tokens, and shell snippets — not for API
+  symbols.
+- Cross-references are NOT required (and should be omitted) inside
+  `.. code-block::` directives, `::` literal blocks, Mermaid / other diagram
+  blocks, YAML examples, or section titles.
+- When a class, method, function, module, attribute, or data constant is
+  added, removed, or renamed, every cross-reference to it across the docs
+  tree MUST be updated in the same change. A rename without ref updates is a
+  documentation regression.
+- Validate by building with `sphinx-build -W -b html` (warnings as errors)
+  AND `sphinx-build -n -b html` (nitpicky mode); both MUST succeed with zero
+  warnings before delivering.
+
+## 6. Change Discipline
+
+- Any code change MUST update the relevant docstrings and the README if affected.
+- NEVER leave stale or contradictory documentation. If a feature is removed, remove its docs.

rms_picmaker-1.0.0/.cursor/rules/environment_best_practices.mdc

@@ -0,0 +1,40 @@
+---
+description: Git, CI/CD (GitHub Actions), virtual environments, and tooling for development and publishing.
+alwaysApply: true
+---
+
+# Environment Best Practices
+
+## 1. Source Control
+
+- ALWAYS use **git** for all source code.
+- Commit early and often with meaningful messages (see `git_workflow.mdc`).
+
+## 2. CI/CD
+
+- ALWAYS use **GitHub Actions** for continuous integration and publishing.
+- Every PR MUST pass lint (`ruff`), type-check (`mypy`), test (`pytest`), Markdown lint (`PyMarkdown`), and documentation build (`sphinx-build`) jobs before merge.
+- Pin action versions to a major tag (e.g., `actions/checkout@v6`) to balance stability and security updates.
+- Publishing to PyPI is triggered by creating a GitHub Release from a version tag on `main`.
+
+## 3. Environment Isolation
+
+- ALWAYS use `python -m venv` (or `virtualenv`) to create an isolated virtual environment. Activate it before any `pip install`.
+- NEVER install project dependencies into the system Python.
+- Record the supported Python version range in `pyproject.toml` via `requires-python` (e.g., `>=3.10`).
+- Test across all supported Python versions in CI using a matrix strategy.
+
+## 4. Editor Settings (VSCode / Cursor)
+
+The repository includes `.vscode/settings.json` so all contributors get consistent formatting:
+
+- **Indent**: 4 spaces (no tabs).
+- **Trailing whitespace**: Trimmed on save.
+- **Final newline**: Exactly one newline at end of file; excess trailing blank lines removed on save.
+- **Line length**: Rulers at 80, 90, and 100 characters (max 100 enforced by Ruff).
+
+## 5. Secrets and Configuration
+
+- NEVER commit secrets, tokens, or credentials. Use environment variables or GitHub Secrets.
+- Use `.env` files for local development only; ensure `.env` is in `.gitignore`.
+- Validate required environment variables at startup with clear error messages.

rms_picmaker-1.0.0/.cursor/rules/git_workflow.mdc

@@ -0,0 +1,66 @@
+---
+description: Conventional commits, branching, and PR workflow for source control and code review.
+alwaysApply: false
+---
+
+# Git Workflow
+
+## 1. Commit Messages
+
+Use the **Conventional Commits** format:
+
+```
+<type>[(<scope>)]: <imperative summary>   (50 chars max for subject)
+
+[Optional body — wrap at 72 chars. Explain *what* and *why*, not *how*.]
+
+[Optional footer — e.g., Closes #123, BREAKING CHANGE: description]
+```
+
+### Allowed types
+
+| Type | When to use |
+|------|-------------|
+| `feat` | New user-facing feature or public API addition. |
+| `fix` | Bug fix. |
+| `docs` | Documentation-only change. |
+| `style` | Formatting, whitespace — no logic change. |
+| `refactor` | Code restructure with no behavior change. |
+| `perf` | Performance improvement. |
+| `test` | Adding or updating tests only. |
+| `build` | Build system or dependency change. |
+| `ci` | CI/CD configuration change. |
+| `chore` | Maintenance tasks that don't fit above. |
+
+### Rules
+
+- Subject line MUST be imperative mood ("Add X", not "Added X" or "Adds X").
+- Subject line MUST NOT exceed 50 characters.
+- Do NOT end the subject line with a period.
+- Separate subject from body with a blank line.
+- Body lines MUST NOT exceed 72 characters.
+- Reference related issues in the footer.
+- Each commit MUST represent one logical change. Do NOT mix unrelated changes.
+
+## 2. Branching Strategy
+
+This project uses a simple two-tier branching model:
+
+- **`main`** — Always releasable. Protected; requires PR review and passing CI. Releases are created by tagging commits on `main`.
+- **`feature/<name>`** — New features or enhancements, branched from `main`.
+- **`bugfix/<name>`** — Bug fixes, branched from `main`.
+
+There are NO separate release, hotfix, or develop branches. All work merges back to `main` via pull request.
+
+## 3. Pull Requests and Merging
+
+- ALWAYS create a PR for merging into `main`; direct pushes are prohibited.
+- PRs MUST pass all CI checks (lint, type-check, tests) before merge.
+- Prefer **squash merge** to keep `main` history linear and readable.
+- Delete the source branch after merge.
+
+## 4. Tagging and Releases
+
+- Tag releases on `main` with semantic versioning: `v<MAJOR>.<MINOR>.<PATCH>`.
+- Let `setuptools_scm` derive the package version from tags automatically.
+- Creating a GitHub Release from the tag triggers the PyPI publish workflow.

rms_picmaker-1.0.0/.cursor/rules/how_to.mdc

@@ -0,0 +1,74 @@
+---
+description: Guidelines for writing user-facing how-to documentation with steps, prerequisites, and troubleshooting.
+alwaysApply: false
+---
+
+# How-To Documentation
+
+## 1. Audience and Tone
+
+- Write for **Python users** who are familiar with `pip` and the command line but may not know the library's internals.
+- Use clear, direct language; define domain-specific terms on first use.
+- Focus on what the user needs to do and what they should observe.
+
+## 2. Best Practices
+
+1. **Action-oriented title** — e.g., "How To Process a Cassini Image", not "Image Processing Overview".
+2. **Brief introduction** — 1-3 sentences explaining purpose and value.
+3. **Prerequisites** — Python version, package installation, required data or environment variables.
+4. **Numbered steps** — One action per step in logical order. Include code snippets for API usage or CLI commands.
+5. **Expected results** — State what the user should see after each significant step AND in a summary section at the end. Keep both consistent.
+6. **Troubleshooting** — Common failures (import errors, missing data, version mismatches) and their fixes.
+7. **Related features** — Mention next steps or related guides.
+
+## 3. Document Structure
+
+```markdown
+# How To [Action]
+
+[1-3 sentence introduction explaining purpose and value.]
+
+## Prerequisites
+
+- Python >= 3.10
+- `pip install rms-<package>`
+- [Any required data, environment variables, or configuration]
+
+## Steps
+
+1. Import the module:
+   ```python
+   from package import SomeClass
+   ```
+2. [Action]. You should see [result].
+3. [Action].
+
+## Expected Results
+
+[Summary of the successful end state — expected output, files created, etc.]
+
+## Troubleshooting
+
+- **[Problem]**: [Solution].
+
+## Additional Information
+
+[Tips, performance notes, or links to related guides.]
+```
+
+## 4. Converting Technical Content
+
+When turning docstrings, test scripts, or internal notes into How-To guides:
+
+1. Identify the user-facing feature or workflow.
+2. Determine the target audience (library user, CLI user, contributor).
+3. Extract user actions from technical steps.
+4. Translate internal terminology to user-friendly language.
+5. Add code examples, expected output, and troubleshooting.
+
+## 5. Diagrams and Figures
+
+- **When to use**: Multi-step workflows, data pipelines, or architecture that is clearer as a visual.
+- **Placement**: Inline, immediately after the relevant step or section.
+- **Format**: Prefer Mermaid diagrams (e.g., rendered by Sphinx via `sphinxcontrib-mermaid`) for process flows. Use PNG/SVG for screenshots or data visualizations.
+- **Naming**: Descriptive filenames (e.g., `backplane-pipeline.svg`). Include alt text for accessibility.

rms_picmaker-1.0.0/.cursor/rules/pull_request.mdc

@@ -0,0 +1,43 @@
+---
+description: PR structure, purpose, implementation details, testing evidence, and review checklist.
+alwaysApply: false
+---
+
+# Pull Request Standards
+
+## Scope of review
+
+Treat the PR as a **single unit of change**. The diff to review is the set of all commits on the current branch back to its **immediate root** (the merge-base with the target branch). Consider the net result of those commits together; do **not** comment on differences that exist only between commits within the PR (e.g. "you fixed X in a later commit" or "commit 2 undid part of commit 1"). Review the final state of the branch against the base. Do not explicitly word wrap lines.
+
+## Principles
+
+1. **Descriptive title** — Summarize the change in an imperative sentence (e.g., "Add caching to profile lookup").
+2. **Purpose first** — Explain *why* the change is needed before *how* it was done.
+3. **Scope** — One logical change per PR. Split unrelated changes into separate PRs.
+4. **Testing evidence** — Document automated and manual testing performed.
+5. **Impact assessment** — Note potential effects on the public API, performance, or dependent packages (Potential Impacts section).
+6. **Linked issues** — Reference related GitHub issues using `Closes #NNN` syntax.
+
+## Template
+
+The PR template is in `.github/pull_request_template.md` and is applied automatically when a new PR is opened. Fill out every section:
+
+- **Purpose** — Why the change is needed; link issue with `Closes #NNN`.
+- **Changes / Implementation Details** — What changed and how it was implemented; technical approaches chosen and non-obvious design decisions.
+- **Type of Change** — Check all that apply (bug fix, feature, breaking, refactor, docs, tests, CI/build).
+- **Testing** — Check boxes for unit tests, integration tests, E2E tests run; describe new tests added and manual verification performed.
+- **Potential Impacts** — Public API, backward compatibility, performance, downstream; write "None" if straightforward.
+- **Checklist** — Style, mypy, docs, CHANGES.md, no debug code, no secrets/credentials, no warnings/errors, performance impact assessed, breaking changes flagged.
+- **Notes** — Optional; delete only if not needed (tricky areas, follow-up work).
+
+## Guidance
+
+- **Library-specific** — Call out public API changes, deprecations, and migration notes in Potential Impacts.
+- **Required reviewers** — Tag maintainers for changes to core modules.
+- **Brevity vs. completeness** — Short enough that authors fill everything out; detailed enough for a reviewer with no other context.
+- **Format** - Do not explicitly wrap lines.
+
+## Action
+
+- **Writing a PR description** - When asked to write a PR description, always output the result to a Markdown file called PR_DESCRIPTION.md in the repo root.
+- **Opening a PR** - When asked to open a PR, write the description to a temporary file and then open the PR on GitHub using that description text.

rms_picmaker-1.0.0/.cursor/rules/python_best_practices.mdc

@@ -0,0 +1,145 @@
+---
+alwaysApply: true
+description: Python coding standards for writing correct, readable, maintainable, and well-tested library code.
+---
+
+# Python Best Practices
+
+Apply these rules to ALL new and modified Python code. This project is a Python library published on PyPI and documented on ReadTheDocs. **Minimum Python version: 3.11.**
+
+## 1. Naming and Style
+
+- **Maximum line length**: 100 characters. Enforce via Ruff; use editor rulers at 80 and 90 as visual guides.
+- **Functions and local variables**: Use `lowercase_with_underscores`.
+- **Class names**: Use `TitleCase`.
+- **Module-level constants (global variables)**: Use `ALL_CAPS_WITH_UNDERSCORES`.
+- **Private names**: Prepend a single underscore for names that are not part of the public API: private attributes (e.g. `_cache`), module-private global variables, and non-public helper functions (e.g. `_parse_header`). Public API names have no leading underscore.
+- **Built-in names**: Do NOT use variable or function names that shadow Python built-ins (e.g. `float`, `filter`, `id`, `list`, `type`). If you must use such a name, append a single underscore (e.g. `filter_`, `type_`).
+- **Falsy checks**: Be explicit about what you are testing. Do NOT rely on truthiness when the intent could be ambiguous. Prefer:
+  - `if x is None:` for None checks (not `if not x:` when 0 or [] could occur).
+  - `if len(seq) == 0:` when you explicitly mean "empty sequence" and other falsy values (0, None) are not possible.
+  - For dicts: `if key in d:` then use `d[key]`; avoid `d.get(key)` when you need to distinguish "missing" from "present with a falsy value" unless that is the intent.
+- **Explicit checks over exceptions**: Prefer explicit membership or presence checks over catching exceptions for control flow. Example: use `if "a" in b: x = b["a"]` (or a clear `get` with a sentinel) rather than `try: x = b["a"]` / `except KeyError: ...` for normal flow. Use exceptions for genuinely exceptional conditions.
+
+## 2. General Coding
+
+- NEVER include backwards-compatibility code unless explicitly requested.
+- ALWAYS keep modules under 1000 lines. Split larger modules into a package with multiple files.
+- ALWAYS write simple, clear code; avoid unnecessary complexity.
+- NEVER hardcode magic constants. Define them as module-level constants, in a config module, or via environment variables.
+- ALWAYS catch exceptions at the smallest granularity possible. Do NOT wrap large blocks in a single `try`/`except`.
+- **Libraries:** Let exceptions propagate unless you are adding context, converting to a library-specific exception, or the exception represents a recoverable internal state. When re-raising, use `raise ... from` to preserve the full traceback for debugging.
+- **Applications:** Do not allow uncaught exceptions to reach the top level; use a top-level handler (e.g. in the main loop or HTTP framework) so that failures are logged and the process stays predictable. In both cases, ALWAYS provide full exception information for debugging (e.g. traceback, `raise ... from` when re-raising).
+- ALWAYS include meaningful, structured logging (use the `logging` module) that can be disabled or redirected. NEVER use bare `print()` for diagnostic output in library code.
+- Avoid mutable global variables. If unavoidable, document purpose and limit scope. Prefer module-level constants (ALL_CAPS) or dependency injection.
+- ALWAYS prefer comprehensions (list, dict, set, generator) over manual loops when the result is a new collection and the expression remains readable.
+- ALWAYS make the minimal changes necessary. NEVER modify code outside the scope of the current task.
+- ALWAYS apply DRY. NEVER duplicate code. Place reusable logic in a utility module. Search existing utilities before writing new functions. Parameterize utility functions to increase generality.
+- ALWAYS place imports at the top of the file in three alphabetically-sorted groups separated by a blank line: (1) standard library, (2) third-party, (3) local project. When adding new code or tests, add new imports to the appropriate group at the top; do not place them adjacent to the new code. Inline imports are permitted only to avoid heavy optional dependencies (e.g., GUI libraries).
+- Limit new functions to at most three positional parameters. Additional parameters MUST be keyword-only (after `*`). Choose a logical grouping of 0-3 positional parameters before enforcing keyword-only parameters. If there is no logical break within the first 3 parameters, make all parameters (after `self`) keyword-only.
+- Use the Receive-an-Object, Return-an-Object (RORO) pattern when a function takes or returns more than a few related values: accept a dataclass or TypedDict and return one, rather than long positional tuples.
+- NEVER use `getattr` just as a defensive measure if it is guaranteed that the object has the attribute. ALWAYS reference the attribute directly unless there is a specific reason to know the attribute may not be present. NEVER use getattr to reference the result of an `argparse` namespace when the argument name is a constant string.
+
+## 3. Public API Design
+
+- Clearly separate public API from internal implementation. Prefix internal functions, classes, and modules with `_`.
+- Use `__all__` in `__init__.py` to explicitly declare the public API surface.
+- Design for stability: think carefully before adding to the public API, because removing it later is a breaking change.
+- Include a `py.typed` marker file so downstream users get type-checking support.
+
+## 4. Comments
+
+- ALWAYS write self-documenting code: meaningful names, simple structure, limited nesting.
+- NEVER include comments that merely restate the code, reference user requests, or describe modification history.
+- ALWAYS include comments that explain the **rationale** behind non-obvious or complex logic.
+- ALWAYS preserve existing comments that are still accurate and relevant. Remove or update stale comments.
+
+## 5. Lint and Type Checking
+
+### Types
+
+- ALWAYS annotate all function/method parameters and return values, including `-> None` for functions (and `__init__`) that return nothing.
+- Use modern generic syntax (`list[str]`, `dict[str, int]`, `X | None`) for Python 3.11+.
+- Do not include `from __future__ import annotations` unless actually needed.
+
+### Mypy
+
+- ALWAYS run `mypy` on the full codebase (including tests) after changes. Fix all errors before delivering.
+- NEVER add global type exclusions. "Global type exclusions" means:
+  - Module-level `# type: ignore` without a specific error code.
+  - `ignore_errors = True` in mypy config.
+  - Broad `exclude` patterns that skip entire packages.
+- In exceptional, unfixable cases use a minimal line-level ignore: `# type: ignore[error-code]  # <brief justification>`.
+
+### Ruff / Linting
+
+- ALWAYS include `mypy` and `ruff` in the project's dev dependencies (e.g. in `pyproject.toml`).
+- ALWAYS run `ruff check` and `ruff format` on the full codebase after changes. Fix all errors.
+- Follow PEP 8 for all formatting and naming conventions.
+- Use the project's explicit Ruff rule set in `pyproject.toml` (see **Ruff rule categories** below). Do not disable categories that enforce project conventions (e.g. **A** for no builtin shadowing, **N** for naming).
+
+## 6. Docstrings
+
+- ALWAYS include a docstring for every module, class, function, and method.
+- Follow **PEP 257** using **Google style**. Use `Parameters:` (not `Args:`).
+- Include `Returns:`, `Raises:`, and any important behavioral notes.
+- NEVER mention backwards compatibility or user requests in docstrings.
+- Docstrings MUST be detailed enough to write a black-box test from the docstring alone.
+- Wrap docstring text to **90** characters.
+- ALWAYS update docstrings when the associated code changes.
+
+## 7. Testing
+
+### Test-driven development (TDD)
+
+- Use **test-driven development**: write tests first, then implement. Red → green → refactor.
+- Write tests BEFORE implementation based on stated requirements. If requirements are unclear, ask.
+- Run tests to confirm they fail, then implement, re-run, and fix until green.
+- After implementation, review tests to strengthen coverage.
+
+### Framework
+
+- ALWAYS include type annotations on test functions.
+- ALWAYS use `pytest` with `pytest-cov`.
+- ALWAYS use `pytest` with `pytest-xdist` and run tests with "-n auto".
+- ALWAYS write tests to be independent so that tests can be run in parallel.
+
+### Coverage and correctness
+
+- Target at least **90%** line coverage measured over the entire test suite (not a subset). Skipping hard-to-hit exception paths is acceptable.
+- NEVER write tests whose sole purpose is exercising code paths without asserting correctness.
+- Each `assert` MUST test exactly one condition (no `and` in assertions).
+- ALWAYS test for precise expected values, not ranges or existence checks. If the expected value is only known after implementation, update the test accordingly.
+- When multiple tests call the same function, use distinct inputs to maximize branch coverage, including edge cases and boundary values.
+- If two tests invoke the same code path but assert on different parts of the result, combine them into one test.
+- When testing exceptions, ALWAYS use `pytest.raises` as a context manager and assert on the exception **message content**, not just the exception type.
+
+### Test hygiene
+
+- If a test mutates a global, use a fixture or `try`/`finally` to restore the original value.
+- NEVER write a test that passes by ignoring an incorrect result or swallowing an exception. If the code is wrong, leave the failing test and explain why.
+- NEVER include line numbers, verbose rationale, or modification history in test comments. Keep comments to short (1-2 sentence) summaries useful for future maintainers.
+
+### Debugging
+
+- NEVER guess at bug causes. Use logic, stack traces, and targeted logging. If stuck in a fix loop, revert and re-approach from first principles. When necessary, ask for help.
+
+## 8. Ruff Rule Categories (Default Set)
+
+The template enables these Ruff lint categories in `pyproject.toml`. Use them as the default for new repos; add or ignore specific codes as needed.
+
+| Code | Source | Purpose |
+|------|--------|---------|
+| **E**, **W** | pycodestyle | Style and formatting (indent, whitespace, line length). |
+| **F** | Pyflakes | Unused imports, undefined names, syntax issues. |
+| **I** | isort | Import sorting and grouping. |
+| **UP** | pyupgrade | Prefer modern Python (e.g. 3.11+ syntax). |
+| **B** | flake8-bugbear | Common bugs (mutable defaults, assert, loop vars). |
+| **SIM** | flake8-simplify | Simpler alternatives (e.g. `in` instead of `not x == y`). |
+| **C4** | flake8-comprehensions | Prefer comprehensions over loops where clear. |
+| **A** | flake8-builtins | No shadowing of builtins (`id`, `filter`, `type`, etc.). |
+| **N** | pep8-naming | Class = TitleCase, functions/variables = lowercase_with_underscores. |
+| **PT** | flake8-pytest-style | Pytest best practices (fixtures, parametrize, raises). |
+| **RUF** | Ruff | Ruff-specific (e.g. unused noqa, deprecated). |
+
+Optional categories to consider adding later: **D** (pydocstyle) or **DOC** (pydoclint) for docstring linting; **PTH** (pathlib); **RET** (return simplification); **PERF** (perflint). Enable only if the team agrees to fix or ignore the resulting diagnostics.

rms_picmaker-1.0.0/.cursor/rules/security.mdc

@@ -0,0 +1,48 @@
+---
+alwaysApply: true
+description: Security best practices for Python library development — secrets, dependencies, and defensive coding.
+---
+
+# Security Best Practices
+
+## 1. Secrets Management
+
+- NEVER commit secrets, API keys, tokens, passwords, or private keys to the repository.
+- Store secrets in environment variables or a dedicated secrets manager (e.g., GitHub Secrets, GCP Secret Manager).
+- Use `.env` files for local development ONLY. Ensure `.env` is listed in `.gitignore`.
+- If a secret is accidentally committed, rotate it immediately — deleting the commit is NOT sufficient.
+
+## 2. Dependency Security
+
+- Specify minimum compatible versions for direct dependencies (e.g., `numpy>=2.2.0`) in `pyproject.toml`.
+- Run `pip audit` regularly and in CI to detect known vulnerabilities.
+- Enable GitHub Dependabot for automated dependency update PRs.
+- Review changelogs and diffs before merging dependency updates.
+
+## 3. Input Validation
+
+- NEVER trust external input (function arguments from callers, file contents, environment variables, data from remote URLs).
+- Validate inputs at the public API boundary of the library. Raise clear `ValueError` or `TypeError` exceptions for invalid arguments.
+- For file paths, resolve to absolute paths and verify they remain within the expected directory (prevent path traversal).
+
+## 4. Safe Defaults
+
+- NEVER implement custom cryptography. Use standard algorithms via trusted libraries (`cryptography`, `hashlib`).
+- When the library downloads or reads external data, verify integrity (checksums, expected schemas) where feasible.
+- Do NOT embed credentials, default passwords, or example secrets in source code, tests, or documentation.
+
+## 5. Logging
+
+- NEVER log secrets, tokens, passwords, or full stack traces containing sensitive data.
+- Sanitize PII (personally identifiable information) before logging.
+- Use the `logging` module with appropriate levels so callers can control verbosity.
+
+## 6. Code Review Security Checklist
+
+When reviewing PRs, verify:
+
+- [ ] No secrets or credentials in code, config, or comments.
+- [ ] Public API inputs are validated with clear error messages.
+- [ ] New dependencies are from reputable sources and have no known CVEs.
+- [ ] File operations guard against path traversal.
+- [ ] Error messages do not leak internal file paths or sensitive data.

rms_picmaker-1.0.0/.cursor/settings.json

@@ -0,0 +1,9 @@
+{
+  "editor.tabSize": 4,
+  "editor.insertSpaces": true,
+  "editor.detectIndentation": false,
+  "files.trimTrailingWhitespace": true,
+  "files.insertFinalNewline": true,
+  "files.trimFinalNewlines": true,
+  "editor.rulers": [80, 90, 100]
+}