@tera-system/core 0.2.19 → 0.3.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 (35) hide show
  1. package/MANIFEST.json +6 -6
  2. package/RELEASES.md +28 -0
  3. package/agents/auditor.md +17 -0
  4. package/agents/design-reviewer.md +12 -3
  5. package/agents/tera.md +48 -76
  6. package/agents/ui-designer.md +31 -0
  7. package/commands/tera-approve.md +34 -34
  8. package/commands/tera-diagnose.md +47 -47
  9. package/commands/tera-gate.md +40 -40
  10. package/commands/tera-help.md +41 -41
  11. package/commands/tera-new-project.md +35 -35
  12. package/commands/tera-plan.md +34 -34
  13. package/commands/tera-request-build.md +45 -45
  14. package/commands/tera-resume.md +34 -34
  15. package/commands/tera-review.md +52 -52
  16. package/commands/tera-status.md +38 -38
  17. package/commands/tera-update.md +48 -48
  18. package/core/tera-system/AGENT_ACTIVATION_MATRIX.md +2 -0
  19. package/core/tera-system/AGENT_DEPENDENCY_MAP.md +4 -4
  20. package/core/tera-system/TOOLING_AND_MCP_POLICY.md +81 -1
  21. package/core/tera-system/TeraArchitectureMap.md +3 -0
  22. package/core/tera-system/TeraCapabilityMap.md +4 -4
  23. package/core/tera-system/TeraPolicyMap.md +3 -1
  24. package/core/tera-system/image-generation/ASSET_POLICY.md +149 -0
  25. package/core/tera-system/image-generation/IMAGE_TOOL_CONTRACT.md +341 -0
  26. package/core/tera-system/profiles/PROFILES_INDEX.md +1 -0
  27. package/core/tera-system/profiles/node-ts-coolify-postgres.md +93 -0
  28. package/core/tera-system/profiles/rust.md +164 -0
  29. package/core/tera-system/runtime/TERA_RUNTIME_PROTOCOLS.md +1 -1
  30. package/core/tera-system/runtime/TERA_RUNTIME_TEMPLATES.md +5 -4
  31. package/core/tera-system/runtime/TERA_RUNTIME_TEMPLATES_DELIVERY.md +59 -0
  32. package/core/tera-system/semgrep-rules/tera-security.yml +119 -10
  33. package/package.json +2 -2
  34. package/scripts/install.js +20 -15
  35. package/scripts/tera-license.mjs +0 -63
@@ -0,0 +1,341 @@
1
+ <!-- © 2026 Majed Khaireddin (Alabasi1980). Tera System — Proprietary. All rights reserved. -->
2
+
3
+ # IMAGE_TOOL_CONTRACT.md
4
+
5
+ > **مصدر الحقيقة لعقد أدوات توليد الصور في Teranoo.**
6
+ > SCP-2026-09-12-002 — النطاق: تعريفات وحدود فقط. صفر كود مزود، صفر API wiring.
7
+ > أي نقطة تتطلب قراراً جديداً أو تغيّر المعمارية: STOP وارفعها كـIssue بدل حلها بصمت.
8
+
9
+ ---
10
+
11
+ ## 1. القاعدة الذهبية للفصل
12
+
13
+ ```text
14
+ Adapter يعرف المزود فقط.
15
+ Tool Layer تعرف المشروع والسياسة فقط.
16
+ الوكيل يعرف النية فقط.
17
+ ```
18
+
19
+ | المسؤولية | Tool Layer | Provider Adapter |
20
+ |-----------|-----------|------------------|
21
+ | التحقق من المدخلات | ✅ | ❌ |
22
+ | Cost Guard | ✅ | ❌ (يبلّغ التكلفة فقط إن توفرت) |
23
+ | سياسة الأصول | ✅ (انظر `ASSET_POLICY.md`) | ❌ |
24
+ | `prompt_hash` + `prompt_ref` | ✅ | ❌ |
25
+ | كتابة Metadata JSON | ✅ | ❌ |
26
+ | إدارة المؤقتات (`temp_uri` lifecycle) | ✅ | ❌ |
27
+ | ترجمة الأخطاء لرموز موحدة | ✅ | يرفع خطأ مزود خام فقط |
28
+ | مفاتيح API / أسرار | ❌ (لا يراها أبداً) | ✅ (من البيئة فقط) |
29
+ | ترجمة hints لقيم المزود | ❌ | ✅ |
30
+ | استدعاء HTTP للمزود | ❌ | ✅ (تعريف حدود فقط في هذه المرحلة — لا تنفيذ) |
31
+ | معرفة مسارات المشروع أو الـapproval | ❌ | ❌ (ممنوع) |
32
+
33
+ ---
34
+
35
+ ## 2. `generate_image`
36
+
37
+ **الغرض:** إنشاء صورة جديدة من وصف نصي. تُرجع ناتجاً مؤقتاً فقط — لا تحفظ في المشروع مباشرة.
38
+
39
+ ### Input
40
+
41
+ | الحقل | إلزامي؟ | القاعدة |
42
+ |-------|---------|---------|
43
+ | `prompt` | ✅ | نص غير فارغ، 10–2000 حرف. التطبيع قبل الـhash (trim + توحيد المسافات) |
44
+ | `asset_type` | ✅ | واحد من: `reference / production / icon / marketing` — نية الاستخدام، لا مسار الحفظ |
45
+ | `project_path` | ✅ | مسار مشروع موجود — للـCost Guard والـMetadata فقط |
46
+ | `model_hint` | اختياري (`auto`) | `fast / precision / auto` فقط. **ممنوع ذكر أسماء موديلات حرفية هنا — تبقى داخل الـAdapter** |
47
+ | `size_hint` | اختياري (`auto`) | `square / landscape / portrait / auto` — تُترجم داخل الـAdapter |
48
+ | `quality_hint` | اختياري (`auto`) | `draft / standard / high` — تُترجم داخل الـAdapter |
49
+ | `use_baseline` | اختياري (`true`) | إن كان `true` يُستدعى `read_visual_baseline` أولاً ويُرفق مرجعه |
50
+ | `provider` | اختياري (`auto`) | `auto / local / openai` — اختيار صريح فقط، بلا fallback آلي. `auto` = المحلي أولاً (مجاني). ضروري لتمرير الاختيار بشكل مجرد — لا أسماء موديلات هنا |
51
+
52
+ ### Output
53
+
54
+ ```text
55
+ image_id opaque temporary ID — ليس file path — له expires_at
56
+ provider اسم المزود ("openai")
57
+ model_used الاسم الفعلي الذي استخدمه الـAdapter (يُسجَّل هنا فقط، لا يُطلب به)
58
+ width / height / format
59
+ temp_uri internal only — لا يُعتمد كمسار مشروع
60
+ prompt_hash sha256 النص المطبّع
61
+ expires_at UTC ISO8601 — بعدها save_asset يرفض بـ EXPIRED_IMAGE_ID
62
+ created_at UTC ISO8601
63
+ cost_estimate إن توفر من المزود، وإلا "unknown"
64
+ baseline_missing true/false — هل وُجدت baseline عند التوليد
65
+ ```
66
+
67
+ ### Validation (قبل أي اتصال بالمزود)
68
+
69
+ 1. `prompt` ضمن الطول وغير فارغ.
70
+ 2. `asset_type` من القائمة المغلقة.
71
+ 3. `project_path` موجود.
72
+ 4. **Cost Guard** يسمح — وإلا رفض قبل الاتصال.
73
+ 5. `use_baseline=true` ولا baseline → **لا فشل** — المتابعة مع `baseline_missing=true` (قاعدة الاعتماد في §6 تمنع تحويله لـapproved لاحقاً).
74
+
75
+ ### Errors
76
+
77
+ | الكود | المعنى | السلوك |
78
+ |-------|--------|--------|
79
+ | `INVALID_INPUT` | حقل مرفوض | لا اتصال بالمزود |
80
+ | `COST_GUARD_BLOCKED` | الحد يمنع | STOP — لا fallback |
81
+ | `PROVIDER_REJECTED_PROMPT` | رفض سلامة من المزود | تُمرَّر رسالة المزود كما هي — لا إعادة تلقائية |
82
+ | `PROVIDER_UNAVAILABLE` | عطل/Timeout | STOP — لا fallback تلقائي لمزود آخر |
83
+ | `TIMEOUT` | تجاوز المهلة | كـ `PROVIDER_UNAVAILABLE` |
84
+
85
+ > لا إعادة محاولة تلقائية. لا fallback تلقائي. أي إعادة قرار صريح من الوكيل أو Majed.
86
+
87
+ ---
88
+
89
+ ## 3. `edit_image`
90
+
91
+ **الغرض:** تعديل صورة موجودة بتعليمات نصية. تُرجع ناتجاً مؤقتاً (مثل generate).
92
+
93
+ ### Input
94
+
95
+ | الحقل | إلزامي؟ | القاعدة |
96
+ |-------|---------|---------|
97
+ | `source_ref` | ✅ | `image_id` مؤقت صالح أو مسار asset موجود داخل المشروع |
98
+ | `edit_prompt` | ✅ | نفس قواعد `prompt` (10–2000) |
99
+ | `asset_type` | ✅ | نية ناتج التعديل (قد تختلف عن المصدر) |
100
+ | `project_path` | ✅ | كما في generate |
101
+ | `model_hint` | اختياري (`precision`) | التعديل الدقيق يميل للدقة افتراضياً |
102
+ | `provider` | اختياري (`auto`) | `auto / local / openai` — كما في generate، بلا fallback |
103
+
104
+ ### Output
105
+
106
+ نفس Output الـgenerate + حقل إضافي:
107
+
108
+ ```text
109
+ parent_ref الـsource_ref الأصلي — سلسلة النسب
110
+ ```
111
+
112
+ ### Validation
113
+
114
+ 1. `source_ref` موجود وقابل للقراءة.
115
+ 2. الصيغة من: `png / jpg / webp` فقط (الباقي لاحقاً — Class C).
116
+ 3. حد حجم المصدر يُحدَّد في الـAdapter (لا يُثبَّت هنا).
117
+ 4. Cost Guard قبل الاتصال.
118
+ 5. **قاعدة المصدر المقيّد:** مصدر (`ownership=third-party` أو `usage_rights=restricted`) → الناتج `reference` فقط. تحويله لـ`production/icon/marketing` يتطلب `rights_override_ref` موثقاً (انظر `ASSET_POLICY.md` §4).
119
+
120
+ ### Errors
121
+
122
+ نفس أخطاء generate +:
123
+
124
+ | الكود | المعنى |
125
+ |-------|--------|
126
+ | `SOURCE_NOT_FOUND` | المرجع غير موجود |
127
+ | `UNSUPPORTED_FORMAT` | صيغة غير مدعومة |
128
+ | `RESTRICTED_SOURCE` | مصدر مقيّد لا يقبل التحويل لإنتاج بلا override |
129
+ | `EXPIRED_IMAGE_ID` | `image_id` مؤقت منتهي (إن كان المصدر مؤقتاً) |
130
+
131
+ ---
132
+
133
+ ## 4. `save_asset`
134
+
135
+ **الغرض:** الوحيدة التي تكتب داخل `project-assets/`. الفصل بين الإنشاء والحفظ مقصود — هذه نقطة الحوكمة الحقيقية.
136
+
137
+ ### Input
138
+
139
+ | الحقل | إلزامي؟ | القاعدة |
140
+ |-------|---------|---------|
141
+ | `image_id` | ✅ | ناتج generate/edit صالح وغير منتهي |
142
+ | `project_path` | ✅ | |
143
+ | `asset_type` | ✅ | يحدد المجلد الفرعي حصراً (انظر `ASSET_POLICY.md` §2) |
144
+ | `filename` | اختياري | إن غاب يُولَّد اسم آمن. التطهير إلزامي: `[a-z0-9-_]` + امتداد ثابت — أي `../` أو مسار مطلق = `PATH_TRAVERSAL` |
145
+ | `overwrite` | اختياري (`false`) | |
146
+ | `usage_rights` | مشروط | **إلزامي إن كان `asset_type ≠ reference`** — `internal / commercial / restricted` |
147
+ | `ownership` | مشروط | **إلزامي إن كان `asset_type ≠ reference`** — `teranoo / client / third-party`. لا تُستنتج من النوع أبداً |
148
+ | `approval_ref` | اختياري | مرجع تفويض — انظر §6 (لا يكفي وحده) |
149
+ | `approval_scope` | مشروط | **إلزامي مع `approval_ref`** — `task_authorized / asset_preapproval / explicit_approval` (انظر §6) |
150
+ | `rights_override_ref` | مشروط | إلزامي عند تخفيف قيود مصدر مقيّد (انظر `ASSET_POLICY.md` §4) |
151
+
152
+ ### Output
153
+
154
+ ```text
155
+ final_path داخل project-assets/visual/{type}/ حصراً
156
+ metadata_path ملف JSON بجانب الصورة (نفس الاسم + .meta.json)
157
+ approval_status draft / approved (حسب §6 فقط)
158
+ ```
159
+
160
+ ### Validation
161
+
162
+ 1. `image_id` صالح وغير منتهي — وإلا `EXPIRED_IMAGE_ID`.
163
+ 2. المجلد الهدف واحد من الأربعة المعتمدة فقط.
164
+ 3. `filename` مطهّر.
165
+ 4. `overwrite=false` والملف موجود = `ASSET_EXISTS`.
166
+ 5. **حماية المعتمد:** الكتابة فوق asset حالته `approved` مرفوضة دائماً إلا بـ `overwrite=true` + `approval_scope=explicit_approval` جديد.
167
+ 6. `usage_rights` + `ownership` إلزاميان لغير المرجعي — وإلا `MISSING_RIGHTS`.
168
+ 7. قاعدة Rights Laundering (انظر `ASSET_POLICY.md` §4).
169
+
170
+ ### Errors
171
+
172
+ | الكود | المعنى |
173
+ |-------|--------|
174
+ | `ASSET_EXISTS` | الملف موجود و `overwrite=false` |
175
+ | `APPROVED_OVERWRITE_BLOCKED` | كتابة فوق معتمد بدون تفويض صريح جديد |
176
+ | `PATH_TRAVERSAL` | اسم ملف غير آمن |
177
+ | `MISSING_RIGHTS` | `usage_rights/ownership` ناقصة لغير المرجعي |
178
+ | `INVALID_ASSET_TYPE` | نوع خارج القائمة |
179
+ | `EXPIRED_IMAGE_ID` | المعرف المؤقت منتهي |
180
+ | `RIGHTS_LAUNDERING_BLOCKED` | تخفيف قيود بلا override موثق |
181
+ | `BASELINE_REQUIRED_FOR_APPROVAL` | إنتاجي بلا baseline وبلا override (انظر §6) |
182
+
183
+ ---
184
+
185
+ ## 5. `read_visual_baseline`
186
+
187
+ **الغرض:** أداة سياق مشروع مشتركة (وليست Image Tool حرفياً). تُستدعى قبل أي توليد بصري مهم.
188
+
189
+ ### Input
190
+
191
+ | الحقل | إلزامي؟ |
192
+ |-------|---------|
193
+ | `project_path` | ✅ |
194
+
195
+ ### Output (الحد الأدنى — لا توسعة)
196
+
197
+ ```text
198
+ exists true / false
199
+ colors
200
+ typography
201
+ icon_direction
202
+ visual_tone
203
+ approved_assets قائمة مراجع
204
+ style_guide_path إن وجد
205
+ ```
206
+
207
+ ### السلوك
208
+
209
+ غياب الـbaseline **ليس خطأ** — يُرجع `exists=false` وحقولاً فارغة. الـgenerate يتابع مع `baseline_missing=true`، وقاعدة §6 تمنع الاعتماد.
210
+
211
+ ### Errors
212
+
213
+ `PROJECT_NOT_FOUND` فقط.
214
+
215
+ ---
216
+
217
+ ## 6. قواعد الاعتماد (Approval Rules)
218
+
219
+ ```text
220
+ reference
221
+ → auto-save
222
+ → approval_status = draft (لا يحتاج approval أصلاً)
223
+
224
+ production / icon / marketing
225
+ → تُحفظ دائماً كـ draft أولاً
226
+ → تصبح approved فقط بإحدى:
227
+ (أ) approval_scope = asset_preapproval ضمن مهمة مخولة
228
+ (ب) approval_scope = explicit_approval لاحق (ملف أو مجموعة)
229
+ → approval_scope = task_authorized وحده لا يكفي أبداً
230
+ → baseline_missing=true تمنع الـapproved حتى: توجد baseline
231
+ أو approval_scope يتضمن override صريحاً موثقاً
232
+ ```
233
+
234
+ > Tool Layer **لا تعتمد بنفسها** — تثبت الحالة حسب النطاق المقدَّم. لا Approval Engine في هذه المرحلة.
235
+
236
+ ---
237
+
238
+ ## 7. عقد Metadata (13 حقلاً: 10 أساسية + 3 provenance حوكمي)
239
+
240
+ ```json
241
+ {
242
+ "asset_type": "reference | production | icon | marketing",
243
+ "provider": "openai",
244
+ "model": "gpt-image-2.5-flare",
245
+ "created_at": "2026-09-12T14:30:00Z",
246
+ "prompt_hash": "sha256:...",
247
+ "prompt_ref": "prompts/2026-09-12/abc123.txt",
248
+ "source_refs": ["wireframe-v1.png"],
249
+ "approval_status": "draft | approved | rejected",
250
+ "usage_rights": "internal | commercial | restricted",
251
+ "ownership": "teranoo | client | third-party",
252
+
253
+ "approval_ref": null,
254
+ "approval_scope": null,
255
+ "rights_override_ref": null
256
+ }
257
+ ```
258
+
259
+ - `prompt_ref` اختياري — مسار سجل النص الكامل (لا يُخزَّن النص الحساس داخل كل Metadata).
260
+ - الحقول الثلاثة الأخيرة **nullable/optional** — provenance حوكمي يوثّق *لماذا* اعتُمد الأصل أو خُفف قيده. ليست Audit Framework — مجرد أدلة القرار ملتصقة بالأصل نفسه.
261
+ - لغير المرجعي: `usage_rights` + `ownership` إلزاميان.
262
+ - للمرجعي: افتراضي `internal / teranoo` (أو `third-party` إن كان المصدر خارجياً).
263
+
264
+ ### 7.1 مصدر كل حقل: النظام أم المتصل (قاعدة صريحة — أمنية)
265
+
266
+ ```text
267
+ Provider/model/prompt/lineage/temp-generation metadata
268
+ is system-derived from image_id and cannot be overridden by the caller.
269
+ ```
270
+
271
+ | الحقل | المصدر | هل يقبله `save_asset` من المتصل؟ |
272
+ |-------|--------|----------------------------------|
273
+ | `provider`, `model`, `created_at` | النظام — من سجل `image_id` المؤقت | ❌ مرفوض (`INVALID_INPUT`) إن قُدِّم |
274
+ | `prompt_hash`, `prompt_ref` | النظام — من سجل `image_id` المؤقت | ❌ مرفوض إن قُدِّم |
275
+ | `source_refs` (النسب) | النظام — من `parent_ref`/سلسلة المصدر | ❌ مرفوض إن قُدِّم — يمنع حذف النسب وإظهار الأصل غير مشتق |
276
+ | `baseline_missing` | النظام — من لحظة التوليد | ❌ لا يُمرَّر أصلاً |
277
+ | `approval_status` | النظام — محسوب من `approval_scope` + القواعد (§6) | ❌ المتصل يقدّم `approval_ref/scope` فقط، والحالة تُحسب |
278
+ | `asset_type`, `filename` | المتصل — قرار نية/تسمية | ✅ |
279
+ | `usage_rights`, `ownership` | المتصل — قرار تجاري/حوكمي | ✅ (إلزاميان لغير المرجعي) |
280
+ | `approval_ref`, `approval_scope` | المتصل — دليل التفويض | ✅ (النطاق إلزامي مع المرجع) |
281
+ | `rights_override_ref` | المتصل — دليل تخفيف القيد | ✅ (مشروط — انظر `ASSET_POLICY.md` §4) |
282
+
283
+ > السبب: وكيل سيئ أو مخطئ لا يستطيع تزوير المزوّد أو حذف `source_refs` ليُظهر الأصل غير مشتق — هذه الحماية هي ما يجعل قاعدة Rights Laundering فعّالة فعلاً لا نظرياً.
284
+
285
+ ---
286
+
287
+ ## 8. دورة حياة المؤقتات (Temp Lifecycle Contract)
288
+
289
+ ```text
290
+ image_id → opaque temporary ID — مرتبط بجلسة/عملية — ليس file path — له expires_at
291
+ temp_uri → internal only — لا يُعتمد كمسار مشروع — يُحذف بعد expiry/session cleanup
292
+ save_asset(expired image_id) → EXPIRED_IMAGE_ID
293
+ ```
294
+
295
+ المدة الزمنية Configuration لاحقاً — لا تُثبَّت هنا.
296
+
297
+ ---
298
+
299
+ ## 9. `analyze_image` — قدرة مستقبلية فقط (ليست Tool الآن)
300
+
301
+ ```text
302
+ إن دعم موديل OpenCode الـVision مباشرة → يُمرَّر المرجع للنموذج (صفر أدوات).
303
+ وإلا → تُعرَّف analyze_image لاحقاً (image_ref → description).
304
+ ```
305
+
306
+ التصنيف: **C — Future Consideration.** المفهوم محفوظ، البناء مؤجل.
307
+
308
+ ---
309
+
310
+ ## 10. حدود صريحة (ممنوع في هذه المرحلة)
311
+
312
+ ```text
313
+ ❌ Provider implementation أو API wiring — الـAdapter تعريف حدود فقط
314
+ ❌ Agent جديد — التوسيع على ui-designer حصراً
315
+ ❌ Approval Engine / Cost Dashboard / Build Gate كامل
316
+ ❌ أدواتBeyond الأربع (resize/crop/convert/bg_remove/svg) — كلها Class C
317
+ ❌ تسريب أسماء الموديلات لعقد الوكيل — model_hint تجريد فقط
318
+ ❌ Automatic fallback بين المزودات
319
+ ❌ رقم Cost Guard ثابت في المعمارية — قابل للتهيئة فقط
320
+ ```
321
+
322
+ ---
323
+
324
+ ## 11. مرجع المزود الأول (تعريف حدود — لا تنفيذ)
325
+
326
+ ```text
327
+ OpenAIImageAdapter
328
+ ├─ model_hint=fast → موديل سريع للمهام اليومية (داخل الـAdapter فقط)
329
+ └─ model_hint=precision → موديل دقيق للتعديل والأصول النهائية (داخل الـAdapter فقط)
330
+ ```
331
+
332
+ ```text
333
+ LocalOpenVINOAdapter (المزود الافتراضي — قرار تنفيذي معتمد)
334
+ ├─ Stable Diffusion 1.5 INT8 عبر OpenVINO (optimum-intel)
335
+ ├─ الجهاز من TERA_IMAGE_LOCAL_DEVICE (الافتراضي GPU — هدف Intel Iris Xe)
336
+ ├─ model_hint يُقبل ويُتجاهل بالتصميم (موديل واحد محلياً)
337
+ ├─ provider=openai الصريح فقط يوجّه للمدفوع — لا fallback آلي أبداً
338
+ └─ cost_estimate = "free-local" — لا يحتاج مفتاحاً
339
+ ```
340
+
341
+ أسماء الموديلات الفعلية لا تظهر في أي عقد وكيل أو Tool Layer — تبقى داخل الـAdapters ليعزل تغيّرها لاحقاً. (أسماء المزودين `local/openai` مجردة ومسموحة على السطح — ليست أسماء موديلات.)
@@ -49,6 +49,7 @@ If the stack is still unclear, do not activate a final profile yet.
49
49
  | `react-pwa` | React 18 + Vite + TypeScript + Tailwind CSS (RTL) + Zustand + idb (IndexedDB) + Fuse.js + vite-plugin-pwa | ✅ **Approved — Active** | PWA محلي عربي (Offline Standalone) — فعّل Majed (2026-08-01, PREP-D-016) |
50
50
  | `flutter-mobile` | Flutter + Dart | Available | موبايل — يُحمَّل عند تصنيف المنتج موبايل (MVP_DEFINITION_PROTOCOL + MOBILE_UI_UX_STANDARDS) — (SCP-2026-09-04-003) |
51
51
  | `dotnet-razorpages-adonet` | .NET Razor Pages + ADO.NET | Available | تطبيقات أعمال داخلية + تكامل بيانات — (SCP-2026-09-04-003) |
52
+ | `rust` | Rust (cargo/rustc) — 2024 edition, Axum/Tauri/SQLx | **Draft — Needs Verification** | عام: CLI، خدمات عالية الأداء، Tauri، WebAssembly — لا متخصص، يعمل عبر engineering-agent (fallback)؛ الترقية لـ Available بعد تجربة تحقق (SCP-2026-09-04-011) |
52
53
 
53
54
  ## Placeholder Candidates
54
55
 
@@ -0,0 +1,93 @@
1
+ # Technology Profile: node-ts-coolify-postgres
2
+
3
+ > **Status:** APPROVED — approved by Majed 2026-09-15 (response: «اعتمد»).
4
+ > **Active for:** APP-DISCOVERY-SURVEY (CLIENT-TERANOO-INTERNAL) as of 2026-09-15.
5
+ > **First consumer:** APP-DISCOVERY-SURVEY (CLIENT-TERANOO-INTERNAL) — reusable for small internal Node+TS tools on Coolify + Postgres.
6
+
7
+ ## 1. Profile Identity
8
+
9
+ - Profile ID: `node-ts-coolify-postgres`
10
+ - Language: TypeScript (strict) on Node.js 20+
11
+ - Framework: None (existing host app code — e.g. `tera-website`: `tsx server/index.ts` :3001). No new framework unless task requires it.
12
+ - Database: PostgreSQL 17-alpine as separate Coolify service (never shared with another app's DB).
13
+ - ORM: Decided per project at first DB task (default recommendation: Prisma — migrations + seed; alternatives: Drizzle / raw SQL via `pg`). No lock at profile level.
14
+ - Package Manager / CLI: npm (+ `npx`) / Coolify (Nixpacks: `npm ci` + `npm run build`) / GitHub flow (branch → master → Coolify redeploy).
15
+ - Default Project Type: Small internal web tool mounted inside an existing Node+TS app folder (Track A).
16
+
17
+ ## 2. Applicability
18
+
19
+ Use when: (a) the host is an existing Node+TS app deployed on Coolify via Nixpacks; (b) persistence is a dedicated Postgres 17 service; (c) scope is a small internal MVP (no public signup, single-admin or token-gated access).
20
+ Do NOT use for: .NET/Blazor stacks, Flutter/mobile, Phaser games, public multi-tenant SaaS (needs stronger tenancy review first).
21
+
22
+ ## 3. Default Execution Order
23
+
24
+ ```text
25
+ Profile lock → Auth gate (if admin area) → DB service + migrations + seed + isolation check
26
+ → Token/access → Forms/workflows → Dashboard/admin → Export/print
27
+ → Ops (retention/cron/domain/SSL) → Acceptance (T-*) → Phase 7 closure
28
+ Prototype (mock, no DB) always precedes real implementation unless WAIVED_BY_MAJED.
29
+ ```
30
+
31
+ ## 4. First Task Rule
32
+
33
+ Safest first task: **isolated mock prototype** (`TASK-PROTO-*`, no DB, no secrets, no deploy) rendered from the approved Design Source, reviewed by DesignReviewer, approved by owner (Gate 6) — before any `TASK-COD-*`.
34
+
35
+ ## 5. Scaffold Rules
36
+
37
+ - No new Coolify Application for Track-A tools — modify inside the existing app folder only (`app/`), same pipeline, same repo branch.
38
+ - No new framework/scaffolder by default. New files live in the task's Allowed Write Targets (absolute paths) — never outside.
39
+ - Reuse host app conventions first (read existing code before adding files). Follow the Engineering File Quality mandate: semantic folders, no junk-drawer `utils/`, no mixed responsibilities, non-generated files > ~500 lines need justification or splitting, WHY-comments, no dead code.
40
+
41
+ ## 6. ORM / Database Rules
42
+
43
+ - One dedicated database per tool (`tera-internal-db` pattern). DSN via Env/Coolify secrets only — never in repo, never logged.
44
+ - **Pre-deploy DSN check is mandatory before every deploy:** the DSN must point exclusively at the tool's own DB (prevents writes to foreign DBs such as `bustan_db`). Violation = immediate stop.
45
+ - Destructive deletes use `ON DELETE RESTRICT` + soft-delete first; `audit_log` tables are append-only (no UPDATE/DELETE).
46
+ - Migrations + seed are code-reviewed; seed data comes only from approved preparation inventory (e.g. literal field keys).
47
+
48
+ ## 7. CLI Side Effects
49
+
50
+ | Command | Side effect | Rule |
51
+ |---|---|---|
52
+ | `npm install <pkg>` | modifies `package.json`/`package-lock.json` | allowed only inside task scope; no PDF libs in MVP unless task says so |
53
+ | `npx prisma migrate dev --name X` | creates migration + touches DB | local/tool DB only; never against foreign DSN |
54
+ | `npx prisma db seed` | writes rows | seed file must match approved inventory exactly |
55
+ | `git add/commit/push` | publishes | commit message concise; **push only after Majed approval**; no force-push, no amend |
56
+ | Coolify service create / domain attach / schedule | infra change | Majed permission at deploy time; recorded in task file |
57
+
58
+ ## 8. Forbidden Defaults
59
+
60
+ - No plaintext secrets/tokens/passwords/hashes-of-record in repo, logs, screenshots, or task files (`[REDACTED]` only; values live in Env/Coolify secrets).
61
+ - No storing raw single-use tokens — hash-only (SHA-256 + Env pepper).
62
+ - No public/unsigned links for private data; no new auth system when an ADR already decided auth (reuse of a session-less marketing site's auth is forbidden — see ADR-01 pattern).
63
+ - No invented field keys/labels — payload keys must equal the approved template ids literally.
64
+ - No API write path outside explicitly allowed columns (pattern: CR-001 — anything else → 422 + audit entry).
65
+ - No PDF generation library in MVP unless explicitly tasked.
66
+ - No `utils/`/`helpers/`/`common/` junk drawers; no file mixing UI + logic + data + auth.
67
+
68
+ ## 9. Pre-Execution Gate Additions
69
+
70
+ Extends `TeraPreExecutionGate.md` for this profile — all must PASS before any `TASK-COD-*` delegation:
71
+
72
+ 1. `PROFILE_APPROVED = PASS` (Majed approved this Draft).
73
+ 2. `GATE6_PROTO_APPROVED = PASS` (prototype approval letter filed) — unless WAIVED_BY_MAJED.
74
+ 3. `DSN_ISOLATION_PLAN = PASS` (task names the tool's own DB; pre-deploy check step included).
75
+ 4. `SECRETS_PLAN = PASS` (all secrets named as Env/Coolify-secret names with zero values).
76
+ 5. `SCOPE_LOCK = PASS` (task maps to locked scope items only; deferred/excluded items absent).
77
+ 6. `WRITE_TARGETS_ABSOLUTE = PASS` (absolute paths or explicit `ClientAppPath`-relative).
78
+
79
+ ## 10. Acceptance Criteria Patterns
80
+
81
+ - Token/access: single-use display of raw secret, hash-only storage, expiry enforced, revoke kills immediately, single-active invariant, rate-limit returns 429 + audit.
82
+ - Forms: literal field inventory match (order/labels/keys), autosave draft recoverable, submit requires only the approved mandatory fields, completion % = answered-active / active.
83
+ - Admin: unauthenticated `/admin/*` rejected, login rate-limited with temporary ban + audit, respondent isolation (no cross-record access).
84
+ - Data: zero writes to foreign DBs (verified), submitted records never purged, audit entries for every sensitive action.
85
+ - Export/print: valid JSON + clean RTL print (nav/buttons/filters hidden, no broken sections).
86
+ - Ops: old drafts purged per N, expired links read-only, domain serves HTTPS with redirect, `git diff --check` clean.
87
+
88
+ ## Decision Request
89
+
90
+ ```text
91
+ To Majed: approve this Draft as the Active Technology Profile for APP-DISCOVERY-SURVEY (yes / amend / reject).
92
+ On approval: TeraAgent locks ORM choice at TASK-COD-02 and proceeds under this profile.
93
+ ```
@@ -0,0 +1,164 @@
1
+ # Technology Profile: rust
2
+
3
+ > **Status: Draft — Needs Verification** (SCP-2026-09-04-011)
4
+ > مبني على بحث عميق 2026 من مصادر موثوقة (16 مصدراً: Corgea, Rust 2026 Template, onehorizon, Apollo skills, RuleSync, Agentbrisk, Axum/SQLx production guides...). **لم يُثبت بعد ببناء/اختبار فعلي محلي** (cargo غير مثبت على بيئة الإنشاء عند كتابة هذا البروفايل). ترقية الحالة إلى `Available` بعد تجربة تحقق (انظر §10).
5
+
6
+ ## 1. Profile Identity
7
+
8
+ - Profile ID: `rust`
9
+ - Language: Rust
10
+ - Framework: حسب المشروع — Axum (HTTP API) / Tauri (سطح مكتب + ويب) / actix-web (اختياري) / مكتبة أو CLI نقية
11
+ - Database: PostgreSQL (الأكثر شيوعاً مع SQLx) / SQLite / MySQL — حسب المشروع
12
+ - ORM: **SQLx** (يفضَّل — SQL مكتوب يدوياً + تحقق compile-time) / Diesel / SeaORM
13
+ - Package Manager / CLI: `cargo` + `rustup` (toolchain) — إصدار 2024 edition, MSRV 1.85+ (تحديث 2026)
14
+ - Default Project Type: CLI / خدمات عالية الأداء / أدوات نظامية / WebAssembly / Tauri (سطح مكتب) / Backend API
15
+
16
+ ## 2. Applicability
17
+
18
+ يُستخدم هذا البروفايل عندما:
19
+ - المشروع يتطلب أداءً عالياً أو موارد منخفضة (مقارنة بـ GC languages).
20
+ - تطبيق CLI أو أداة أو نظام أو خدمة شبكة عالية الأداء.
21
+ - سطح مكتب عبر Tauri (بديل أخف من Electron) أو WebAssembly.
22
+ - الزبون طلب Rust صراحة (المبدأ: لا لغة ممنوعة — fallback يعمل، والبروفايل يرفع الجودة).
23
+
24
+ **لا يُفضَّل** لمشاريع الويب التجارية سريعة الإنتاج (حيث TypeScript/.NET أسرع إنتاجية) — إلا بطلب صريح أو حاجة أداء مؤكدة.
25
+
26
+ ## 3. Default Execution Order
27
+
28
+ ```text
29
+ 1. cargo new --vcs git <name> (أو إعداد workspace لمشروع متعدد المكونات)
30
+ 2. تثبيت/تأكيد toolchain: rustup + cargo + rustfmt + clippy (cargo --version)
31
+ 3. First Task: أثبت toolchain — hello-world + cargo build + cargo test
32
+ 4. بنية النطاق: types/domain أولاً (تشفير الحالات غير الصالحة في الأنواع)
33
+ 5. منطق الأعمال: functions/structs + Result-errors (thiserror في lib / anyhow في bin)
34
+ 6. طبقة البيانات (إن وجدت): SQLx + migrations (compile-time-checked queries)
35
+ 7. واجهة (إن وجدت): Axum (backend) / Tauri (desktop) — DTO منفصلة عن domain
36
+ 8. اختبارات: unit (#[cfg(test)]) + integration (tests/) + nextest + proptest
37
+ 9. التحقق النهائي: cargo fmt --check + cargo clippy -D warnings + cargo test + cargo audit
38
+ ```
39
+
40
+ ## 4. First Task Rule
41
+
42
+ أول مهمة تنفيذية لأي مشروع Rust: **إثبات الـ toolchain قبل أي كود منطقي**:
43
+
44
+ ```text
45
+ 1. cargo --version && rustc --version && rustup show
46
+ 2. cargo new <name> --vcs git
47
+ 3. تعديل main.rs (hello) → cargo build → cargo run
48
+ 4. cargo test (يتأكد أن بنية الاختبارات تعمل)
49
+ 5. cargo clippy -- -D warnings (يتأكد أن clippy يعمل وصافي)
50
+ 6. cargo fmt --check
51
+ ```
52
+
53
+ إذا فشلت أي خطوة: STOP — لا تبنِ فوق toolchain غير مثبت. وثّق الإصدارات في الـ handback.
54
+
55
+ ## 5. Scaffold Rules
56
+
57
+ - `cargo new <name> --vcs git` — يبدأ ببيئة git (لا تحذفها إلا بتوجيه).
58
+ - للمشاريع متعددة المكونات: **workspace** (`[workspace] members`) — لكن **Module-First**: لا تقسّم crates إلا لحاجة حقيقية (proc-macro، حدود صارمة، توازي بناء) — 2026 consensus.
59
+ - حدد `rust-version` (MSRV) في Cargo.toml — cargo يرفض بناءً بـ toolchain أقدم.
60
+ - `Cargo.lock`: **يُلتَزم في git** (للتكرار القابل للبناء حتى في المكتبات).
61
+ - التبعيات: **بلا wildcards** (`tokio = "*"` ممنوع) — ثبّت major+minor (`tokio = "1.38"`). حدد features المستخدمة فقط.
62
+ - `[lints]` في Cargo.toml (مستقر منذ Rust 1.74): سياسة lint موحدة للجميع — انظر §9.
63
+
64
+ ## 6. ORM / Database Rules
65
+
66
+ ### SQLx (المفضَّل):
67
+ - `query!` / `query_as!` — تحقق compile-time ضد قاعدة حقيقية (يتطلب DATABASE_URL عند البناء).
68
+ - **Offline mode**: `cargo sqlx prepare` + `SQLX_OFFLINE=true` في CI/Docker + التزام `.sqlx/`.
69
+ - Migrations: `sqlx migrate add <name>` + `sqlx::migrate!()` (تشغيل تلقائي عند البدء) أو sqlx-cli.
70
+ - **Parameterized queries إلزامي** — ممنوع string interpolation في SQL (SQL injection — OWASP).
71
+ - `PgPool`: max_connections محدود (أقل من max Postgres ÷ عدد النسخ) + `acquire_timeout` + `idle_timeout` — لا إعدادات افتراضية.
72
+ - Diesel/SeaORM: عند الحاجة — migrations عبر أدواتها الخاصة (`diesel_cli` / `sea-orm-cli`).
73
+
74
+ ## 7. CLI Side Effects
75
+
76
+ | الأمر | الأثر |
77
+ |---|---|
78
+ | `cargo add <crate>` | يضيف تبعية — وثّق السبب؛ لا تبعية بلا حاجة |
79
+ | `cargo build` / `cargo run` | يبني/يشغّل — بدون أثر دائم (ما لم يشغّل كوداً بآثار) |
80
+ | `cargo test` | يشغّل الاختبارات |
81
+ | `cargo clippy` / `cargo fmt` | تحليل/تنسيق — بلا أثر على الإنتاج |
82
+ | `cargo sqlx prepare` | يكتب `.sqlx/` metadata — **يُلتَزم** |
83
+ | `sqlx migrate run` | **يغيّر قاعدة البيانات** — يتطلب موافقة صريحة (مثل أي migration) |
84
+ | `cargo audit` / `cargo deny` | فحص تبعيات — تشغيل قبل التسليم |
85
+
86
+ **القاعدة:** أي أمر يغيّر قاعدة بيانات أو يثبّت شيئاً في النظام = بوابة موافقة (مثل سياسة migrations في المنظومة).
87
+
88
+ ## 8. Forbidden Defaults
89
+
90
+ ```text
91
+ ❌ unsafe — خارج "المكتبات/FFI ذات الحاجة المؤكدة فقط" — والافتراضي #![forbid(unsafe_code)]
92
+ ❌ .unwrap() / .expect() في كود الإنتاج (مسموح في الاختبارات فقط) — لint unwrap_used/expect_used
93
+ ❌ panic! في مسارات الإدخال الخارجي (DoS) — Result و ? بدلها
94
+ ❌ &String / &Vec<T> في التواقيع — &str / &[T] (أرخص اقتراض عند الحدود)
95
+ ❌ .clone() "لإسكات الـ borrow checker" — أعد تصميم الملكية أولاً؛ لا clone في الحلقات
96
+ ❌ Box<dyn Error> في API عام للمكتبات — thiserror enum بدلها (2026: لا مزايا)
97
+ ❌ std::sync::Mutex عبر .await — deadlock في tokio؛ استخدم tokio::sync::Mutex أو أسقط القفل قبل await
98
+ ❌ استدعاء I/O حاجب (blocking) داخل async fn — tokio::fs/net/reqwest أو spawn_blocking
99
+ ❌ tokio = "*" أو أي wildcard تبعية
100
+ ❌ Rc<RefCell<T>> كحل سهل للملكية — أعد التصميم
101
+ ❌ Cargo.toml بلا rust-version / بلا [lints]
102
+ ❌ كود "C-style Rust" — تجنب 400-line match وأقواس مفرطة؛ استخدم idioms حقيقية (enums للأنواع غير الصالحة)
103
+ ```
104
+
105
+ ## 9. Pre-Execution Gate Additions
106
+
107
+ إضافات بروفايل Rust على `TeraPreExecutionGate.md`:
108
+
109
+ | # | الفحص |
110
+ |---|---|
111
+ | 1 | `cargo --version` متوفر؟ (toolchain مثبت — إن لا: STOP، ثبّت أولاً) |
112
+ | 2 | إصدار 2024 edition + `rust-version` محدد في Cargo.toml؟ |
113
+ | 3 | التبعيات بلا wildcards + features محدودة؟ |
114
+ | 4 | `Cargo.lock` مُلتَزم (إن مشروع binary/service)؟ |
115
+ | 5 | سياسة `[lints]` حاضرة؟ |
116
+ | 6 | لـ SQLx: DATABASE_URL / offline metadata (`SQLX_OFFLINE` + `.sqlx/`)؟ |
117
+ | 7 | أي unsafe مخطط له — مبرر وضمن crate منفصل بحدود؟ |
118
+ | 8 | المهمة تلمس بيانات حساسة/صلاحيات/دفع → Security Review (الدرع) قبل التنفيذ |
119
+
120
+ **مرجع lint الموصى به** ([lints] في Cargo.toml — مصدر: Corgea 2026 + Apollo + Rust 2026 Template):
121
+
122
+ ```toml
123
+ [lints.rust]
124
+ unsafe_code = "forbid" # تُزال في crates التي تحتاج unsafe فعلاً
125
+ missing_docs = "warn"
126
+
127
+ [lints.clippy]
128
+ unwrap_used = "warn"
129
+ expect_used = "warn"
130
+ undocumented_unsafe_blocks = "deny"
131
+ cast_possible_truncation = "warn"
132
+ await_holding_lock = "warn"
133
+ redundant_clone = "warn"
134
+ needless_collect = "warn"
135
+ large_enum_variant = "warn"
136
+ ```
137
+
138
+ في workspace: `[workspace.lints]` مرة واحدة + `lints.workspace = true` لكل crate.
139
+
140
+ ## 10. Acceptance Criteria Patterns
141
+
142
+ ```text
143
+ ✅ cargo build --release → PASS
144
+ ✅ cargo test → PASS (unit + integration)
145
+ ✅ cargo clippy --workspace --all-targets -- -D warnings → صفر warnings
146
+ ✅ cargo fmt --check → PASS (لا انحراف)
147
+ ✅ cargo audit (لا CRITICAL/HIGH بلا إصلاح أو خطة) — GITLEAKS للأسرار
148
+ ✅ معايير الخطأ: thiserror في lib (أنواع قابلة للمطابقة) / anyhow + .context() في bin — بلا unwrap خارج الاختبارات
149
+ ✅ لـ async: بلا I/O حاجب في async fn + بلا قفل عبر await (clippy يتحقق)
150
+ ✅ لـ SQL: parameterized فقط + migrations قابلة للتراجع
151
+ ✅ لـ UI (Tauri/Web): Playwright/axe وفق قواعد المنظومة
152
+ ```
153
+
154
+ ### مسار الترقية إلى Available (خطوة التحقق المتبقية — بيئة تنفيذ بها cargo)
155
+
156
+ ```text
157
+ 1. cargo new verify-rust-cli → build + test + clippy -D warnings + fmt --check → PASS
158
+ 2. (اختياري) مشروع Axum+SQLx صغير → build + migrate + test → PASS
159
+ 3. عند النجاح: رفع حالة هذا البروفايل من "Draft" → "Available" في §1 + PROFILES_INDEX + TeraCapabilityMap
160
+ ```
161
+
162
+ ---
163
+
164
+ *أُنشئ: TeraSystemEvolutionAgent (حارس) — 2026-09-04 · SCP-2026-09-04-011 · بحث 2026 من 16 مصدراً موثوقاً — Draft حتى تجربة تحقق.*
@@ -1,6 +1,6 @@
1
1
  # Tera Runtime Protocols — Knowledge Management
2
2
 
3
- This file now contains **Section 19** (Project Knowledge Management Protocol) after the INS-02 continuation split (2026-08-01).
3
+ This file now contains **Section 19 ONLY** (Project Knowledge Management Protocol) after the INS-02 continuation split (2026-08-01). It is NOT the protocols master — for Sections 1–11 see `TERA_RUNTIME_PROTOCOLS_CORE.md`, for 12–18 see `TERA_RUNTIME_PROTOCOLS_CLIENT.md` (SCP-2026-09-16-003).
4
4
 
5
5
  ## Split Notice
6
6
 
@@ -43,6 +43,7 @@ Reference Files:
43
43
  Required Sections:
44
44
  Allowed Write Targets:
45
45
  Forbidden Files / Actions:
46
+ Tool Escalation: إن احتجت أداة خارج صلاحياتك → توقف واطلبها مني (لا تُكمل بأدلة ناقصة صامتة، ولا ترحّل الفجوة للمالك) — GAP-013
46
47
  Token Budget: Low / Medium / High / Critical
47
48
  Model Tier Recommendation: Light / Medium / Strong
48
49
  Minimum Acceptable Model Tier: Light / Medium / Strong
@@ -886,15 +887,15 @@ See `TERA_RUNTIME_PROTOCOLS_CLIENT.md` Section 18, Client Discovery Step 7 for t
886
887
 
887
888
  ## 27. Project Preparation Plan (Phase 3 Output)
888
889
 
889
- > ?? **������� ��� ������ (SCP-2026-07-28-118).** ������ ������ ���� ��:
890
- > `tera-system/runtime/TERA_SOLUTION_PREPARATION_TEMPLATES.md` �2 � Preparation Plan Template
890
+ > ⚠️ **مصدر التغيير (SCP-2026-07-28-118).** هذا القالب انتقل إلى:
891
+ > `tera-system/runtime/TERA_SOLUTION_PREPARATION_TEMPLATES.md` §2 — Preparation Plan Template
891
892
 
892
893
  ---
893
894
 
894
895
  ## 28. Agent Delegation Plan (Phase 4 Output)
895
896
 
896
- > ?? **������� ��� ������ (SCP-2026-07-28-118).** ������ ������ ���� ��:
897
- > `tera-system/runtime/TERA_SOLUTION_PREPARATION_TEMPLATES.md` �3 � Agent Delegation Plan Template
897
+ > ⚠️ **مصدر التغيير (SCP-2026-07-28-118).** هذا القالب انتقل إلى:
898
+ > `tera-system/runtime/TERA_SOLUTION_PREPARATION_TEMPLATES.md` §3 — Agent Delegation Plan Template
898
899
 
899
900
  ---
900
901