@opslane/claude-code-game 0.1.0

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.
Files changed (201) hide show
  1. package/dist/cli.d.ts +2 -0
  2. package/dist/cli.js +59 -0
  3. package/dist/cli.js.map +1 -0
  4. package/dist/routes/auth.d.ts +1 -0
  5. package/dist/routes/auth.js +123 -0
  6. package/dist/routes/auth.js.map +1 -0
  7. package/dist/routes/levels.d.ts +44 -0
  8. package/dist/routes/levels.js +78 -0
  9. package/dist/routes/levels.js.map +1 -0
  10. package/dist/routes/sessions.d.ts +17 -0
  11. package/dist/routes/sessions.js +303 -0
  12. package/dist/routes/sessions.js.map +1 -0
  13. package/dist/server.d.ts +2 -0
  14. package/dist/server.js +58 -0
  15. package/dist/server.js.map +1 -0
  16. package/dist/terminal.d.ts +6 -0
  17. package/dist/terminal.js +23 -0
  18. package/dist/terminal.js.map +1 -0
  19. package/dist/verification.d.ts +31 -0
  20. package/dist/verification.js +239 -0
  21. package/dist/verification.js.map +1 -0
  22. package/frontend/assets/index-CNVEnbfs.css +1 -0
  23. package/frontend/assets/index-D70xl9zu.js +27 -0
  24. package/frontend/index.html +14 -0
  25. package/frontend/vite.svg +1 -0
  26. package/keys/v1.pem +9 -0
  27. package/levels/01-context-is-everything/exercise/README.md +152 -0
  28. package/levels/01-context-is-everything/exercise/data/expenses.db +0 -0
  29. package/levels/01-context-is-everything/exercise/database.py +171 -0
  30. package/levels/01-context-is-everything/exercise/docs/FIRECRAWL_QUICKSTART.md +212 -0
  31. package/levels/01-context-is-everything/exercise/historical_data/expenses_2024_01.json +2306 -0
  32. package/levels/01-context-is-everything/exercise/historical_data/expenses_2024_02.json +2394 -0
  33. package/levels/01-context-is-everything/exercise/historical_data/expenses_2024_03.json +2251 -0
  34. package/levels/01-context-is-everything/exercise/historical_data/expenses_2024_04.json +1987 -0
  35. package/levels/01-context-is-everything/exercise/historical_data/expenses_2024_05.json +2229 -0
  36. package/levels/01-context-is-everything/exercise/main.py +97 -0
  37. package/levels/01-context-is-everything/exercise/models.py +141 -0
  38. package/levels/01-context-is-everything/exercise/pyproject.toml +52 -0
  39. package/levels/01-context-is-everything/exercise/reports.py +138 -0
  40. package/levels/01-context-is-everything/exercise/seed_data.py +91 -0
  41. package/levels/01-context-is-everything/exercise/tests/__init__.py +1 -0
  42. package/levels/01-context-is-everything/exercise/tests/conftest.py +69 -0
  43. package/levels/01-context-is-everything/exercise/tests/test_database.py +244 -0
  44. package/levels/01-context-is-everything/exercise/tests/test_models.py +240 -0
  45. package/levels/01-context-is-everything/exercise/tests/test_reports.py +190 -0
  46. package/levels/01-context-is-everything/exercise/utils.py +163 -0
  47. package/levels/01-context-is-everything/lesson.yaml +82 -0
  48. package/levels/02-claude-md/exercise/README.md +152 -0
  49. package/levels/02-claude-md/exercise/data/expenses.db +0 -0
  50. package/levels/02-claude-md/exercise/database.py +171 -0
  51. package/levels/02-claude-md/exercise/main.py +97 -0
  52. package/levels/02-claude-md/exercise/models.py +141 -0
  53. package/levels/02-claude-md/exercise/pyproject.toml +52 -0
  54. package/levels/02-claude-md/exercise/reports.py +138 -0
  55. package/levels/02-claude-md/exercise/seed_data.py +91 -0
  56. package/levels/02-claude-md/exercise/tests/__init__.py +1 -0
  57. package/levels/02-claude-md/exercise/tests/conftest.py +69 -0
  58. package/levels/02-claude-md/exercise/tests/test_database.py +244 -0
  59. package/levels/02-claude-md/exercise/tests/test_models.py +240 -0
  60. package/levels/02-claude-md/exercise/tests/test_reports.py +190 -0
  61. package/levels/02-claude-md/exercise/utils.py +163 -0
  62. package/levels/02-claude-md/lesson.yaml +60 -0
  63. package/levels/03-read-edit-verify/exercise/CLAUDE.md +15 -0
  64. package/levels/03-read-edit-verify/exercise/README.md +152 -0
  65. package/levels/03-read-edit-verify/exercise/data/expenses.db +0 -0
  66. package/levels/03-read-edit-verify/exercise/database.py +171 -0
  67. package/levels/03-read-edit-verify/exercise/main.py +97 -0
  68. package/levels/03-read-edit-verify/exercise/models.py +141 -0
  69. package/levels/03-read-edit-verify/exercise/pyproject.toml +52 -0
  70. package/levels/03-read-edit-verify/exercise/reports.py +138 -0
  71. package/levels/03-read-edit-verify/exercise/seed_data.py +91 -0
  72. package/levels/03-read-edit-verify/exercise/tests/__init__.py +1 -0
  73. package/levels/03-read-edit-verify/exercise/tests/conftest.py +69 -0
  74. package/levels/03-read-edit-verify/exercise/tests/test_database.py +244 -0
  75. package/levels/03-read-edit-verify/exercise/tests/test_models.py +240 -0
  76. package/levels/03-read-edit-verify/exercise/tests/test_reports.py +190 -0
  77. package/levels/03-read-edit-verify/exercise/utils.py +163 -0
  78. package/levels/03-read-edit-verify/lesson.yaml +60 -0
  79. package/levels/04-planning-mode/exercise/README.md +152 -0
  80. package/levels/04-planning-mode/exercise/data/expenses.db +0 -0
  81. package/levels/04-planning-mode/exercise/database.py +171 -0
  82. package/levels/04-planning-mode/exercise/main.py +97 -0
  83. package/levels/04-planning-mode/exercise/models.py +116 -0
  84. package/levels/04-planning-mode/exercise/pyproject.toml +52 -0
  85. package/levels/04-planning-mode/exercise/reports.py +138 -0
  86. package/levels/04-planning-mode/exercise/seed_data.py +91 -0
  87. package/levels/04-planning-mode/exercise/tests/__init__.py +1 -0
  88. package/levels/04-planning-mode/exercise/tests/conftest.py +69 -0
  89. package/levels/04-planning-mode/exercise/tests/test_database.py +244 -0
  90. package/levels/04-planning-mode/exercise/tests/test_expenses.db +0 -0
  91. package/levels/04-planning-mode/exercise/tests/test_models.py +240 -0
  92. package/levels/04-planning-mode/exercise/tests/test_reports.py +190 -0
  93. package/levels/04-planning-mode/exercise/utils.py +163 -0
  94. package/levels/04-planning-mode/lesson.yaml +53 -0
  95. package/levels/05-spec-driven/exercise/README.md +152 -0
  96. package/levels/05-spec-driven/exercise/data/expenses.db +0 -0
  97. package/levels/05-spec-driven/exercise/database.py +171 -0
  98. package/levels/05-spec-driven/exercise/main.py +97 -0
  99. package/levels/05-spec-driven/exercise/models.py +116 -0
  100. package/levels/05-spec-driven/exercise/pyproject.toml +52 -0
  101. package/levels/05-spec-driven/exercise/reports.py +138 -0
  102. package/levels/05-spec-driven/exercise/seed_data.py +91 -0
  103. package/levels/05-spec-driven/exercise/tests/__init__.py +1 -0
  104. package/levels/05-spec-driven/exercise/tests/conftest.py +69 -0
  105. package/levels/05-spec-driven/exercise/tests/test_database.py +244 -0
  106. package/levels/05-spec-driven/exercise/tests/test_expenses.db +0 -0
  107. package/levels/05-spec-driven/exercise/tests/test_models.py +240 -0
  108. package/levels/05-spec-driven/exercise/tests/test_reports.py +190 -0
  109. package/levels/05-spec-driven/exercise/utils.py +163 -0
  110. package/levels/05-spec-driven/lesson.yaml +53 -0
  111. package/levels/06-sub-agents/exercise/README.md +152 -0
  112. package/levels/06-sub-agents/exercise/data/expenses.db +0 -0
  113. package/levels/06-sub-agents/exercise/database.py +171 -0
  114. package/levels/06-sub-agents/exercise/main.py +97 -0
  115. package/levels/06-sub-agents/exercise/models.py +116 -0
  116. package/levels/06-sub-agents/exercise/pyproject.toml +52 -0
  117. package/levels/06-sub-agents/exercise/reports.py +63 -0
  118. package/levels/06-sub-agents/exercise/seed_data.py +91 -0
  119. package/levels/06-sub-agents/exercise/tests/__init__.py +1 -0
  120. package/levels/06-sub-agents/exercise/tests/conftest.py +69 -0
  121. package/levels/06-sub-agents/exercise/tests/test_database.py +244 -0
  122. package/levels/06-sub-agents/exercise/tests/test_models.py +240 -0
  123. package/levels/06-sub-agents/exercise/tests/test_reports.py +190 -0
  124. package/levels/06-sub-agents/exercise/utils.py +163 -0
  125. package/levels/06-sub-agents/lesson.yaml +49 -0
  126. package/levels/07-skills/exercise/README.md +152 -0
  127. package/levels/07-skills/exercise/data/expenses.db +0 -0
  128. package/levels/07-skills/exercise/database.py +171 -0
  129. package/levels/07-skills/exercise/main.py +97 -0
  130. package/levels/07-skills/exercise/models.py +116 -0
  131. package/levels/07-skills/exercise/pyproject.toml +52 -0
  132. package/levels/07-skills/exercise/reports.py +63 -0
  133. package/levels/07-skills/exercise/seed_data.py +91 -0
  134. package/levels/07-skills/exercise/tests/__init__.py +1 -0
  135. package/levels/07-skills/exercise/tests/conftest.py +69 -0
  136. package/levels/07-skills/exercise/tests/test_database.py +244 -0
  137. package/levels/07-skills/exercise/tests/test_models.py +240 -0
  138. package/levels/07-skills/exercise/tests/test_reports.py +190 -0
  139. package/levels/07-skills/exercise/utils.py +163 -0
  140. package/levels/07-skills/lesson.yaml +49 -0
  141. package/levels/08-mcp-servers/exercise/README.md +152 -0
  142. package/levels/08-mcp-servers/exercise/data/expenses.db +0 -0
  143. package/levels/08-mcp-servers/exercise/database.py +171 -0
  144. package/levels/08-mcp-servers/exercise/main.py +97 -0
  145. package/levels/08-mcp-servers/exercise/models.py +116 -0
  146. package/levels/08-mcp-servers/exercise/pyproject.toml +52 -0
  147. package/levels/08-mcp-servers/exercise/reports.py +63 -0
  148. package/levels/08-mcp-servers/exercise/seed_data.py +91 -0
  149. package/levels/08-mcp-servers/exercise/tests/__init__.py +1 -0
  150. package/levels/08-mcp-servers/exercise/tests/conftest.py +69 -0
  151. package/levels/08-mcp-servers/exercise/tests/test_database.py +244 -0
  152. package/levels/08-mcp-servers/exercise/tests/test_models.py +240 -0
  153. package/levels/08-mcp-servers/exercise/tests/test_reports.py +190 -0
  154. package/levels/08-mcp-servers/exercise/utils.py +163 -0
  155. package/levels/08-mcp-servers/lesson.yaml +59 -0
  156. package/levels/09-plugins/exercise/README.md +152 -0
  157. package/levels/09-plugins/exercise/data/expenses.db +0 -0
  158. package/levels/09-plugins/exercise/database.py +171 -0
  159. package/levels/09-plugins/exercise/main.py +97 -0
  160. package/levels/09-plugins/exercise/models.py +116 -0
  161. package/levels/09-plugins/exercise/pyproject.toml +52 -0
  162. package/levels/09-plugins/exercise/reports.py +63 -0
  163. package/levels/09-plugins/exercise/seed_data.py +91 -0
  164. package/levels/09-plugins/exercise/tests/__init__.py +1 -0
  165. package/levels/09-plugins/exercise/tests/conftest.py +69 -0
  166. package/levels/09-plugins/exercise/tests/test_database.py +244 -0
  167. package/levels/09-plugins/exercise/tests/test_models.py +240 -0
  168. package/levels/09-plugins/exercise/tests/test_reports.py +190 -0
  169. package/levels/09-plugins/exercise/utils.py +163 -0
  170. package/levels/09-plugins/lesson.yaml +51 -0
  171. package/levels/10-hooks/exercise/README.md +152 -0
  172. package/levels/10-hooks/exercise/data/expenses.db +0 -0
  173. package/levels/10-hooks/exercise/database.py +171 -0
  174. package/levels/10-hooks/exercise/main.py +97 -0
  175. package/levels/10-hooks/exercise/models.py +116 -0
  176. package/levels/10-hooks/exercise/pyproject.toml +52 -0
  177. package/levels/10-hooks/exercise/reports.py +63 -0
  178. package/levels/10-hooks/exercise/seed_data.py +91 -0
  179. package/levels/10-hooks/exercise/tests/__init__.py +1 -0
  180. package/levels/10-hooks/exercise/tests/conftest.py +69 -0
  181. package/levels/10-hooks/exercise/tests/test_database.py +244 -0
  182. package/levels/10-hooks/exercise/tests/test_models.py +240 -0
  183. package/levels/10-hooks/exercise/tests/test_reports.py +190 -0
  184. package/levels/10-hooks/exercise/utils.py +163 -0
  185. package/levels/10-hooks/lesson.yaml +58 -0
  186. package/levels/11-worktrees/exercise/README.md +152 -0
  187. package/levels/11-worktrees/exercise/data/expenses.db +0 -0
  188. package/levels/11-worktrees/exercise/database.py +171 -0
  189. package/levels/11-worktrees/exercise/main.py +97 -0
  190. package/levels/11-worktrees/exercise/models.py +116 -0
  191. package/levels/11-worktrees/exercise/pyproject.toml +52 -0
  192. package/levels/11-worktrees/exercise/reports.py +63 -0
  193. package/levels/11-worktrees/exercise/seed_data.py +91 -0
  194. package/levels/11-worktrees/exercise/tests/__init__.py +1 -0
  195. package/levels/11-worktrees/exercise/tests/conftest.py +69 -0
  196. package/levels/11-worktrees/exercise/tests/test_database.py +244 -0
  197. package/levels/11-worktrees/exercise/tests/test_models.py +240 -0
  198. package/levels/11-worktrees/exercise/tests/test_reports.py +190 -0
  199. package/levels/11-worktrees/exercise/utils.py +163 -0
  200. package/levels/11-worktrees/lesson.yaml +68 -0
  201. package/package.json +38 -0
package/frontend/index.html ADDED
@@ -0,0 +1,14 @@
1
+ <!doctype html>
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="UTF-8" />
5
+ <link rel="icon" type="image/svg+xml" href="/vite.svg" />
6
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
7
+ <title>frontend</title>
8
+ <script type="module" crossorigin src="/assets/index-D70xl9zu.js"></script>
9
+ <link rel="stylesheet" crossorigin href="/assets/index-CNVEnbfs.css">
10
+ </head>
11
+ <body>
12
+ <div id="root"></div>
13
+ </body>
14
+ </html>
package/frontend/vite.svg ADDED
@@ -0,0 +1 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="iconify iconify--logos" width="31.88" height="32" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 257"><defs><linearGradient id="IconifyId1813088fe1fbc01fb466" x1="-.828%" x2="57.636%" y1="7.652%" y2="78.411%"><stop offset="0%" stop-color="#41D1FF"></stop><stop offset="100%" stop-color="#BD34FE"></stop></linearGradient><linearGradient id="IconifyId1813088fe1fbc01fb467" x1="43.376%" x2="50.316%" y1="2.242%" y2="89.03%"><stop offset="0%" stop-color="#FFEA83"></stop><stop offset="8.333%" stop-color="#FFDD35"></stop><stop offset="100%" stop-color="#FFA800"></stop></linearGradient></defs><path fill="url(#IconifyId1813088fe1fbc01fb466)" d="M255.153 37.938L134.897 252.976c-2.483 4.44-8.862 4.466-11.382.048L.875 37.958c-2.746-4.814 1.371-10.646 6.827-9.67l120.385 21.517a6.537 6.537 0 0 0 2.322-.004l117.867-21.483c5.438-.991 9.574 4.796 6.877 9.62Z"></path><path fill="url(#IconifyId1813088fe1fbc01fb467)" d="M185.432.063L96.44 17.501a3.268 3.268 0 0 0-2.634 3.014l-5.474 92.456a3.268 3.268 0 0 0 3.997 3.378l24.777-5.718c2.318-.535 4.413 1.507 3.936 3.838l-7.361 36.047c-.495 2.426 1.782 4.5 4.151 3.78l15.304-4.649c2.372-.72 4.652 1.36 4.15 3.788l-11.698 56.621c-.732 3.542 3.979 5.473 5.943 2.437l1.313-2.028l72.516-144.72c1.215-2.423-.88-5.186-3.54-4.672l-25.505 4.922c-2.396.462-4.435-1.77-3.759-4.114l16.646-57.705c.677-2.35-1.37-4.583-3.769-4.113Z"></path></svg>
package/keys/v1.pem ADDED
@@ -0,0 +1,9 @@
1
+ -----BEGIN PUBLIC KEY-----
2
+ MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAsW5tJXvqMaNpaVUesq0A
3
+ CPk6FDPfR6IlgpfSqxTOVTuGfAtQLmp6IIRm2FSBBdxoTPW2rOgoI7HucLm1U2U2
4
+ oPecAlDHjj/JVcH7NbWBjG/v6FiaYaQd9jtFOdLLfKJg80fz1xpnFp5Q0DOXayBU
5
+ KlAa3kQgTfALx3kdBJtgAnRNYj2wDJrHzWq5PqqIT9iPxfb3TjEXGzufx9AXqKXR
6
+ zMwLvXAas7lJgXziSXTGjOrc28BgCFVNzP4cPuAHJSTG0e/nXqhVaa40t80/zuJb
7
+ FTVNmW5+eI4JcbV1bLnP0JxogWxBf9AOFjIZPc2N8mBXsi3in+IUx3FDzTVZ0l8j
8
+ mwIDAQAB
9
+ -----END PUBLIC KEY-----
package/levels/01-context-is-everything/exercise/README.md ADDED
@@ -0,0 +1,152 @@
1
+ # Expense Tracker
2
+
3
+ A simple CLI expense tracker built with Python and SQLite.
4
+
5
+ This is the project used throughout the Claude Code course. You'll learn to use
6
+ Claude Code to understand, debug, and extend this codebase.
7
+
8
+ ## Quick Start
9
+
10
+ ```bash
11
+ # 1. Seed the database with sample data
12
+ python seed_data.py
13
+
14
+ # 2. Try some commands
15
+ python main.py list
16
+ python main.py summary
17
+ python main.py list --category Food
18
+ ```
19
+
20
+ ## Commands
21
+
22
+ ### Add an expense
23
+ ```bash
24
+ python main.py add <amount> <category> <description> [--date YYYY-MM-DD]
25
+
26
+ # Examples:
27
+ python main.py add 45.50 Food "Grocery shopping"
28
+ python main.py add 25.00 Transport "Uber" --date 2026-01-15
29
+ ```
30
+
31
+ ### List expenses
32
+ ```bash
33
+ python main.py list [--category CATEGORY] [--month YYYY-MM] [--limit N]
34
+
35
+ # Examples:
36
+ python main.py list
37
+ python main.py list --category Food
38
+ python main.py list --month 2026-01
39
+ python main.py list --limit 5
40
+ ```
41
+
42
+ ### Show expense details
43
+ ```bash
44
+ python main.py show <expense_id>
45
+
46
+ # Example:
47
+ python main.py show abc123
48
+ ```
49
+
50
+ ### Delete an expense
51
+ ```bash
52
+ python main.py delete <expense_id>
53
+
54
+ # Example:
55
+ python main.py delete abc123
56
+ ```
57
+
58
+ ### View spending summary
59
+ ```bash
60
+ python main.py summary
61
+ ```
62
+
63
+ ## Running Tests
64
+
65
+ ```bash
66
+ # Run all tests
67
+ pytest
68
+
69
+ # Run with verbose output
70
+ pytest -v
71
+
72
+ # Run specific test file
73
+ pytest tests/test_models.py
74
+
75
+ # Run tests matching a pattern
76
+ pytest -k "category"
77
+ ```
78
+
79
+ ## Project Structure
80
+
81
+ ```
82
+ expense_tracker/
83
+ ├── main.py # CLI entry point
84
+ ├── models.py # Expense data model and core functions
85
+ ├── database.py # SQLite database operations
86
+ ├── utils.py # Helper functions (formatting, parsing)
87
+ ├── reports.py # Report generation (Lesson 4)
88
+ ├── seed_data.py # Script to populate sample data
89
+ ├── tests/
90
+ │ ├── conftest.py # Pytest fixtures
91
+ │ ├── test_models.py # Model tests
92
+ │ ├── test_database.py # Database tests
93
+ │ └── test_reports.py # Report tests (Lesson 4)
94
+ ├── data/
95
+ │ └── expenses.db # SQLite database (created on first run)
96
+ └── README.md
97
+ ```
98
+
99
+ ## Course Lessons
100
+
101
+ This codebase is used in the following lessons:
102
+
103
+ | Lesson | Focus | What You'll Do |
104
+ |--------|-------|----------------|
105
+ | 1 | Context | Explore the codebase, see context limits |
106
+ | 2 | CLAUDE.md | Create project memory |
107
+ | 3 | Bug Fix | Fix the negative amount validation bug |
108
+ | 4 | Debugging | Fix the case-sensitive category bug |
109
+ | 5 | Specs | Add recurring expenses feature |
110
+ | 6 | Planning | Implement the reports module |
111
+ | 7+ | Building Blocks | Create commands, skills, workflows |
112
+
113
+ ## Known Issues (For Learning)
114
+
115
+ This codebase has intentional bugs for learning purposes:
116
+
117
+ 1. **Negative amounts accepted** (Lesson 3)
118
+ - `add_expense()` doesn't validate that amount > 0
119
+ - Tests `test_add_negative_amount_should_fail` and `test_add_zero_amount_should_fail` fail
120
+
121
+ 2. **Case-sensitive category filtering** (a later lesson)
122
+ - `list_expenses(category="Food")` won't find expenses with category "food" or "FOOD"
123
+ - Test `test_list_by_category_case_insensitive` fails
124
+
125
+ 3. **Reports not implemented** (Lesson 4)
126
+ - `reports.py` has stub functions that raise `NotImplementedError`
127
+ - All tests in `test_reports.py` are skipped until implementation
128
+
129
+ ## Development
130
+
131
+ ### Requirements
132
+ - Python 3.10+
133
+ - pytest (for running tests)
134
+
135
+ ### Setup
136
+ ```bash
137
+ # Create virtual environment (optional but recommended)
138
+ python -m venv venv
139
+ source venv/bin/activate # On Windows: venv\Scripts\activate
140
+
141
+ # Install dev dependencies
142
+ pip install pytest ruff
143
+
144
+ # Initialize database
145
+ python seed_data.py
146
+ ```
147
+
148
+ ### Code Style
149
+ - Type hints on all function signatures
150
+ - Docstrings on public functions
151
+ - Black-compatible formatting
152
+ - No unused imports
package/levels/01-context-is-everything/exercise/database.py ADDED
@@ -0,0 +1,171 @@
1
+ """SQLite database operations for expense storage."""
2
+
3
+ import sqlite3
4
+ import os
5
+ from pathlib import Path
6
+ from datetime import datetime
7
+ from typing import Optional, TYPE_CHECKING
8
+ from contextlib import contextmanager
9
+
10
+ if TYPE_CHECKING:
11
+ from models import Expense
12
+
13
+ # Database path - use environment variable for testing, otherwise default location
14
+ DB_PATH = Path(os.environ.get(
15
+ "EXPENSE_DB_PATH",
16
+ Path(__file__).parent / "data" / "expenses.db"
17
+ ))
18
+
19
+
20
+ @contextmanager
21
+ def get_connection():
22
+ """Get a database connection with proper cleanup.
23
+
24
+ Yields:
25
+ sqlite3.Connection with Row factory enabled
26
+
27
+ Example:
28
+ with get_connection() as conn:
29
+ conn.execute("SELECT * FROM expenses")
30
+ """
31
+ conn = sqlite3.connect(DB_PATH)
32
+ conn.row_factory = sqlite3.Row
33
+ try:
34
+ yield conn
35
+ conn.commit()
36
+ finally:
37
+ conn.close()
38
+
39
+
40
+ def init_db() -> None:
41
+ """Initialize the database schema.
42
+
43
+ Creates the expenses table if it doesn't exist.
44
+ Also creates the data directory if needed.
45
+ """
46
+ DB_PATH.parent.mkdir(parents=True, exist_ok=True)
47
+
48
+ with get_connection() as conn:
49
+ conn.execute('''
50
+ CREATE TABLE IF NOT EXISTS expenses (
51
+ id TEXT PRIMARY KEY,
52
+ amount REAL NOT NULL,
53
+ category TEXT NOT NULL,
54
+ description TEXT,
55
+ date TEXT NOT NULL,
56
+ recurring INTEGER DEFAULT 0,
57
+ recurring_frequency TEXT
58
+ )
59
+ ''')
60
+
61
+
62
+ def save_expense(expense: "Expense") -> None:
63
+ """Save an expense to the database.
64
+
65
+ Args:
66
+ expense: The Expense object to save
67
+ """
68
+ with get_connection() as conn:
69
+ conn.execute('''
70
+ INSERT INTO expenses (id, amount, category, description, date, recurring, recurring_frequency)
71
+ VALUES (?, ?, ?, ?, ?, ?, ?)
72
+ ''', (
73
+ expense.id,
74
+ expense.amount,
75
+ expense.category,
76
+ expense.description,
77
+ expense.date.isoformat(),
78
+ 1 if expense.recurring else 0,
79
+ expense.recurring_frequency
80
+ ))
81
+
82
+
83
+ def load_expenses() -> list["Expense"]:
84
+ """Load all expenses from the database.
85
+
86
+ Returns:
87
+ List of all Expense objects, ordered by date descending
88
+ """
89
+ from models import Expense # Import here to avoid circular import
90
+
91
+ with get_connection() as conn:
92
+ rows = conn.execute('SELECT * FROM expenses ORDER BY date DESC').fetchall()
93
+
94
+ expenses = []
95
+ for row in rows:
96
+ expenses.append(Expense(
97
+ id=row['id'],
98
+ amount=row['amount'],
99
+ category=row['category'],
100
+ description=row['description'],
101
+ date=datetime.fromisoformat(row['date']),
102
+ recurring=bool(row['recurring']),
103
+ recurring_frequency=row['recurring_frequency']
104
+ ))
105
+
106
+ return expenses
107
+
108
+
109
+ def get_expense_by_id(expense_id: str) -> Optional["Expense"]:
110
+ """Get a single expense by ID.
111
+
112
+ Args:
113
+ expense_id: The unique expense ID
114
+
115
+ Returns:
116
+ The Expense if found, None otherwise
117
+ """
118
+ from models import Expense # Import here to avoid circular import
119
+
120
+ with get_connection() as conn:
121
+ row = conn.execute(
122
+ 'SELECT * FROM expenses WHERE id = ?',
123
+ (expense_id,)
124
+ ).fetchone()
125
+
126
+ if not row:
127
+ return None
128
+
129
+ return Expense(
130
+ id=row['id'],
131
+ amount=row['amount'],
132
+ category=row['category'],
133
+ description=row['description'],
134
+ date=datetime.fromisoformat(row['date']),
135
+ recurring=bool(row['recurring']),
136
+ recurring_frequency=row['recurring_frequency']
137
+ )
138
+
139
+
140
+ def remove_expense(expense_id: str) -> bool:
141
+ """Remove an expense from the database.
142
+
143
+ Args:
144
+ expense_id: The unique expense ID
145
+
146
+ Returns:
147
+ True if an expense was deleted, False if not found
148
+ """
149
+ with get_connection() as conn:
150
+ cursor = conn.execute('DELETE FROM expenses WHERE id = ?', (expense_id,))
151
+ return cursor.rowcount > 0
152
+
153
+
154
+ def clear_all_expenses() -> None:
155
+ """Clear all expenses from the database.
156
+
157
+ WARNING: This deletes all data! Use only for testing.
158
+ """
159
+ with get_connection() as conn:
160
+ conn.execute('DELETE FROM expenses')
161
+
162
+
163
+ def get_expense_count() -> int:
164
+ """Get the total number of expenses.
165
+
166
+ Returns:
167
+ Count of expenses in database
168
+ """
169
+ with get_connection() as conn:
170
+ row = conn.execute('SELECT COUNT(*) as count FROM expenses').fetchone()
171
+ return row['count']
package/levels/01-context-is-everything/exercise/docs/FIRECRAWL_QUICKSTART.md ADDED
@@ -0,0 +1,212 @@
1
+ # Firecrawl Python SDK - Quick Start Guide
2
+
3
+ > **Version:** 1.x
4
+ > **Last Updated:** October 2024
5
+
6
+ Turn any website into clean, LLM-ready markdown with Firecrawl.
7
+
8
+ ## Installation
9
+
10
+ ```bash
11
+ pip install firecrawl-py
12
+ ```
13
+
14
+ ## Quick Start
15
+
16
+ ```python
17
+ from firecrawl import FirecrawlApp
18
+
19
+ # Initialize the client
20
+ app = FirecrawlApp(api_key="fc-YOUR-API-KEY")
21
+
22
+ # Scrape a single URL
23
+ result = app.scrape_url("https://example.com")
24
+ print(result["markdown"])
25
+ ```
26
+
27
+ ## Core Methods
28
+
29
+ ### `scrape_url()`
30
+
31
+ Scrape a single URL and get its content.
32
+
33
+ ```python
34
+ from firecrawl import FirecrawlApp
35
+
36
+ app = FirecrawlApp(api_key="fc-YOUR-API-KEY")
37
+
38
+ # Basic scrape
39
+ result = app.scrape_url("https://docs.firecrawl.dev")
40
+
41
+ # With options
42
+ result = app.scrape_url(
43
+ "https://docs.firecrawl.dev",
44
+ params={
45
+ "formats": ["markdown", "html"],
46
+ "onlyMainContent": True
47
+ }
48
+ )
49
+
50
+ print(result["markdown"])
51
+ ```
52
+
53
+ **Parameters:**
54
+ - `url` (str): The URL to scrape
55
+ - `params` (dict, optional): Scrape options
56
+ - `formats`: List of output formats ("markdown", "html", "rawHtml")
57
+ - `onlyMainContent`: Remove headers/footers (default: True)
58
+
59
+ **Returns:** Dictionary with `markdown`, `html`, `metadata`
60
+
61
+ ---
62
+
63
+ ### `crawl_url()`
64
+
65
+ Crawl an entire website starting from a URL.
66
+
67
+ ```python
68
+ from firecrawl import FirecrawlApp
69
+
70
+ app = FirecrawlApp(api_key="fc-YOUR-API-KEY")
71
+
72
+ # Crawl a site
73
+ result = app.crawl_url(
74
+ "https://docs.firecrawl.dev",
75
+ params={
76
+ "maxDepth": 2,
77
+ "limit": 10,
78
+ "ignoreSitemap": True
79
+ }
80
+ )
81
+
82
+ for page in result:
83
+ print(page["metadata"]["title"])
84
+ ```
85
+
86
+ **Parameters:**
87
+ - `url` (str): Starting URL
88
+ - `params` (dict, optional): Crawl options
89
+ - `maxDepth`: How deep to crawl (default: 2)
90
+ - `limit`: Maximum pages to crawl
91
+ - `ignoreSitemap`: Skip sitemap discovery (default: False)
92
+ - `allowBackwardCrawling`: Allow crawling parent paths
93
+
94
+ **Returns:** List of page results
95
+
96
+ ---
97
+
98
+ ### `async_crawl_url()`
99
+
100
+ Start an async crawl job for large sites.
101
+
102
+ ```python
103
+ from firecrawl import FirecrawlApp
104
+ import time
105
+
106
+ app = FirecrawlApp(api_key="fc-YOUR-API-KEY")
107
+
108
+ # Start async crawl
109
+ job = app.async_crawl_url(
110
+ "https://docs.firecrawl.dev",
111
+ params={"maxDepth": 3, "limit": 100}
112
+ )
113
+
114
+ job_id = job["jobId"]
115
+ print(f"Started crawl job: {job_id}")
116
+
117
+ # Poll for completion
118
+ while True:
119
+ status = app.check_crawl_status(job_id)
120
+ if status["status"] == "completed":
121
+ break
122
+ print(f"Progress: {status['completed']}/{status['total']}")
123
+ time.sleep(5)
124
+
125
+ # Get results
126
+ print(f"Crawled {len(status['data'])} pages")
127
+ ```
128
+
129
+ ---
130
+
131
+ ### `map_url()`
132
+
133
+ Discover all URLs on a website without scraping content.
134
+
135
+ ```python
136
+ from firecrawl import FirecrawlApp
137
+
138
+ app = FirecrawlApp(api_key="fc-YOUR-API-KEY")
139
+
140
+ # Map a website
141
+ urls = app.map_url("https://firecrawl.dev")
142
+
143
+ print(f"Found {len(urls)} URLs:")
144
+ for url in urls[:10]:
145
+ print(f" - {url}")
146
+ ```
147
+
148
+ **Parameters:**
149
+ - `url` (str): The website to map
150
+ - `params` (dict, optional): Map options
151
+ - `search`: Filter URLs by keyword
152
+ - `limit`: Maximum URLs to return
153
+
154
+ **Returns:** List of discovered URLs
155
+
156
+ ---
157
+
158
+ ## Complete Example
159
+
160
+ ```python
161
+ from firecrawl import FirecrawlApp
162
+
163
+ def scrape_documentation(base_url: str, api_key: str) -> list[dict]:
164
+ """Scrape all pages from a documentation site."""
165
+
166
+ app = FirecrawlApp(api_key=api_key)
167
+
168
+ # First, map the site to find all URLs
169
+ all_urls = app.map_url(base_url, params={"limit": 50})
170
+
171
+ # Then crawl with depth limit
172
+ results = app.crawl_url(
173
+ base_url,
174
+ params={
175
+ "maxDepth": 2,
176
+ "limit": 20,
177
+ "ignoreSitemap": True
178
+ }
179
+ )
180
+
181
+ return results
182
+
183
+ # Usage
184
+ docs = scrape_documentation(
185
+ "https://docs.example.com",
186
+ "fc-YOUR-API-KEY"
187
+ )
188
+ ```
189
+
190
+ ## Error Handling
191
+
192
+ ```python
193
+ from firecrawl import FirecrawlApp
194
+ from firecrawl.exceptions import FirecrawlError
195
+
196
+ app = FirecrawlApp(api_key="fc-YOUR-API-KEY")
197
+
198
+ try:
199
+ result = app.scrape_url("https://example.com")
200
+ except FirecrawlError as e:
201
+ print(f"Scrape failed: {e}")
202
+ ```
203
+
204
+ ## Rate Limits
205
+
206
+ - Free tier: 500 credits/month
207
+ - Scrape: 1 credit per page
208
+ - Crawl: 1 credit per page crawled
209
+
210
+ ---
211
+
212
+ *For full documentation, visit [docs.firecrawl.dev](https://docs.firecrawl.dev)*