@tera-system/core 0.4.0 → 0.5.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.
@@ -0,0 +1,222 @@
1
+ # Python Django Technology Profile
2
+
3
+ ## 1. Purpose
4
+
5
+ This profile provides Python/Django/DRF-specific execution rules for backend API projects in the Tera system.
6
+
7
+ It is a **stack-specific Technology Profile** — loaded only when a project is classified as Backend with Django + Django REST Framework as the chosen stack.
8
+
9
+ ## 2. Identity
10
+
11
+ | Field | Value |
12
+ |---|---|
13
+ | Profile ID | `python-django` |
14
+ | Stack | Python 3.12+ + Django 5.x + Django REST Framework + PostgreSQL |
15
+ | Minimum Python | 3.12+ |
16
+ | Minimum Django | 5.0+ (DRF 3.14+) |
17
+ | Status | Available |
18
+ | Owner | Tera Agent (decision engine) / engineering-agent-django (execution) |
19
+
20
+ ## 3. When to Load This Profile
21
+
22
+ Load `python-django.md` when:
23
+
24
+ - Project classification = **Backend API**
25
+ - Technology stack confirmed as **Django + DRF + PostgreSQL**
26
+ - `project-control/PROJECT_STATE.md` or `project-preparation/08_TECHNICAL_ARCHITECTURE.md` records `Active Technology Profile: python-django`
27
+
28
+ ### Automatic activation triggers
29
+
30
+ | Trigger | Action |
31
+ |---|---|
32
+ | Project type = Backend AND Stack = Django/DRF | Load `python-django.md` as active profile |
33
+ | `PROJECT_STATE.md` sets `python-django` | Load immediately |
34
+ | Pre-Execution Gate detects Django + DRF | Verify profile is loaded; BLOCKED if not |
35
+
36
+ ## 4. Project Structure
37
+
38
+ Standard Django project layout:
39
+
40
+ ```
41
+ config/ # settings, urls, wsgi/asgi
42
+ settings/
43
+ base.py
44
+ development.py
45
+ production.py
46
+ apps/
47
+ {app_name}/
48
+ models.py
49
+ serializers.py
50
+ views.py # viewsets
51
+ urls.py # router registration
52
+ tests/
53
+ test_models.py
54
+ test_api.py
55
+ admin.py
56
+ migrations/
57
+ manage.py
58
+ requirements.txt (or pyproject.toml)
59
+ Dockerfile
60
+ ```
61
+
62
+ ### Rules
63
+
64
+ - One Django app per bounded domain — do not create a single `core` app holding everything.
65
+ - Settings must be split (`base`/`development`/`production`) — never a single `settings.py` with `if DEBUG`.
66
+ - `manage.py` stays at the root — do not move it.
67
+ - Tests live inside each app (`tests/`), never in a detached top-level folder.
68
+
69
+ ## 5. Architecture Guidance (DRF)
70
+
71
+ | Concern | Recommendation |
72
+ |---|---|
73
+ | Views | `ModelViewSet` / `GenericAPIView` + mixins — no fat function views for CRUD |
74
+ | Routing | DRF `DefaultRouter` registered per app `urls.py`, included from `config/urls.py` |
75
+ | Serializers | Explicit `fields` lists — never `fields = "__all__"`; nested writes only with explicit `create()`/`update()` |
76
+ | Validation | Serializer-level first; `validate_<field>` / `validate()`; never trust client payload shape |
77
+ | Filtering/Search/Ordering | `django-filter` `FilterSet` + DRF `SearchFilter` + `OrderingFilter` |
78
+ | Pagination | DRF pagination globally (`PageNumberPagination`, explicit `PAGE_SIZE`); never unbounded list endpoints |
79
+ | API docs | `drf-spectacular` — schema must generate cleanly (`spectacular --validate`) |
80
+ | Background work | Celery / django-q2 only when approved in scope; otherwise synchronous with timeouts |
81
+
82
+ ### Architecture rules
83
+
84
+ - Do not add Repository / Unit-of-Work / CQRS layers by default — Django ORM + serializers are the boundary.
85
+ - Do not expose the Django admin to end users unless explicitly in scope (staff-only, hardened).
86
+ - Every list endpoint must be paginated and every filter must be an explicit `FilterSet` field.
87
+ - `drf-spectacular` schema generation must pass without warnings on changed endpoints.
88
+
89
+ ## 6. Authentication (SimpleJWT)
90
+
91
+ | Item | Rule |
92
+ |---|---|
93
+ | Library | `djangorestframework-simplejwt` |
94
+ | Token pair | Short-lived access + rotating refresh; blacklist on logout (`rest_framework_simplejwt.token_blacklist`) |
95
+ | Storage guidance for clients | HttpOnly cookie or platform secure storage — never `localStorage` for web clients |
96
+ | Rotation | `ROTATE_REFRESH_TOKENS = True`, `BLACKLIST_AFTER_ROTATION = True` |
97
+
98
+ ## 7. Permissions — Server-Side Enforcement (Non-Negotiable)
99
+
100
+ ```text
101
+ لا يُعتمد أي endpoint بصلاحية client-side فقط.
102
+ الفرض دائماً server-side: permission_classes على كل view/viewset.
103
+ ```
104
+
105
+ | Rule | Notes |
106
+ |---|---|
107
+ | Default permission | `IsAuthenticated` globally (`DEFAULT_PERMISSION_CLASSES`); open endpoints only with explicit, documented `AllowAny` + reason |
108
+ | Object-level | `has_object_permission` for any row-scoped access; never filter only in the serializer |
109
+ | Financial / PII / admin actions | Explicit permission class + SecurityAgent review when sensitive (crosses to `tera-system/TeraPreExecutionGate.md` risk rules) |
110
+ | Throttling | DRF throttles on auth + write endpoints (`AnonRateThrottle`, `UserRateThrottle`, scoped rates for login/token) |
111
+
112
+ ## 8. Database (PostgreSQL)
113
+
114
+ | Item | Rule |
115
+ |---|---|
116
+ | Engine | PostgreSQL via `psycopg` — no SQLite in any shared/staging/production environment |
117
+ | Migrations | Review every generated migration + SQL (`sqlmigrate`) before applying; **never apply to shared/staging/production unless the task explicitly authorizes that environment** |
118
+ | Destructive ops | `DropModel` / `RemoveField` / narrowing / data transforms require an explicit, reviewed plan + backup note; `managed = False` tables require an explicit contract (read-only unless stated) |
119
+ | Query shape | `select_related` / `prefetch_related` for FK/M2M reads; bound/paginate; no N+1 in list endpoints |
120
+ | Transactions | `transaction.atomic()` only where multi-write atomicity is required — not a default wrapper |
121
+
122
+ ## 9. Testing
123
+
124
+ | Type | Tool | Notes |
125
+ |---|---|---|
126
+ | Unit / API tests | `pytest` + `pytest-django` | Models, serializers, permissions, endpoints |
127
+ | System check | `python manage.py check` | Must pass with zero errors |
128
+ | Migration check | `python manage.py makemigrations --check --dry-run` | Must report "No changes detected" on a clean tree |
129
+ | Schema check | `spectacular --validate` (via drf-spectacular) | Must pass on changed endpoints |
130
+
131
+ ### Rules
132
+
133
+ - `pytest` must pass with zero failures before handover.
134
+ - Every permission class must have a direct test (allowed / denied / object-level).
135
+ - Every changed endpoint must be tested for: success, validation failure, unauthenticated, forbidden.
136
+ - Do not test Django internals; test project code.
137
+
138
+ ## 10. Environment Verification
139
+
140
+ ```bash
141
+ # Python version
142
+ python --version
143
+
144
+ # Install / sync dependencies
145
+ pip install -r requirements.txt
146
+
147
+ # Django system check (zero errors required)
148
+ python manage.py check
149
+
150
+ # Pending migrations check (clean tree required)
151
+ python manage.py makemigrations --check --dry-run
152
+
153
+ # Run test suite
154
+ python -m pytest
155
+ ```
156
+
157
+ ## 11. Docker / Coolify
158
+
159
+ | Item | Rule |
160
+ |---|---|
161
+ | Image | `python:3.12-slim` base; multi-stage if the project requires compiled deps |
162
+ | Server | `gunicorn` (sync workers) or `uvicorn` (ASGI) — per approved architecture, not both |
163
+ | Static files | `collectstatic` at build; served by the platform/CDN, never by Django in production |
164
+ | Env | All secrets via environment (`django-environ`); no `.env` committed; `DEBUG = False` + explicit `ALLOWED_HOSTS` in production |
165
+
166
+ ## 12. Security (Reference Only)
167
+
168
+ Refer to existing Tera security policies:
169
+
170
+ - `project-preparation/15_SECURITY_AND_ACCESS_CONTROL.md`
171
+ - `tera-system/TeraPreExecutionGate.md` (secret handling rules)
172
+ - `project-preparation/PROJECT_RULES.md`
173
+
174
+ Django-specific security notes:
175
+
176
+ - Never hard-code `SECRET_KEY`, DB credentials, or API keys — env only (Semgrep `tera-no-hardcoded-secrets` python rules apply).
177
+ - `DEBUG = False` + `ALLOWED_HOSTS` set in any non-local environment.
178
+ - `SECURE_SSL_REDIRECT`, `SESSION_COOKIE_SECURE`, `CSRF_COOKIE_SECURE` in production.
179
+ - CORS: explicit allowlist (`django-cors-headers`) — never `CORS_ALLOW_ALL_ORIGINS = True` in production.
180
+ - Validate `X-Forwarded-*` only behind a trusted proxy.
181
+
182
+ ## 13. QA / Acceptance (Reference Only)
183
+
184
+ Refer to:
185
+
186
+ - `project-preparation/10_TESTING_AND_ACCEPTANCE.md`
187
+ - `tera-system/runtime/TERA_RUNTIME_CHECKLISTS.md`
188
+
189
+ Django QA rules:
190
+
191
+ - Endpoint matrix per changed endpoint: success / validation failure / unauthenticated (401) / forbidden (403).
192
+ - Contract stability: `drf-spectacular` diff reviewed for breaking changes.
193
+ - Migration safety: `sqlmigrate` reviewed; destructive ops only with explicit authorization.
194
+ - Permission tests: direct allow/deny/object-level coverage.
195
+
196
+ ## 14. Known Django Limits (Document These)
197
+
198
+ | Limit | Notes |
199
+ |---|---|
200
+ | **Sync ORM in async views** | Use `sync_to_async` / async ORM carefully; do not mix casually |
201
+ | **Realtime** | Channels/WebSockets only when in scope; otherwise poll or document as deferred |
202
+ | **Heavy background** | Celery/queue only when approved; default to synchronous with timeouts |
203
+ | **managed = False** | Read-only unless an explicit contract says otherwise; schema changes need DBA coordination |
204
+
205
+ ## 15. References
206
+
207
+ | Topic | Source |
208
+ |---|---|
209
+ | Django docs | https://docs.djangoproject.com |
210
+ | DRF docs | https://www.django-rest-framework.org |
211
+ | SimpleJWT | https://django-rest-framework-simplejwt.readthedocs.io |
212
+ | django-filter | https://django-filter.readthedocs.io |
213
+ | drf-spectacular | https://drf-spectacular.readthedocs.io |
214
+ | Tera Pre-Execution Gate | `tera-system/TeraPreExecutionGate.md` |
215
+ | Tera QA/Acceptance | `tera-system/runtime/TERA_RUNTIME_CHECKLISTS.md` |
216
+
217
+ ## 16. Profile Version
218
+
219
+ - **Current Profile Version:** 1.0.0
220
+ - **Created:** 2026-09-23 — SCP-2026-09-23-006 (prerequisite for `engineering-agent-django`)
221
+ - **Maintainer:** TeraSystemEvolutionAgent (حارس)
222
+ - **Django Baseline:** 5.x + DRF 3.14+ · **Python Baseline:** 3.12+ · **DB:** PostgreSQL
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@tera-system/core",
3
- "version": "0.4.0",
4
- "description": "Tera System OpenCode Plugin — governance core, 23 agents, 35 commands, distribution tools (personal edition)",
3
+ "version": "0.5.0",
4
+ "description": "Tera System OpenCode Plugin — governance core, 25 agents, 37 commands, distribution tools (personal edition)",
5
5
  "license": "SEE LICENSE IN LICENSE.md",
6
6
  "type": "module",
7
7
  "engines": {
@@ -4,7 +4,7 @@
4
4
  tera-watch.ps1 -Once at logon and every -IntervalHours hours.
5
5
 
6
6
  Usage:
7
- tera-schedule.ps1 -RepositoryUrl "https://github.com/Alabasi1980/TeraSystem.git" -RepoPath "D:\My Projects\TeraWebsite"
7
+ tera-schedule.ps1 -RepositoryUrl "https://github.com/Alabasi1980/Teranoo-System-Core.git" -RepoPath "D:\My Projects\TeraWebsite"
8
8
  tera-schedule.ps1 -Unregister
9
9
 
10
10
  Source of truth: tera-system/TERA_DISTRIBUTION_POLICY.md (SCP-2026-08-15-013)