@tera-system/core 0.2.18 → 0.2.20

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,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 حتى تجربة تحقق.*
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tera-system/core",
3
- "version": "0.2.18",
3
+ "version": "0.2.20",
4
4
  "description": "Tera System OpenCode Plugin ط£آ¢أ¢â€ڑآ¬أ¢â‚¬â€Œ governance core, 20 agents, 11 commands, distribution tools (personal edition)",
5
5
  "license": "SEE LICENSE IN LICENSE.md",
6
6
  "type": "module",
@@ -226,21 +226,26 @@ fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
226
226
  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
227
227
 
228
228
  /* ------------------- license state (non-blocking, never breaks install) ------------------- */
229
- try {
230
- const stateFile = path.join(target, ".tera", "license.state.json");
231
- let licenseKey = (readLicenseState(stateFile) || {}).licenseKey;
232
- if (!licenseKey) licenseKey = process.env.TERA_LICENSE_KEY || undefined;
233
- const state = assessLicenseState(licenseKey);
234
- writeLicenseState(stateFile, {
235
- state: state.state,
236
- reason: state.reason,
237
- licenseKey: licenseKey || null,
238
- expiresAt: state.expiresAt || null,
239
- checkedAt: new Date().toISOString(),
240
- });
241
- console.log(` [license ] state=${state.state} (${state.reason})`);
242
- } catch (err) {
243
- console.log(` [license ] skipped (${err.message}) — install continues`);
229
+ // `@tera-system/core` is free — it has no license gate. Skip the whole block for it so no
230
+ // `[license]` line is printed and no `.tera/license.state.json` is ever created.
231
+ // The paid `@tera-system/pro` distribution keeps its own license flow via its install.js.
232
+ if (pkg.name !== "@tera-system/core") {
233
+ try {
234
+ const stateFile = path.join(target, ".tera", "license.state.json");
235
+ let licenseKey = (readLicenseState(stateFile) || {}).licenseKey;
236
+ if (!licenseKey) licenseKey = process.env.TERA_LICENSE_KEY || undefined;
237
+ const state = assessLicenseState(licenseKey);
238
+ writeLicenseState(stateFile, {
239
+ state: state.state,
240
+ reason: state.reason,
241
+ licenseKey: licenseKey || null,
242
+ expiresAt: state.expiresAt || null,
243
+ checkedAt: new Date().toISOString(),
244
+ });
245
+ console.log(` [license ] state=${state.state} (${state.reason})`);
246
+ } catch (err) {
247
+ console.log(` [license ] skipped (${err.message}) — install continues`);
248
+ }
244
249
  }
245
250
 
246
251
  console.log("\n summary:");
@@ -1,63 +0,0 @@
1
- #!/usr/bin/env node
2
- // @tera/core license CLI — issue & verify license keys (SCP-005)
3
- import fs from "node:fs";
4
- import path from "node:path";
5
- import { fileURLToPath } from "node:url";
6
- import { issueLicenseKey, assessLicenseState, readLicenseState, STATES } from "./lib/license.mjs";
7
-
8
- const __dirname = path.dirname(fileURLToPath(import.meta.url));
9
- const DEV_KEY = path.join(__dirname, "..", "license", "dev", "dev-private-key.pem");
10
-
11
- function usage() {
12
- console.log(`Usage:
13
- tera-license gen --tier <basic|premium> --project <name> --expires <YYYY-MM-DD> [--seats N]
14
- (private key: env TERA_LICENSE_PRIVATE or the dev key under license/dev/)
15
- tera-license check [--key <licenseKey> | --state-file <path>]
16
- (or env TERA_LICENSE_KEY)`);
17
- }
18
-
19
- const args = process.argv.slice(2);
20
- const cmd = args[0];
21
- function flag(name) {
22
- const i = args.indexOf(name);
23
- return i >= 0 && args[i + 1] ? args[i + 1] : undefined;
24
- }
25
-
26
- if (cmd === "gen") {
27
- const tier = flag("--tier") || "basic";
28
- const project = flag("--project");
29
- const expires = flag("--expires");
30
- const seats = flag("--seats") ? Number(flag("--seats")) : 1;
31
- if (!project || !expires) {
32
- usage();
33
- process.exit(1);
34
- }
35
- const privatePem = process.env.TERA_LICENSE_PRIVATE || fs.readFileSync(DEV_KEY, "utf8");
36
- const key = issueLicenseKey(
37
- { tier, project, issuedAt: new Date().toISOString(), expiresAt: new Date(expires).toISOString(), seats },
38
- privatePem
39
- );
40
- console.log(key);
41
- } else if (cmd === "check") {
42
- let key = flag("--key");
43
- if (!key) {
44
- const stateFile = flag("--state-file");
45
- if (stateFile) {
46
- const st = readLicenseState(stateFile);
47
- key = st && st.licenseKey;
48
- if (!key) {
49
- console.log(JSON.stringify({ state: STATES.UNLICENSED, reason: "no-key-trial" }, null, 2));
50
- process.exit(0);
51
- }
52
- } else {
53
- key = process.env.TERA_LICENSE_KEY;
54
- }
55
- }
56
- if (!key) {
57
- console.log(JSON.stringify({ state: STATES.UNLICENSED, reason: "no-key-trial" }, null, 2));
58
- process.exit(0);
59
- }
60
- console.log(JSON.stringify(assessLicenseState(key), null, 2));
61
- } else {
62
- usage();
63
- }