pyramid-sa 0.1.0__tar.gz

pyramid_sa-0.1.0/.cursor/rules/dev-workflow-activation.mdc

@@ -0,0 +1,46 @@
+---
+description: Ask the user at the start of every new chat whether to follow the full development workflow
+alwaysApply: true
+---
+
+# Chat-Start Triage
+
+At the **very beginning** of every new chat, before doing anything else, check for in-progress work:
+
+1. Run `git branch --show-current`
+2. If the branch is **not** `main`, `master`, or `develop`, use the **Resume-Aware Triage**.
+3. Otherwise, use the **Standard Triage**.
+
+## Standard Triage
+
+Use the `AskQuestion` tool:
+
+title: "Chat Mode"
+prompt: "Should this chat follow the full development workflow?"
+options:
+  - id: full
+    label: "Yes — full dev workflow (planning, branching, PRs, quality checks)"
+  - id: quick
+    label: "No — quick task / exploration (skip workflow steps, keep code quality rules)"
+
+## Resume-Aware Triage
+
+Use the `AskQuestion` tool, including the detected branch name:
+
+title: "Chat Mode"
+prompt: "You're on branch `<branch-name>`. Want to continue this work or start something new?"
+options:
+  - id: continue
+    label: "Continue current work (resume dev workflow on this branch)"
+  - id: full
+    label: "Start a new dev workflow (different issue)"
+  - id: quick
+    label: "Quick task / exploration (skip workflow steps, keep code quality rules)"
+
+## Behavior Based on Answer
+
+**Continue current work** (`continue`): Read `.cursor/skills/dev-workflow/SKILL.md` and follow its **Resume** section — the agent will extract the issue from the branch name, fetch context, and pick up where the previous chat left off. Also enforce all rules from `.cursor/rules/quality.mdc`.
+
+**Full dev workflow** (`full`): Read and follow `.cursor/skills/dev-workflow/SKILL.md` from Step 1 — planning before coding, feature branches, incremental commits, PR process. Also enforce all rules from `.cursor/rules/quality.mdc`.
+
+**Quick task / exploration** (`quick`): Skip the structured workflow steps (mandatory planning phase, feature branches, PRs, release process). Still enforce all code quality rules defined in `.cursor/rules/quality.mdc`.

pyramid_sa-0.1.0/.cursor/rules/knowledge-base.mdc

@@ -0,0 +1,28 @@
+---
+description: Directs the AI to use the knowledge/ directory for project context
+alwaysApply: true
+---
+
+# Project Knowledge Base
+
+This project maintains a `knowledge/` directory with context for AI assistants.
+
+## Before making design or architectural decisions
+
+Read these files for context:
+
+- `knowledge/architecture.md` — system overview, components, and data flow
+- `knowledge/decisions.md` — past architectural decisions and their rationale
+- `knowledge/concepts.md` — domain terminology, mental models, and invariants
+
+## When new decisions are made
+
+Update `knowledge/decisions.md` with a new entry following the ADR template in that file.
+
+## When new domain concepts emerge
+
+Update `knowledge/concepts.md` with new terms, mental models, or invariants.
+
+## Important
+
+The `knowledge/` directory is for AI context. Human-facing documentation belongs in `docs/`.

pyramid_sa-0.1.0/.cursor/rules/knowledge.mdc

@@ -0,0 +1,38 @@
+---
+alwaysApply: true
+---
+
+# Knowledge Directory
+
+The `knowledge/` directory contains AI-facing living documentation — one markdown file per feature area describing its current state, design decisions, API surface, and gotchas.
+
+## Two Audiences
+
+- **`docs/` and `README.md`** are for humans — developers, users, contributors. Focus on clarity, examples, and getting-started guidance.
+- **`knowledge/`** is for the AI — the agent reads these files to understand the codebase. Focus on precision, design decisions, API surface, gotchas, and non-obvious learnings. Conciseness matters more than prose quality.
+- Both must stay in sync. When a feature changes, update both.
+
+## Structure
+
+One markdown file per feature area (e.g., `knowledge/auth.md`, `knowledge/billing.md`, `knowledge/architecture.md`). Each file follows a consistent structure:
+
+1. **Overview** — What this area does, in one or two sentences.
+2. **Design Decisions** — Why it works the way it does. Trade-offs, constraints, alternatives considered.
+3. **API Surface** — Key classes, functions, types, and their relationships.
+4. **Key Learnings / Gotchas** — Non-obvious behaviors, edge cases, things that broke before.
+
+## When to Update
+
+- After completing a new feature — create or extend the relevant file.
+- After fixing a significant bug that revealed something non-obvious — add to Key Learnings.
+- After making an architectural change — update the affected files.
+
+## What Does NOT Belong
+
+- Task lists, progress tracking, or backlog items.
+- Changelogs or timestamps — knowledge files describe the present, not the history.
+- Documentation for end users — that lives in `docs/`.
+
+## Reading Before Writing
+
+Before making changes to a feature area, read the relevant `knowledge/*.md` file first. It contains context that may affect your approach.

pyramid_sa-0.1.0/.cursor/rules/python-conventions.mdc

@@ -0,0 +1,47 @@
+---
+description: Python project conventions for pyramid-sa
+globs: "**/*.py"
+alwaysApply: false
+---
+
+# Python Conventions
+
+## Project layout
+
+- Source code lives in `src/pyramid_sa/`
+- Testing package lives in `testing/src/pyramid_sa_testing/`
+- Tests live in `tests/`
+- Always use the `src` layout; never put package code at the repository root
+
+## Imports
+
+- All imports at the top of the module, never inside functions or methods
+- Use absolute imports: `from pyramid_sa.module import thing`
+- Import order enforced by ruff (isort rules): stdlib, third-party, local
+
+## Formatting and linting
+
+- Formatter: black (line length 88)
+- Linter: ruff
+- Run before committing: `uv run ruff check .` and `uv run black .`
+
+## Testing
+
+- Framework: pytest
+- Test files: `tests/test_*.py`
+- Run: `uv run pytest`
+- Avoid mocks unless absolutely necessary; prefer real objects and integration tests
+
+## Forbidden
+
+- Never use pydantic
+- Never use FastAPI
+- Never add imports inside functions or methods
+
+## Style
+
+Follow the Zen of Python. Prefer:
+- Simple over complex
+- Explicit over implicit
+- Flat over nested
+- Readable over clever

pyramid_sa-0.1.0/.cursor/rules/quality.mdc

@@ -0,0 +1,21 @@
+---
+alwaysApply: true
+---
+
+# Code Quality Rules
+
+These rules apply to **every** chat, regardless of whether the full dev workflow is active.
+
+## Code Quality
+
+### Type Hints
+
+Use type hints for all function signatures and class attributes.
+
+### No Obvious Comments
+
+Do not add comments that merely narrate what the code does. Comments should explain non-obvious intent, trade-offs, or constraints that the code itself cannot convey.
+
+### Clean Formatting
+
+Run the project's formatter and linter before committing. All pre-commit checks must pass.

pyramid_sa-0.1.0/.cursor/rules/test-patterns.mdc

@@ -0,0 +1,68 @@
+---
+description: Enforce pytest testing patterns for Pyramid applications
+globs: **/tests/**/*.py, **/test_*.py
+alwaysApply: false
+---
+
+# Pytest Testing Patterns
+
+These rules apply whenever you create or modify test files.
+
+## Strict Rules
+
+- **No conditional logic in tests**: no `if/else`, `try/except`, `for`, `while`, ternary operators
+- **No class-based tests**: always use plain pytest functions
+- **No imports inside functions**: all imports at module level
+- **No standalone helper functions for test setup**: use `@pytest.fixture` in `conftest.py`
+- **No mocking unless absolutely necessary**: prefer `responses` for HTTP, real code for everything else. `unittest.mock.patch` is a last resort (gRPC clients only)
+- **No test files over ~200 lines**: split by concern (`_api`, `_service`, `_integration`, `_security`)
+
+## Testing Priority
+
+1. Real integrations and real code paths
+2. `responses` library for external HTTP calls (`@responses.activate`)
+3. `factory-boy` for test data generation (`SQLAlchemyModelFactory`)
+4. Pytest fixtures for reusable setup
+5. `unittest.mock.patch` only as absolute last resort
+
+## Test Structure
+
+- Mirror source structure in `tests/` directory
+- One test file per module: `test_<module_name>.py`
+- Descriptive function names: `test_<action>_<scenario>`
+- One test, one purpose
+- Brief docstring on each test function
+
+## Mandatory Security Tests
+
+If the endpoint under test is protected (has `factory=`, `permission=`, `__acl__`, JWT logic), you MUST include:
+
+- **Wrong/invalid token** test (expect 401 or 403)
+- **Wrong permission scope** test (expect 403)
+- **Missing authentication** test (expect 403)
+- **Wrong credentials** test where applicable (expect 401)
+
+Never ask whether to include these. If the endpoint is protected, they are required.
+
+## Avoid Duplication
+
+- Use `@pytest.mark.parametrize` with clear `ids` when tests share the same logic but differ in input/output
+- Use `@pytest.fixture` for repeated setup logic (never standalone helper functions)
+- Use `hypothesis` (`@given()`) for property-based testing of validators and numeric logic
+
+## Factory-Boy
+
+- Use `SQLAlchemyModelFactory` with `sqlalchemy_session_persistence = "flush"`
+- Use `factory.Faker` for realistic data
+- Use `factory.SubFactory` for relationships
+- Use `factory.LazyFunction` for computed fields
+
+## Forbidden
+
+- Never use FastAPI or pydantic
+- Never use mocks when `responses` or real integrations work
+- Never write conditional logic inside test functions
+
+## Full Workflow
+
+For writing complete test suites from scratch, use the **write-pytest** skill which provides a guided research-discuss-write flow.

pyramid_sa-0.1.0/.cursor/skills/dev-workflow/SKILL.md

@@ -0,0 +1,272 @@
+---
+name: dev-workflow
+description: Automate the full development cycle from issue to pull request using GitHub Issues. Use when the user wants to work on a feature, fix a bug, start a dev task, or says things like "let's work on", "implement", or "fix".
+---
+
+# Dev Workflow (GitHub Issues)
+
+Guide the developer through the full cycle: issue -> branch -> plan -> implement -> PR -> release.
+
+## Resume (Continuing from a Previous Chat)
+
+If resuming an in-progress workflow (the user selected "Continue current work" from the chat triage), follow these steps instead of starting from Step 1:
+
+1. Get the current branch name:
+
+```bash
+git branch --show-current
+```
+
+2. Extract the issue number from the branch name. Branches follow the pattern `<type>/<issue-number>-<slug>` (e.g., `fix/42-login-timeout` → issue `42`).
+
+3. Fetch the issue details and comments:
+
+```bash
+gh issue view <number> --json title,body,labels,number,comments
+```
+
+4. Search the issue comments for an **Implementation Plan**. If found:
+   - Parse the plan tasks
+   - Cross-reference with the git log (`git log main..HEAD --oneline`) to determine which tasks are likely completed
+   - Create TodoWrite entries: mark completed tasks as `completed`, set the next unfinished task to `in_progress`, rest as `pending`
+   - Tell the user what was found and which task you'll resume from
+   - Continue from **Step 5: Execute**
+
+5. If no plan is found in the comments:
+   - Tell the user the issue context and that no plan was stored yet
+   - Continue from **Step 3: Plan**
+
+---
+
+## Step 1: Issue
+
+Use AskQuestion:
+
+```
+prompt: "Do you already have a GitHub issue for this work?"
+options:
+  - Yes, I have an issue URL
+  - No, let's create one
+```
+
+### If the user has an issue
+
+Ask for the issue URL or number. Fetch the issue details:
+
+```bash
+gh issue view <number> --json title,body,labels,number
+```
+
+Parse the title, description, and labels for context.
+
+### If the user does not have an issue
+
+Discuss the work with the user to define:
+- **Title**: concise summary
+- **Description**: what needs to happen and why
+- **Labels**: bug, feature, enhancement, etc.
+
+When the issue is well-defined, create it:
+
+```bash
+gh issue create --title "<title>" --body "<description>" --label "<labels>"
+```
+
+Capture the issue number from the output.
+
+## Step 2: Branch
+
+Determine the branch type from labels or context:
+- `bug` label -> `fix/`
+- `feature` or `enhancement` label -> `feat/`
+- otherwise -> `task/`
+
+Create a slug from the issue title (lowercase, hyphens, max 40 chars).
+
+```bash
+git checkout -b <type>/<issue-number>-<slug>
+git push -u origin HEAD
+```
+
+Example: `fix/42-login-timeout`
+
+## Step 3: Plan
+
+Tell the user: "Switching to plan mode to design the implementation."
+
+Use the SwitchMode tool to enter plan mode. Then create an implementation plan by:
+1. Reading the issue description
+2. Exploring the relevant parts of the codebase
+3. Drafting a step-by-step plan with specific files and changes
+
+The plan should include:
+- A summary of the approach
+- Ordered list of tasks (each should be a concrete, testable unit of work)
+- Files to create or modify per task
+- Test strategy
+
+Wait for the user to review and approve the plan.
+
+## Step 4: Store Plan
+
+Once the plan is approved:
+
+1. Post the plan as a comment on the issue:
+
+```bash
+gh issue comment <number> --body "$(cat <<'EOF'
+## Implementation Plan
+
+<paste the approved plan here>
+
+EOF
+)"
+```
+
+2. Create TodoWrite entries for each task in the plan. Set the first task to `in_progress`, the rest to `pending`.
+
+## Step 5: Execute
+
+Switch back to agent mode using the SwitchMode tool.
+
+Work through the tasks sequentially:
+1. Pick the current `in_progress` task
+2. Implement the changes
+3. Run tests if applicable
+4. Mark the task as `completed` in TodoWrite
+5. Move the next task to `in_progress`
+
+After completing each task, post a progress comment on the issue:
+
+```bash
+gh issue comment <number> --body "Completed: <task description>"
+```
+
+## Step 6: Sync
+
+Throughout execution, keep the issue and TodoWrite aligned:
+- When a task is completed locally, comment on the issue
+- If the plan needs adjustment mid-execution, update both the TodoWrite list and post an updated plan comment on the issue
+- If new tasks emerge, add them to both TodoWrite and the issue
+
+## Step 7: Update Knowledge
+
+Before creating the PR, update the project's knowledge files:
+
+1. Check if the changes affect a feature area that has an existing `knowledge/*.md` file — if so, read the file and update any sections that are now stale. Rewrite sections to reflect the current state rather than appending notes.
+2. If a new feature area was introduced and no knowledge file exists, create one following the structure in `.cursor/rules/knowledge.mdc` (Overview, Design Decisions, API Surface, Key Learnings / Gotchas).
+3. If the changes affect the overall architecture, update `knowledge/architecture.md`.
+4. Commit knowledge updates separately:
+
+```bash
+git add knowledge/
+git commit -m "docs: update knowledge for <feature>"
+```
+
+## Step 8: Pull Request
+
+When all tasks are complete:
+
+1. Ensure all changes are committed
+2. Push the branch: `git push`
+3. Create the PR:
+
+```bash
+gh pr create --title "<issue-title>" --body "$(cat <<'EOF'
+## Summary
+<1-3 bullet points describing what was done>
+
+Closes #<issue-number>
+
+## Test plan
+<checklist of how to verify the changes>
+
+EOF
+)"
+```
+
+4. Tell the user the PR is ready for review and provide the PR URL.
+
+## Step 9: Review & Merge
+
+After the PR is created, ask the user:
+
+```
+prompt: "The PR is open. What would you like to do?"
+options:
+  - Check review status now
+  - Come back later — I'll request a review myself
+```
+
+### If "Check review status now"
+
+1. Check CI status and review state:
+
+```bash
+gh pr checks
+gh pr view --json reviewDecision,reviews,statusCheckRollup
+```
+
+2. Summarize the current state:
+   - CI checks: passing / failing / pending
+   - Review status: approved / changes requested / pending / no reviewers
+
+3. **If checks pass and reviews are approved**, ask:
+
+```
+prompt: "PR is approved and checks pass. Merge it?"
+options:
+  - Yes, squash and merge
+  - Yes, merge commit
+  - Yes, rebase and merge
+  - No, not yet
+```
+
+4. If the user selects a merge strategy:
+
+```bash
+gh pr merge --<strategy> --delete-branch
+git checkout main && git pull
+```
+
+5. If checks are failing or reviews are not yet approved, tell the user what is pending and suggest coming back later.
+
+### If "Come back later"
+
+Tell the user they can resume this step by asking to check the PR status or merge. End the current session here — the Release step runs after the PR is merged.
+
+## Step 10: Release
+
+> This step only applies to projects with a release flow.
+
+After the PR is merged:
+
+1. Detect the latest release tag:
+
+```bash
+gh release list --limit 1
+```
+
+2. Determine the next version using semantic versioning:
+   - Bug fix -> patch bump (1.0.0 -> 1.0.1)
+   - Feature -> minor bump (1.0.0 -> 1.1.0)
+   - Breaking change -> major bump (1.0.0 -> 2.0.0)
+
+   Use the issue labels and nature of changes to decide.
+
+3. Create the release:
+
+```bash
+gh release create v<version> --generate-notes --title "v<version>"
+```
+
+4. Tell the user the release has been created and provide the URL.
+
+## Step 11: End
+
+Summarize what was accomplished:
+- Issue number and title
+- Branch name
+- Number of commits
+- PR URL
+- Release version (if applicable)

pyramid_sa-0.1.0/.cursor/skills/knowledge-management/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: knowledge-management
+description: Create or update knowledge files for a feature area. Use when the user says "update knowledge", "create knowledge file for X", "document this feature", or after completing a feature that needs knowledge documentation.
+---
+
+# Knowledge Management
+
+This skill guides you through creating or updating files in the `knowledge/` directory. Follow the conventions defined in `.cursor/rules/knowledge.mdc`.
+
+## Step 1: Determine the Action
+
+Use AskQuestion:
+
+```
+prompt: "What would you like to do?"
+options:
+  - Create a new knowledge file for a feature area
+  - Update an existing knowledge file
+  - Review all knowledge files for staleness
+```
+
+---
+
+## Creating a New Knowledge File
+
+### Step 2a: Identify the Feature Area
+
+Ask the user which feature area to document, or infer it from the conversation context. The file should be named after the feature area in lowercase with underscores (e.g., `knowledge/billing.md`, `knowledge/auth.md`).
+
+### Step 3a: Explore the Codebase
+
+Read the source code for the feature area thoroughly:
+1. Identify the key modules, classes, and functions
+2. Trace the main code paths and data flow
+3. Note design decisions that are not obvious from the code alone
+4. Look for edge cases, gotchas, and non-obvious behaviors
+
+Also read `knowledge/architecture.md` to understand how this area fits into the overall system.
+
+### Step 4a: Draft the Knowledge File
+
+Write the file following this structure:
+
+```markdown
+# <Feature Area Name>
+
+<One or two sentences describing what this area does.>
+
+## Design Decisions
+
+<Why it works the way it does. Trade-offs, constraints, alternatives considered. Use a heading per decision if there are several.>
+
+## API Surface
+
+<Key classes, functions, types, and their relationships. Focus on what another developer (or the AI) needs to know to work in this area correctly.>
+
+## Key Learnings / Gotchas
+
+<Non-obvious behaviors, edge cases, things that broke before, common mistakes to avoid.>
+```
+
+### Step 5a: Write and Confirm
+
+Write the file to `knowledge/<feature-area>.md`. Tell the user what was created and suggest they review it.
+
+---
+
+## Updating an Existing Knowledge File
+
+### Step 2b: Identify What Changed
+
+Determine which knowledge file needs updating. This can come from:
+- The user specifying a file directly
+- A feature that was just implemented or modified
+- A bug fix that revealed a non-obvious behavior
+
+### Step 3b: Read Current State
+
+Read the existing knowledge file and the relevant source code. Identify which sections are stale or incomplete.
+
+### Step 4b: Rewrite Affected Sections
+
+Update only the sections that need changes. Knowledge files describe the **present state** — rewrite sections entirely rather than appending notes or changelogs. Keep the same structure (Design Decisions, API Surface, Key Learnings / Gotchas).
+
+### Step 5b: Write and Confirm
+
+Write the updated file. Tell the user what was changed and why.
+
+---
+
+## Reviewing All Knowledge Files
+
+### Step 2c: Scan for Staleness
+
+For each file in `knowledge/`:
+1. Read the knowledge file
+2. Check if the source code it describes has changed significantly since the file was last written
+3. Flag files that appear outdated
+
+### Step 3c: Report
+
+Present a summary listing each knowledge file with its status:
+- **Current** — the file accurately reflects the source code
+- **Needs update** — the source code has diverged; explain what looks stale
+- **Missing** — a significant feature area has source code but no knowledge file
+
+Ask the user which files to update, then follow the update flow above for each.

pyramid_sa-0.1.0/.cursor/skills/lint-format/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: lint-format
+description: Lint and format code for pyramid-sa. Use when the user asks to lint, format, check style, or fix code style.
+---
+
+# Lint and Format
+
+## Check (no changes)
+
+```bash
+uv run ruff check .
+uv run black --check .
+```
+
+## Fix
+
+```bash
+uv run ruff check . --fix
+uv run black .
+```