vardoger 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- vardoger-0.1.0/.github/workflows/ci.yml +58 -0
- vardoger-0.1.0/.github/workflows/publish.yml +39 -0
- vardoger-0.1.0/.gitignore +50 -0
- vardoger-0.1.0/AGENTS.md +141 -0
- vardoger-0.1.0/CHANGELOG.md +69 -0
- vardoger-0.1.0/CONTRIBUTING.md +137 -0
- vardoger-0.1.0/LICENSE +190 -0
- vardoger-0.1.0/PKG-INFO +182 -0
- vardoger-0.1.0/PRD.md +464 -0
- vardoger-0.1.0/README.md +152 -0
- vardoger-0.1.0/SECURITY.md +64 -0
- vardoger-0.1.0/assets/logo.svg +12 -0
- vardoger-0.1.0/plugins/_shared/README.md +23 -0
- vardoger-0.1.0/plugins/claude-code/.claude-plugin/plugin.json +19 -0
- vardoger-0.1.0/plugins/claude-code/README.md +35 -0
- vardoger-0.1.0/plugins/claude-code/hooks/hooks.json +16 -0
- vardoger-0.1.0/plugins/claude-code/skills/analyze/SKILL.md +111 -0
- vardoger-0.1.0/plugins/codex/.codex-plugin/plugin.json +18 -0
- vardoger-0.1.0/plugins/codex/README.md +74 -0
- vardoger-0.1.0/plugins/codex/skills/analyze/SKILL.md +111 -0
- vardoger-0.1.0/plugins/cursor/.cursor-plugin/plugin.json +19 -0
- vardoger-0.1.0/plugins/cursor/README.md +50 -0
- vardoger-0.1.0/plugins/cursor/assets/logo.svg +9 -0
- vardoger-0.1.0/plugins/cursor/install.sh +51 -0
- vardoger-0.1.0/plugins/cursor/mcp.json +8 -0
- vardoger-0.1.0/plugins/openclaw/README.md +25 -0
- vardoger-0.1.0/plugins/openclaw/skills/analyze/SKILL.md +118 -0
- vardoger-0.1.0/pyproject.toml +128 -0
- vardoger-0.1.0/scripts/install-local.sh +106 -0
- vardoger-0.1.0/scripts/render-skills.py +144 -0
- vardoger-0.1.0/scripts/smoke-test-release.sh +58 -0
- vardoger-0.1.0/src/vardoger/__init__.py +5 -0
- vardoger-0.1.0/src/vardoger/__main__.py +7 -0
- vardoger-0.1.0/src/vardoger/analyze.py +50 -0
- vardoger-0.1.0/src/vardoger/checkpoint.py +236 -0
- vardoger-0.1.0/src/vardoger/cli.py +792 -0
- vardoger-0.1.0/src/vardoger/digest.py +56 -0
- vardoger-0.1.0/src/vardoger/feedback.py +162 -0
- vardoger-0.1.0/src/vardoger/history/__init__.py +16 -0
- vardoger-0.1.0/src/vardoger/history/claude_code.py +190 -0
- vardoger-0.1.0/src/vardoger/history/codex.py +128 -0
- vardoger-0.1.0/src/vardoger/history/cursor.py +128 -0
- vardoger-0.1.0/src/vardoger/history/models.py +69 -0
- vardoger-0.1.0/src/vardoger/history/openclaw.py +122 -0
- vardoger-0.1.0/src/vardoger/mcp_server.py +352 -0
- vardoger-0.1.0/src/vardoger/models.py +263 -0
- vardoger-0.1.0/src/vardoger/personalization.py +134 -0
- vardoger-0.1.0/src/vardoger/prompts/__init__.py +62 -0
- vardoger-0.1.0/src/vardoger/prompts/analyze_skill_body.md +107 -0
- vardoger-0.1.0/src/vardoger/prompts/feedback_context.md +30 -0
- vardoger-0.1.0/src/vardoger/prompts/summarize.md +62 -0
- vardoger-0.1.0/src/vardoger/prompts/synthesize.md +52 -0
- vardoger-0.1.0/src/vardoger/quality.py +317 -0
- vardoger-0.1.0/src/vardoger/setup.py +231 -0
- vardoger-0.1.0/src/vardoger/staleness.py +125 -0
- vardoger-0.1.0/src/vardoger/writers/__init__.py +13 -0
- vardoger-0.1.0/src/vardoger/writers/claude_code.py +68 -0
- vardoger-0.1.0/src/vardoger/writers/codex.py +119 -0
- vardoger-0.1.0/src/vardoger/writers/cursor.py +67 -0
- vardoger-0.1.0/src/vardoger/writers/openclaw.py +85 -0
- vardoger-0.1.0/tests/conftest.py +108 -0
- vardoger-0.1.0/tests/history/test_claude_code.py +147 -0
- vardoger-0.1.0/tests/history/test_codex.py +149 -0
- vardoger-0.1.0/tests/history/test_cursor.py +136 -0
- vardoger-0.1.0/tests/history/test_extract_text.py +50 -0
- vardoger-0.1.0/tests/history/test_openclaw.py +175 -0
- vardoger-0.1.0/tests/prompts/test_prompts.py +24 -0
- vardoger-0.1.0/tests/test_analyze.py +46 -0
- vardoger-0.1.0/tests/test_checkpoint.py +354 -0
- vardoger-0.1.0/tests/test_cli.py +513 -0
- vardoger-0.1.0/tests/test_digest.py +86 -0
- vardoger-0.1.0/tests/test_feedback.py +138 -0
- vardoger-0.1.0/tests/test_mcp_server.py +224 -0
- vardoger-0.1.0/tests/test_personalization.py +192 -0
- vardoger-0.1.0/tests/test_quality.py +207 -0
- vardoger-0.1.0/tests/test_staleness.py +183 -0
- vardoger-0.1.0/tests/writers/test_claude_code_writer.py +55 -0
- vardoger-0.1.0/tests/writers/test_codex_writer.py +82 -0
- vardoger-0.1.0/tests/writers/test_cursor_writer.py +46 -0
- vardoger-0.1.0/tests/writers/test_openclaw_writer.py +85 -0
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
name: CI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [main]
|
|
6
|
+
pull_request:
|
|
7
|
+
branches: [main]
|
|
8
|
+
|
|
9
|
+
jobs:
|
|
10
|
+
test:
|
|
11
|
+
runs-on: ubuntu-latest
|
|
12
|
+
strategy:
|
|
13
|
+
matrix:
|
|
14
|
+
python-version: ["3.11", "3.12", "3.13"]
|
|
15
|
+
steps:
|
|
16
|
+
- uses: actions/checkout@v6
|
|
17
|
+
|
|
18
|
+
- uses: astral-sh/setup-uv@v8.1.0
|
|
19
|
+
with:
|
|
20
|
+
enable-cache: true
|
|
21
|
+
cache-dependency-glob: pyproject.toml
|
|
22
|
+
|
|
23
|
+
- name: Install dependencies
|
|
24
|
+
run: uv sync --python ${{ matrix.python-version }}
|
|
25
|
+
|
|
26
|
+
- name: Lint
|
|
27
|
+
run: uv run ruff check src/ tests/ scripts/
|
|
28
|
+
|
|
29
|
+
- name: Format check
|
|
30
|
+
run: uv run ruff format --check src/ tests/ scripts/
|
|
31
|
+
|
|
32
|
+
- name: Type check
|
|
33
|
+
run: uv run mypy src/
|
|
34
|
+
|
|
35
|
+
- name: Check rendered plugin skills are in sync
|
|
36
|
+
run: uv run scripts/render-skills.py --check
|
|
37
|
+
|
|
38
|
+
- name: Test
|
|
39
|
+
run: uv run pytest tests/ --tb=short -q --cov=vardoger --cov-fail-under=80
|
|
40
|
+
|
|
41
|
+
security:
|
|
42
|
+
runs-on: ubuntu-latest
|
|
43
|
+
steps:
|
|
44
|
+
- uses: actions/checkout@v6
|
|
45
|
+
|
|
46
|
+
- uses: astral-sh/setup-uv@v8.1.0
|
|
47
|
+
with:
|
|
48
|
+
enable-cache: true
|
|
49
|
+
cache-dependency-glob: pyproject.toml
|
|
50
|
+
|
|
51
|
+
- name: Install dependencies
|
|
52
|
+
run: uv sync
|
|
53
|
+
|
|
54
|
+
- name: Static security scan (bandit)
|
|
55
|
+
run: uv run --with bandit bandit -r src/ -q
|
|
56
|
+
|
|
57
|
+
- name: Dependency CVE scan (pip-audit)
|
|
58
|
+
run: uv run --with pip-audit pip-audit --skip-editable
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
name: Publish to PyPI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
release:
|
|
5
|
+
types: [published]
|
|
6
|
+
|
|
7
|
+
jobs:
|
|
8
|
+
build:
|
|
9
|
+
runs-on: ubuntu-latest
|
|
10
|
+
steps:
|
|
11
|
+
- uses: actions/checkout@v6
|
|
12
|
+
|
|
13
|
+
- uses: astral-sh/setup-uv@v8.1.0
|
|
14
|
+
with:
|
|
15
|
+
enable-cache: true
|
|
16
|
+
cache-dependency-glob: pyproject.toml
|
|
17
|
+
|
|
18
|
+
- name: Build package
|
|
19
|
+
run: uv build
|
|
20
|
+
|
|
21
|
+
- uses: actions/upload-artifact@v7
|
|
22
|
+
with:
|
|
23
|
+
name: dist
|
|
24
|
+
path: dist/
|
|
25
|
+
|
|
26
|
+
publish:
|
|
27
|
+
needs: build
|
|
28
|
+
runs-on: ubuntu-latest
|
|
29
|
+
environment: pypi
|
|
30
|
+
permissions:
|
|
31
|
+
id-token: write
|
|
32
|
+
steps:
|
|
33
|
+
- uses: actions/download-artifact@v8
|
|
34
|
+
with:
|
|
35
|
+
name: dist
|
|
36
|
+
path: dist/
|
|
37
|
+
|
|
38
|
+
- name: Publish to PyPI
|
|
39
|
+
uses: pypa/gh-action-pypi-publish@release/v1
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
# OS files
|
|
2
|
+
.DS_Store
|
|
3
|
+
Thumbs.db
|
|
4
|
+
|
|
5
|
+
# IDE files
|
|
6
|
+
.idea/
|
|
7
|
+
.vscode/
|
|
8
|
+
*.swp
|
|
9
|
+
*.swo
|
|
10
|
+
*~
|
|
11
|
+
|
|
12
|
+
# Environment and secrets
|
|
13
|
+
.env
|
|
14
|
+
.env.*
|
|
15
|
+
!.env.example
|
|
16
|
+
*.pem
|
|
17
|
+
*.key
|
|
18
|
+
credentials.json
|
|
19
|
+
|
|
20
|
+
# Build artifacts
|
|
21
|
+
build/
|
|
22
|
+
dist/
|
|
23
|
+
out/
|
|
24
|
+
target/
|
|
25
|
+
|
|
26
|
+
# Dependencies
|
|
27
|
+
node_modules/
|
|
28
|
+
vendor/
|
|
29
|
+
__pycache__/
|
|
30
|
+
*.pyc
|
|
31
|
+
|
|
32
|
+
# Logs
|
|
33
|
+
*.log
|
|
34
|
+
logs/
|
|
35
|
+
|
|
36
|
+
# Coverage
|
|
37
|
+
coverage/
|
|
38
|
+
.coverage
|
|
39
|
+
.nyc_output/
|
|
40
|
+
|
|
41
|
+
# Pytest
|
|
42
|
+
.pytest_cache/
|
|
43
|
+
|
|
44
|
+
# Python / uv
|
|
45
|
+
.venv/
|
|
46
|
+
*.egg-info/
|
|
47
|
+
uv.lock
|
|
48
|
+
|
|
49
|
+
# vardoger generated output (don't commit personalization)
|
|
50
|
+
.cursor/rules/vardoger.md
|
vardoger-0.1.0/AGENTS.md
ADDED
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
# Engineering Rules (for AI Assistants)
|
|
2
|
+
|
|
3
|
+
Authoritative coding instructions for this repository. Linked from:
|
|
4
|
+
- `.cursor/rules/` (Cursor)
|
|
5
|
+
- `.github/copilot-instructions.md` (Copilot)
|
|
6
|
+
- `CLAUDE.md` (Claude Code)
|
|
7
|
+
- `AGENTS.md` (OpenAI Codex)
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## Project Structure & Naming
|
|
12
|
+
|
|
13
|
+
```
|
|
14
|
+
src/vardoger/ # shared core — history reading, analysis, prompt generation
|
|
15
|
+
plugins/cursor/ # Cursor MCP server config, install script
|
|
16
|
+
plugins/claude-code/ # Claude Code plugin manifest, skills
|
|
17
|
+
plugins/codex/ # Codex plugin manifest, skills
|
|
18
|
+
plugins/openclaw/ # OpenClaw skill
|
|
19
|
+
tests/ # all tests, mirroring src/ structure
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
| Kind | Path pattern |
|
|
23
|
+
|---|---|
|
|
24
|
+
| History adapters | `src/vardoger/history/<platform>.py` |
|
|
25
|
+
| Prompt writers | `src/vardoger/writers/<platform>.py` |
|
|
26
|
+
| AI prompts | `src/vardoger/prompts/*.md` (or `plugins/<platform>/prompts/` if platform-specific) |
|
|
27
|
+
| Plugin manifests | `plugins/<platform>/.<tool>-plugin/plugin.json` |
|
|
28
|
+
| Skills | `plugins/<platform>/skills/<name>/SKILL.md` |
|
|
29
|
+
| Tests | `tests/` directory mirroring `src/vardoger/` (e.g., `tests/history/test_cursor.py`) |
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## Before You Code
|
|
34
|
+
|
|
35
|
+
- **Find the module boundary**: locate the nearest `pyproject.toml` and treat it as the unit of build, test, and dependency rules.
|
|
36
|
+
- **Preserve layering**: shared core lives in `src/vardoger/`, platform-specific code in `plugins/<platform>/`. Don't mix them.
|
|
37
|
+
- **Prefer configuration over ad-hoc constants**: use a config class and env vars rather than scattering `os.getenv` calls.
|
|
38
|
+
- **Avoid duplication**: if you see near-identical blocks, centralize them.
|
|
39
|
+
|
|
40
|
+
---
|
|
41
|
+
|
|
42
|
+
## Code Review Priorities
|
|
43
|
+
|
|
44
|
+
These are the patterns reviewers consistently flag:
|
|
45
|
+
|
|
46
|
+
- **Module boundaries & dependency direction**
|
|
47
|
+
- Shared types belong in `src/vardoger/`, not inside a plugin.
|
|
48
|
+
- Plugin modules should not import from other plugins; dependencies flow inward to the shared core.
|
|
49
|
+
|
|
50
|
+
- **Config & safety**
|
|
51
|
+
- Put env/config interpretation in a config class, not sprinkled across code.
|
|
52
|
+
- Add explicit enablement flags for destructive or side-effectful operations.
|
|
53
|
+
|
|
54
|
+
- **Code clarity**
|
|
55
|
+
- Keep method/variable names aligned with actual behavior.
|
|
56
|
+
- Keep private helper functions at the bottom of the file.
|
|
57
|
+
- PR titles/descriptions must match the actual scope.
|
|
58
|
+
|
|
59
|
+
- **Testing**
|
|
60
|
+
- Prefer simple, readable tests over elaborate fixtures.
|
|
61
|
+
- Add unit tests for new non-trivial logic.
|
|
62
|
+
- Assert whole expected objects in a single comparison, not field-by-field.
|
|
63
|
+
|
|
64
|
+
- **Serialization & data**
|
|
65
|
+
- Don't build JSON by string concatenation or manual dict construction; use Pydantic models and `model_dump_json()`.
|
|
66
|
+
- Parse incoming JSON with `model_validate_json()`, not raw `json.loads()` + `.get()` chains.
|
|
67
|
+
- Keep templates centralized and reusable.
|
|
68
|
+
|
|
69
|
+
- **Performance**
|
|
70
|
+
- Don't recreate immutable instances on every call; reuse a single instance when safe.
|
|
71
|
+
- Prefer `orjson` for heavy JSON workloads.
|
|
72
|
+
|
|
73
|
+
---
|
|
74
|
+
|
|
75
|
+
## Git Workflow
|
|
76
|
+
|
|
77
|
+
### Commits
|
|
78
|
+
- **Subject**: imperative summary, one line. Never mention AI assistants (no `Co-Authored-By`).
|
|
79
|
+
- **Dependency bumps**: `bump <package> to <version>` (commit both `pyproject.toml` and `uv.lock`).
|
|
80
|
+
|
|
81
|
+
### Pull Requests
|
|
82
|
+
- **Title**: short imperative summary.
|
|
83
|
+
- **Description**: say what and why. Don't list changed files. Don't mention AI assistants.
|
|
84
|
+
- **Merge**: rebase and merge to `main`, delete branch after merge.
|
|
85
|
+
|
|
86
|
+
---
|
|
87
|
+
|
|
88
|
+
## Python
|
|
89
|
+
|
|
90
|
+
### Runtime & Dependencies
|
|
91
|
+
- **Python version**: ≥3.11 (follow `pyproject.toml`).
|
|
92
|
+
- **Package manager**: [uv](https://docs.astral.sh/uv/)
|
|
93
|
+
- Install: `uv sync`
|
|
94
|
+
- Add runtime dep: `uv add <pkg>`
|
|
95
|
+
- Add dev dep: `uv add --group dev <pkg>`
|
|
96
|
+
- Lock update: `uv lock`
|
|
97
|
+
|
|
98
|
+
### Quality Checks
|
|
99
|
+
|
|
100
|
+
Run these before pushing — all must pass:
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
uv run ruff check . # lint
|
|
104
|
+
uv run ruff format --check . # format check
|
|
105
|
+
uv run mypy src/ # type check
|
|
106
|
+
uv run pytest # tests
|
|
107
|
+
uv run pytest --cov=vardoger # coverage
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
Quick-fix formatting and auto-fixable lint issues:
|
|
111
|
+
|
|
112
|
+
```bash
|
|
113
|
+
uv run ruff format . # auto-format
|
|
114
|
+
uv run ruff check --fix . # auto-fix lints
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
### Code Standards
|
|
118
|
+
- **Data structures**:
|
|
119
|
+
- Use `pydantic.BaseModel` for all JSON I/O shapes (parsing, validation, serialization). All Pydantic models live in `src/vardoger/models.py`.
|
|
120
|
+
- Use `model_validate_json(raw)` to parse, `model_dump_json()` to serialize. Avoid manual `json.loads` / `json.dumps` for typed data.
|
|
121
|
+
- Set `extra="ignore"` on models that parse external/third-party JSON with unpredictable fields.
|
|
122
|
+
- Plain `dataclasses` are fine for pure domain objects that are never serialized (e.g., `Message`, `Conversation` in `history/models.py`).
|
|
123
|
+
- Do not scatter model definitions across modules; add new models to `models.py`.
|
|
124
|
+
- **Typing**:
|
|
125
|
+
- Add `from __future__ import annotations` in every module.
|
|
126
|
+
- MyPy strict mode: `disallow_untyped_defs`, `check_untyped_defs`.
|
|
127
|
+
- Prefer precise types and immutable collections (`frozenset`, `tuple`).
|
|
128
|
+
- **Formatting**: enforced by ruff (replaces black + isort + autoflake). See `[tool.ruff]` in `pyproject.toml`.
|
|
129
|
+
|
|
130
|
+
### Testing
|
|
131
|
+
- Framework: pytest. Tests live in `tests/`, mirroring the `src/vardoger/` structure.
|
|
132
|
+
- Target coverage: ≥90% for core modules.
|
|
133
|
+
- All tests must pass before commit/push.
|
|
134
|
+
|
|
135
|
+
### Architecture Patterns
|
|
136
|
+
- **Configuration**: centralize env access (e.g., `Config.from_env()`), avoid scattered `os.getenv`.
|
|
137
|
+
- **Error handling**: raise clear exceptions with actionable messages.
|
|
138
|
+
- **Logging**: `getLogger(__name__)`, structured and context-rich, never log PII or secrets.
|
|
139
|
+
- **Imports**: absolute imports within the `vardoger` package namespace.
|
|
140
|
+
- **Immutability**: immutable DTOs, avoid mutating inputs.
|
|
141
|
+
- **Prompts**: store as standalone `.md` files under `src/vardoger/prompts/`, never as inline strings. Python code loads them at runtime.
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project are documented here. Format follows
|
|
4
|
+
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres
|
|
5
|
+
to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
6
|
+
|
|
7
|
+
## [Unreleased]
|
|
8
|
+
|
|
9
|
+
## [0.1.0] — 2026-04-20
|
|
10
|
+
|
|
11
|
+
### Added
|
|
12
|
+
|
|
13
|
+
- Phase 4 marketplace-ready release.
|
|
14
|
+
- Plugin manifests for all four platforms carry consistent metadata (`name`,
|
|
15
|
+
`version`, `description`, `author`, `homepage`, `repository`, `license`,
|
|
16
|
+
`keywords`).
|
|
17
|
+
- Cursor native plugin layout: `.cursor-plugin/plugin.json` and a self-bootstrapping
|
|
18
|
+
`mcp.json` that launches the CLI via `uvx` with a `pipx run` fallback.
|
|
19
|
+
- OpenClaw SKILL frontmatter now matches the ClawHub schema
|
|
20
|
+
(`version`, `metadata.openclaw.requires.bins`, `homepage`).
|
|
21
|
+
- Shared analyze-skill template under `plugins/_shared/` with `scripts/render-skills.py`
|
|
22
|
+
to keep the three per-platform `SKILL.md` files in sync.
|
|
23
|
+
- Repo-level `SECURITY.md`, `CHANGELOG.md`, and committed `assets/logo.svg`.
|
|
24
|
+
- Public `plugins/codex/marketplace.json` so users can install via Codex's
|
|
25
|
+
custom-marketplace flow without cloning the repo.
|
|
26
|
+
|
|
27
|
+
### Changed
|
|
28
|
+
|
|
29
|
+
- `Development Status` classifier bumped from `3 - Alpha` to `4 - Beta`.
|
|
30
|
+
- README install instructions default to the stable `pipx install vardoger` path;
|
|
31
|
+
the `--pre` / `uvx vardoger@...` flow is kept under "Previous pre-releases."
|
|
32
|
+
- PRD Phase 1 checkboxes for OpenClaw history adapter and local skill install
|
|
33
|
+
flipped to match reality.
|
|
34
|
+
|
|
35
|
+
### Removed
|
|
36
|
+
|
|
37
|
+
- Stale pre-release wheel and sdist artifacts from `dist/`.
|
|
38
|
+
|
|
39
|
+
## [0.1.0b3] — 2026-04-17
|
|
40
|
+
|
|
41
|
+
### Fixed
|
|
42
|
+
|
|
43
|
+
- Codex plugin registration path and sandbox-aware CLI invocation (#3).
|
|
44
|
+
- `prepare` now only checkpoints after the final batch to avoid premature commits.
|
|
45
|
+
|
|
46
|
+
### Added
|
|
47
|
+
|
|
48
|
+
- YAML frontmatter emitted in generated `SKILL.md` outputs.
|
|
49
|
+
|
|
50
|
+
## [0.1.0b2] — 2026-04-17
|
|
51
|
+
|
|
52
|
+
### Changed
|
|
53
|
+
|
|
54
|
+
- Pinned `astral-sh/setup-uv` to `v8.1.0` for reproducible CI installs.
|
|
55
|
+
- Documented the beta install path (`pipx install --pre vardoger`).
|
|
56
|
+
- Bumped CI action versions.
|
|
57
|
+
|
|
58
|
+
## [0.1.0b1] — 2026-04-17
|
|
59
|
+
|
|
60
|
+
### Added
|
|
61
|
+
|
|
62
|
+
- First public beta on PyPI via trusted-publisher release workflow.
|
|
63
|
+
- Cross-platform core: Cursor, Claude Code, OpenAI Codex, and OpenClaw.
|
|
64
|
+
- Phase 1 — history readers, platform-native prompt writers, `vardoger setup`.
|
|
65
|
+
- Phase 2 — skill-driven analysis pipeline (`prepare`/`synthesize`/`write`).
|
|
66
|
+
- Phase 3 — staleness detection, feedback accept/reject with auto-revert,
|
|
67
|
+
confidence scoring, and A/B comparison.
|
|
68
|
+
- 80% combined test-coverage floor enforced in CI plus `bandit` + `pip-audit`
|
|
69
|
+
security job.
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
# Contributing to vardoger
|
|
2
|
+
|
|
3
|
+
Thanks for taking the time to contribute! This document walks through the full
|
|
4
|
+
workflow for submitting a pull request. For a one-paragraph version, see the
|
|
5
|
+
[Contributing section in the README](README.md#contributing).
|
|
6
|
+
|
|
7
|
+
Coding standards, project layout, and per-module expectations live in
|
|
8
|
+
[AGENTS.md](AGENTS.md) — please skim it before your first change.
|
|
9
|
+
|
|
10
|
+
## Prerequisites
|
|
11
|
+
|
|
12
|
+
- Python 3.11 or newer (CI tests 3.11, 3.12, 3.13).
|
|
13
|
+
- [uv](https://docs.astral.sh/uv/getting-started/installation/) for dependency
|
|
14
|
+
management.
|
|
15
|
+
- A GitHub account for forking the repository.
|
|
16
|
+
|
|
17
|
+
## 1. Fork and clone
|
|
18
|
+
|
|
19
|
+
1. Click **Fork** on [github.com/dstrupl/vardoger](https://github.com/dstrupl/vardoger)
|
|
20
|
+
to create your own copy.
|
|
21
|
+
2. Clone your fork and add the upstream remote so you can keep it in sync:
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
git clone https://github.com/<your-username>/vardoger.git
|
|
25
|
+
cd vardoger
|
|
26
|
+
git remote add upstream https://github.com/dstrupl/vardoger.git
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
3. Install dependencies:
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
uv sync
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## 2. Create a topic branch
|
|
36
|
+
|
|
37
|
+
Base your work on an up-to-date `main`:
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
git fetch upstream
|
|
41
|
+
git checkout -b my-change upstream/main
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Use a short, descriptive branch name (e.g. `fix-cursor-timestamp-parsing`,
|
|
45
|
+
`add-openclaw-staleness-check`).
|
|
46
|
+
|
|
47
|
+
## 3. Make your change
|
|
48
|
+
|
|
49
|
+
- Follow the conventions in [AGENTS.md](AGENTS.md): Pydantic for JSON I/O,
|
|
50
|
+
`from __future__ import annotations` in every module, absolute imports within
|
|
51
|
+
the `vardoger` package, prompts as `.md` files (not inline strings).
|
|
52
|
+
- Add or update tests under `tests/` to cover new behavior. Coverage must stay
|
|
53
|
+
at or above 80% overall.
|
|
54
|
+
- Keep commits focused and use imperative-mood subjects (e.g. `fix cursor
|
|
55
|
+
transcript edge case`, not `Fixed a bug`). Do **not** add AI co-author
|
|
56
|
+
trailers.
|
|
57
|
+
|
|
58
|
+
## 4. Run the quality gates locally
|
|
59
|
+
|
|
60
|
+
CI will run the same checks on your PR; running them locally first avoids the
|
|
61
|
+
back-and-forth. The one-liner:
|
|
62
|
+
|
|
63
|
+
```bash
|
|
64
|
+
uv run ruff check . \
|
|
65
|
+
&& uv run ruff format --check . \
|
|
66
|
+
&& uv run mypy src/ \
|
|
67
|
+
&& uv run pytest --cov=vardoger --cov-fail-under=80
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Individual commands, if you want to iterate on one at a time:
|
|
71
|
+
|
|
72
|
+
| Check | Command |
|
|
73
|
+
| --- | --- |
|
|
74
|
+
| Lint | `uv run ruff check .` |
|
|
75
|
+
| Auto-fix lint | `uv run ruff check --fix .` |
|
|
76
|
+
| Format | `uv run ruff format .` |
|
|
77
|
+
| Format check | `uv run ruff format --check .` |
|
|
78
|
+
| Type check | `uv run mypy src/` |
|
|
79
|
+
| Tests + coverage | `uv run pytest --cov=vardoger --cov-fail-under=80` |
|
|
80
|
+
|
|
81
|
+
The security job in CI additionally runs:
|
|
82
|
+
|
|
83
|
+
```bash
|
|
84
|
+
uv run --with bandit bandit -r src/ -q
|
|
85
|
+
uv run --with pip-audit pip-audit --skip-editable
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
You can run these locally too, but they rarely fail on feature PRs.
|
|
89
|
+
|
|
90
|
+
## 5. Push and open a PR
|
|
91
|
+
|
|
92
|
+
```bash
|
|
93
|
+
git push -u origin my-change
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Then open a pull request against `dstrupl/vardoger:main`. In the PR
|
|
97
|
+
description:
|
|
98
|
+
|
|
99
|
+
- Say **what** the change does and **why** (not the list of touched files).
|
|
100
|
+
- Link any related issue.
|
|
101
|
+
- Mention anything reviewers should pay extra attention to (risk, migrations,
|
|
102
|
+
follow-ups).
|
|
103
|
+
|
|
104
|
+
## 6. What happens on your PR
|
|
105
|
+
|
|
106
|
+
- GitHub runs the `CI` workflow automatically:
|
|
107
|
+
- `test` job: lint, format check, mypy, and pytest with an 80% coverage
|
|
108
|
+
floor on Python 3.11, 3.12, and 3.13.
|
|
109
|
+
- `security` job: `bandit` plus `pip-audit`.
|
|
110
|
+
- If you are a first-time contributor, a maintainer may need to click
|
|
111
|
+
**Approve and run** before the first workflow execution. Subsequent pushes
|
|
112
|
+
to the same PR run automatically.
|
|
113
|
+
- The `publish.yml` workflow does **not** run on PRs; it only fires on tagged
|
|
114
|
+
releases from `main`.
|
|
115
|
+
- Maintainer will rebase and merge once the review is green and CI passes;
|
|
116
|
+
the branch is deleted after merge.
|
|
117
|
+
|
|
118
|
+
## Keeping your fork up to date
|
|
119
|
+
|
|
120
|
+
Rebase rather than merge to keep history linear:
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
git fetch upstream
|
|
124
|
+
git rebase upstream/main
|
|
125
|
+
git push --force-with-lease
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
## Reporting bugs and proposing features
|
|
129
|
+
|
|
130
|
+
Open a GitHub issue before starting on large changes so we can discuss scope.
|
|
131
|
+
For security issues, please avoid filing a public issue — contact the
|
|
132
|
+
maintainer directly.
|
|
133
|
+
|
|
134
|
+
## License
|
|
135
|
+
|
|
136
|
+
By contributing, you agree that your contributions will be licensed under the
|
|
137
|
+
[Apache License, Version 2.0](LICENSE) that covers the project.
|
vardoger-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,190 @@
|
|
|
1
|
+
Apache License
|
|
2
|
+
Version 2.0, January 2004
|
|
3
|
+
http://www.apache.org/licenses/
|
|
4
|
+
|
|
5
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
6
|
+
|
|
7
|
+
1. Definitions.
|
|
8
|
+
|
|
9
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
10
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
11
|
+
|
|
12
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
13
|
+
the copyright owner that is granting the License.
|
|
14
|
+
|
|
15
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
16
|
+
other entities that control, are controlled by, or are under common
|
|
17
|
+
control with that entity. For the purposes of this definition,
|
|
18
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
19
|
+
direction or management of such entity, whether by contract or
|
|
20
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
21
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
22
|
+
|
|
23
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
24
|
+
exercising permissions granted by this License.
|
|
25
|
+
|
|
26
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
27
|
+
including but not limited to software source code, documentation
|
|
28
|
+
source, and configuration files.
|
|
29
|
+
|
|
30
|
+
"Object" form shall mean any form resulting from mechanical
|
|
31
|
+
transformation or translation of a Source form, including but
|
|
32
|
+
not limited to compiled object code, generated documentation,
|
|
33
|
+
and conversions to other media types.
|
|
34
|
+
|
|
35
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
36
|
+
Object form, made available under the License, as indicated by a
|
|
37
|
+
copyright notice that is included in or attached to the work
|
|
38
|
+
(an example is provided in the Appendix below).
|
|
39
|
+
|
|
40
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
41
|
+
form, that is based on (or derived from) the Work and for which the
|
|
42
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
43
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
44
|
+
of this License, Derivative Works shall not include works that remain
|
|
45
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
46
|
+
the Work and Derivative Works thereof.
|
|
47
|
+
|
|
48
|
+
"Contribution" shall mean any work of authorship, including
|
|
49
|
+
the original version of the Work and any modifications or additions
|
|
50
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
51
|
+
submitted to the Licensor for inclusion in the Work by the copyright owner
|
|
52
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
53
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
54
|
+
means any form of electronic, verbal, or written communication sent
|
|
55
|
+
to the Licensor or its representatives, including but not limited to
|
|
56
|
+
communication on electronic mailing lists, source code control systems,
|
|
57
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
58
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
59
|
+
excluding communication that is conspicuously marked or otherwise
|
|
60
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
61
|
+
|
|
62
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
63
|
+
on behalf of whom a Contribution has been received by the Licensor and
|
|
64
|
+
subsequently incorporated within the Work.
|
|
65
|
+
|
|
66
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
67
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
68
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
69
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
70
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
71
|
+
Work and such Derivative Works in Source or Object form.
|
|
72
|
+
|
|
73
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
74
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
75
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
76
|
+
(except as stated in this section) patent license to make, have made,
|
|
77
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
78
|
+
where such license applies only to those patent claims licensable
|
|
79
|
+
by such Contributor that are necessarily infringed by their
|
|
80
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
81
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
82
|
+
institute patent litigation against any entity (including a
|
|
83
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
84
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
85
|
+
or contributory patent infringement, then any patent licenses
|
|
86
|
+
granted to You under this License for that Work shall terminate
|
|
87
|
+
as of the date such litigation is filed.
|
|
88
|
+
|
|
89
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
90
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
91
|
+
modifications, and in Source or Object form, provided that You
|
|
92
|
+
meet the following conditions:
|
|
93
|
+
|
|
94
|
+
(a) You must give any other recipients of the Work or
|
|
95
|
+
Derivative Works a copy of this License; and
|
|
96
|
+
|
|
97
|
+
(b) You must cause any modified files to carry prominent notices
|
|
98
|
+
stating that You changed the files; and
|
|
99
|
+
|
|
100
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
101
|
+
that You distribute, all copyright, patent, trademark, and
|
|
102
|
+
attribution notices from the Source form of the Work,
|
|
103
|
+
excluding those notices that do not pertain to any part of
|
|
104
|
+
the Derivative Works; and
|
|
105
|
+
|
|
106
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
107
|
+
distribution, then any Derivative Works that You distribute must
|
|
108
|
+
include a readable copy of the attribution notices contained
|
|
109
|
+
within such NOTICE file, excluding any notices that do not
|
|
110
|
+
pertain to any part of the Derivative Works, in at least one
|
|
111
|
+
of the following places: within a NOTICE text file distributed
|
|
112
|
+
as part of the Derivative Works; within the Source form or
|
|
113
|
+
documentation, if provided along with the Derivative Works; or,
|
|
114
|
+
within a display generated by the Derivative Works, if and
|
|
115
|
+
wherever such third-party notices normally appear. The contents
|
|
116
|
+
of the NOTICE file are for informational purposes only and
|
|
117
|
+
do not modify the License. You may add Your own attribution
|
|
118
|
+
notices within Derivative Works that You distribute, alongside
|
|
119
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
120
|
+
that such additional attribution notices cannot be construed
|
|
121
|
+
as modifying the License.
|
|
122
|
+
|
|
123
|
+
You may add Your own copyright statement to Your modifications and
|
|
124
|
+
may provide additional or different license terms and conditions
|
|
125
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
126
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
127
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
128
|
+
the conditions stated in this License.
|
|
129
|
+
|
|
130
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
131
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
132
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
133
|
+
this License, without any additional terms or conditions.
|
|
134
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
135
|
+
the terms of any separate license agreement you may have executed
|
|
136
|
+
with Licensor regarding such Contributions.
|
|
137
|
+
|
|
138
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
139
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
140
|
+
except as required for reasonable and customary use in describing the
|
|
141
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
142
|
+
|
|
143
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
144
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
145
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
146
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
147
|
+
implied, including, without limitation, any warranties or conditions
|
|
148
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
149
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
150
|
+
appropriateness of using or redistributing the Work and assume any
|
|
151
|
+
risks associated with Your exercise of permissions under this License.
|
|
152
|
+
|
|
153
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
154
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
155
|
+
unless required by applicable law (such as deliberate and grossly
|
|
156
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
157
|
+
liable to You for damages, including any direct, indirect, special,
|
|
158
|
+
incidental, or consequential damages of any character arising as a
|
|
159
|
+
result of this License or out of the use or inability to use the
|
|
160
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
161
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
162
|
+
other commercial damages or losses), even if such Contributor
|
|
163
|
+
has been advised of the possibility of such damages.
|
|
164
|
+
|
|
165
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
166
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
167
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
168
|
+
or other liability obligations and/or rights consistent with this
|
|
169
|
+
License. However, in accepting such obligations, You may act only
|
|
170
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
171
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
172
|
+
defend, and hold each Contributor harmless for any liability
|
|
173
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
174
|
+
of your accepting any such warranty or additional liability.
|
|
175
|
+
|
|
176
|
+
END OF TERMS AND CONDITIONS
|
|
177
|
+
|
|
178
|
+
Copyright 2026 David Strupl
|
|
179
|
+
|
|
180
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
181
|
+
you may not use this file except in compliance with the License.
|
|
182
|
+
You may obtain a copy of the License at
|
|
183
|
+
|
|
184
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
185
|
+
|
|
186
|
+
Unless required by applicable law or agreed to in writing, software
|
|
187
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
188
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
189
|
+
See the License for the specific language governing permissions and
|
|
190
|
+
limitations under the License.
|