@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.
- package/MANIFEST.json +11 -11
- package/RELEASES.md +23 -0
- package/agents/engineering-agent-django.md +216 -0
- package/agents/engineering-agent-flutter.md +257 -0
- package/agents/engineering-agent-typescript.md +2 -0
- package/agents/engineering-agent.md +4 -0
- package/agents/qa-agent.md +1 -1
- package/agents/tera-system-evolution.md +8 -6
- package/agents/tera.md +2 -0
- package/assets/architecture/security-team.dsl +64 -0
- package/commands/tera-help.md +2 -0
- package/commands/tera-orient-django.md +12 -0
- package/commands/tera-orient-flutter.md +12 -0
- package/core/tera-system/AGENT_ACTIVATION_MATRIX.md +5 -3
- package/core/tera-system/AGENT_DEPENDENCY_MAP.md +4 -2
- package/core/tera-system/AGENT_PERMISSION_MODEL.md +1 -1
- package/core/tera-system/TERA_DISTRIBUTION_POLICY.md +20 -14
- package/core/tera-system/TeraArchitectureMap.md +1 -1
- package/core/tera-system/TeraCapabilityMap.md +3 -3
- package/core/tera-system/TeraHelperAgents.md +2 -2
- package/core/tera-system/TeraPolicyMap.md +1 -1
- package/core/tera-system/TeraSubAgents.md +7 -5
- package/core/tera-system/profiles/PROFILES_INDEX.md +1 -1
- package/core/tera-system/profiles/flutter-mobile.md +1 -0
- package/core/tera-system/profiles/python-django.md +222 -0
- package/package.json +2 -2
- package/tools/tera-schedule.ps1 +1 -1
|
@@ -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
|
-
"description": "Tera System OpenCode Plugin — governance core,
|
|
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": {
|
package/tools/tera-schedule.ps1
CHANGED
|
@@ -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/
|
|
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)
|