@tera-system/core 0.2.20 → 0.3.1
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 +5 -5
- package/RELEASES.md +14 -0
- package/agents/auditor.md +17 -0
- package/agents/design-reviewer.md +12 -3
- package/agents/tera.md +48 -76
- package/agents/ui-designer.md +31 -0
- package/core/tera-system/AGENT_ACTIVATION_MATRIX.md +2 -0
- package/core/tera-system/AGENT_DEPENDENCY_MAP.md +4 -4
- package/core/tera-system/TOOLING_AND_MCP_POLICY.md +81 -1
- package/core/tera-system/TeraArchitectureMap.md +3 -0
- package/core/tera-system/TeraCapabilityMap.md +1 -1
- package/core/tera-system/TeraPolicyMap.md +3 -1
- package/core/tera-system/image-generation/ASSET_POLICY.md +149 -0
- package/core/tera-system/image-generation/IMAGE_TOOL_CONTRACT.md +341 -0
- package/core/tera-system/profiles/PROFILES_INDEX.md +1 -0
- package/core/tera-system/profiles/bun-ts-monorepo-sqlite.md +164 -0
- package/core/tera-system/profiles/node-ts-coolify-postgres.md +93 -0
- package/core/tera-system/runtime/TERA_RUNTIME_PROTOCOLS.md +1 -1
- package/core/tera-system/runtime/TERA_RUNTIME_TEMPLATES.md +5 -4
- package/core/tera-system/runtime/TERA_RUNTIME_TEMPLATES_DELIVERY.md +59 -0
- package/core/tera-system/semgrep-rules/tera-security.yml +119 -10
- package/package.json +2 -2
- package/core/tera-system/knowledge-base/OPENHANDS_ARCHITECTURE_REFERENCE.md +0 -243
|
@@ -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
|
+
```
|
|
@@ -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
|
-
>
|
|
890
|
-
> `tera-system/runtime/TERA_SOLUTION_PREPARATION_TEMPLATES.md`
|
|
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
|
-
>
|
|
897
|
-
> `tera-system/runtime/TERA_SOLUTION_PREPARATION_TEMPLATES.md`
|
|
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
|
|
|
@@ -154,6 +154,8 @@ The generated file is saved to `project-control/EXECUTION_BATCH_PLAN.md`.
|
|
|
154
154
|
| TASK-COD-002 | [e.g. Init ORM + DB] | EngineeringAgent | `prisma/schema.prisma`, `.env.example` | PASS |
|
|
155
155
|
| ... | ... | ... | ... | ... |
|
|
156
156
|
|
|
157
|
+
> **قاعدة قياسية لكل مهمة (GAP-013):** إن احتاج الوكيل أداة خارج صلاحياته → توقف + اطلبها من Tera — لا يُكمل بأدلة ناقصة صامتة، ولا يرحّل الفجوة للمالك. (راجع `TERA_RUNTIME_TEMPLATES.md` §2 — Tool Escalation)
|
|
158
|
+
|
|
157
159
|
## 3. Not Included (Deferred to Later Batches)
|
|
158
160
|
|
|
159
161
|
| Item | Reason | Expected Batch |
|
|
@@ -585,3 +587,60 @@ clients/CLIENT-[client-name-or-id]/applications/APP-[app-name-or-id]/delivery/CL
|
|
|
585
587
|
- سجّل نتيجة الاختبار (تاريخ، نجاح/فشل) في وثائق التسليم.
|
|
586
588
|
|
|
587
589
|
---
|
|
590
|
+
|
|
591
|
+
## 39. TERA Audit Trail Entry Template (moved from tera.md §26 — SCP-2026-09-16-004)
|
|
592
|
+
|
|
593
|
+
Operational core stays in `tera.md` §26 (file, sole owner, when in brief, minimum fields, closure gate). This section holds the full record-once reference: event list + entry structure + evidence guidance.
|
|
594
|
+
|
|
595
|
+
### 39.1 When to Record (substantive events only)
|
|
596
|
+
|
|
597
|
+
Record an entry only at these events:
|
|
598
|
+
1. Phase start
|
|
599
|
+
2. Phase end
|
|
600
|
+
3. Gate PASS / FAIL
|
|
601
|
+
4. Execution Plan / Batch Plan created or approved
|
|
602
|
+
5. `TASK-COD-*` created
|
|
603
|
+
6. Task delegated to an agent
|
|
604
|
+
7. Handback received from an agent
|
|
605
|
+
8. Handback rejected / rework requested
|
|
606
|
+
9. QA / Auditor / Reviewer invoked
|
|
607
|
+
10. QA / Audit / Review result that affects a decision
|
|
608
|
+
11. Owner decision or clarification that affects execution
|
|
609
|
+
12. Open Item status change
|
|
610
|
+
13. Scope Change Request
|
|
611
|
+
14. Governance violation discovered
|
|
612
|
+
15. Dependency or batch-order change
|
|
613
|
+
16. TASK closed
|
|
614
|
+
17. Batch accepted or rejected
|
|
615
|
+
18. Phase 5 → 6 transition
|
|
616
|
+
19. Phase 6 → 7 transition
|
|
617
|
+
20. Final delivery / closure
|
|
618
|
+
|
|
619
|
+
Do **NOT** record: every file read, grep, shell command, internal message, minor failed attempt, small bug fix, or line edit. Record only events with value for governance, delegation, decision-making, quality, traceability, phase control, scope control, or accountability.
|
|
620
|
+
|
|
621
|
+
### 39.2 Entry Structure
|
|
622
|
+
|
|
623
|
+
Fields (not all mandatory for every event):
|
|
624
|
+
- Audit ID (`AUD-0001`, `AUD-0002`, … — sequential, zero-padded, one format only)
|
|
625
|
+
- Timestamp
|
|
626
|
+
- Phase
|
|
627
|
+
- Event Type
|
|
628
|
+
- Actor
|
|
629
|
+
- Target
|
|
630
|
+
- Related Task / Batch
|
|
631
|
+
- Source of Truth
|
|
632
|
+
- Action Taken
|
|
633
|
+
- Decision
|
|
634
|
+
- Reason
|
|
635
|
+
- Evidence
|
|
636
|
+
- Gate Result
|
|
637
|
+
- Owner Approval Required
|
|
638
|
+
- Owner Approval Status
|
|
639
|
+
- Next Step
|
|
640
|
+
|
|
641
|
+
**Mandatory minimum per entry:** Audit ID, Timestamp, Phase, Event Type, Actor, Action Taken, Evidence (or Reference), Next Step. Never write an entry without these.
|
|
642
|
+
|
|
643
|
+
### 39.3 Evidence
|
|
644
|
+
|
|
645
|
+
Point to real evidence wherever possible — never just "done successfully":
|
|
646
|
+
- file path, `TASK-ID`, `Batch-ID`, commit SHA, QA report, handback file, decision-log entry, gate-result file.
|
|
@@ -1,13 +1,52 @@
|
|
|
1
1
|
rules:
|
|
2
|
-
- id: tera-no-hardcoded-secrets
|
|
2
|
+
- id: tera-no-hardcoded-secrets-csharp
|
|
3
3
|
message: >
|
|
4
4
|
SECURITY [QG-SEC-001]: لا تخزن مفاتيح أو ConnectionStrings أو Secrets في الكود.
|
|
5
5
|
استخدم User Secrets / Environment Variables / Azure Key Vault / أي آلية آمنة معتمدة.
|
|
6
6
|
severity: ERROR
|
|
7
7
|
languages:
|
|
8
8
|
- csharp
|
|
9
|
+
patterns:
|
|
10
|
+
- pattern: |
|
|
11
|
+
$VAR = "..."
|
|
12
|
+
- metavariable-regex:
|
|
13
|
+
metavariable: $VAR
|
|
14
|
+
regex: (?i).*(password|secret|connection.?string|api.?key|apikey|passwd|pwd|credential).*
|
|
15
|
+
|
|
16
|
+
- id: tera-no-hardcoded-secrets-javascript
|
|
17
|
+
message: >
|
|
18
|
+
SECURITY [QG-SEC-001]: لا تخزن مفاتيح أو ConnectionStrings أو Secrets في الكود.
|
|
19
|
+
استخدم User Secrets / Environment Variables / Azure Key Vault / أي آلية آمنة معتمدة.
|
|
20
|
+
severity: ERROR
|
|
21
|
+
languages:
|
|
9
22
|
- javascript
|
|
23
|
+
patterns:
|
|
24
|
+
- pattern: |
|
|
25
|
+
$VAR = "..."
|
|
26
|
+
- metavariable-regex:
|
|
27
|
+
metavariable: $VAR
|
|
28
|
+
regex: (?i).*(password|secret|connection.?string|api.?key|apikey|passwd|pwd|credential).*
|
|
29
|
+
|
|
30
|
+
- id: tera-no-hardcoded-secrets-typescript
|
|
31
|
+
message: >
|
|
32
|
+
SECURITY [QG-SEC-001]: لا تخزن مفاتيح أو ConnectionStrings أو Secrets في الكود.
|
|
33
|
+
استخدم User Secrets / Environment Variables / Azure Key Vault / أي آلية آمنة معتمدة.
|
|
34
|
+
severity: ERROR
|
|
35
|
+
languages:
|
|
10
36
|
- typescript
|
|
37
|
+
patterns:
|
|
38
|
+
- pattern: |
|
|
39
|
+
$VAR = "..."
|
|
40
|
+
- metavariable-regex:
|
|
41
|
+
metavariable: $VAR
|
|
42
|
+
regex: (?i).*(password|secret|connection.?string|api.?key|apikey|passwd|pwd|credential).*
|
|
43
|
+
|
|
44
|
+
- id: tera-no-hardcoded-secrets-python
|
|
45
|
+
message: >
|
|
46
|
+
SECURITY [QG-SEC-001]: لا تخزن مفاتيح أو ConnectionStrings أو Secrets في الكود.
|
|
47
|
+
استخدم User Secrets / Environment Variables / Azure Key Vault / أي آلية آمنة معتمدة.
|
|
48
|
+
severity: ERROR
|
|
49
|
+
languages:
|
|
11
50
|
- python
|
|
12
51
|
patterns:
|
|
13
52
|
- pattern: |
|
|
@@ -16,6 +55,23 @@ rules:
|
|
|
16
55
|
metavariable: $VAR
|
|
17
56
|
regex: (?i).*(password|secret|connection.?string|api.?key|apikey|passwd|pwd|credential).*
|
|
18
57
|
|
|
58
|
+
- id: tera-no-hardcoded-secrets-kotlin
|
|
59
|
+
message: >
|
|
60
|
+
SECURITY [QG-SEC-001]: لا تخزن مفاتيح أو ConnectionStrings أو Secrets في الكود.
|
|
61
|
+
استخدم User Secrets / Environment Variables / Azure Key Vault / أي آلية آمنة معتمدة.
|
|
62
|
+
severity: ERROR
|
|
63
|
+
languages:
|
|
64
|
+
- kotlin
|
|
65
|
+
patterns:
|
|
66
|
+
- pattern-either:
|
|
67
|
+
- pattern: |
|
|
68
|
+
val $VAR = "..."
|
|
69
|
+
- pattern: |
|
|
70
|
+
var $VAR = "..."
|
|
71
|
+
- metavariable-regex:
|
|
72
|
+
metavariable: $VAR
|
|
73
|
+
regex: (?i).*(password|secret|connection.?string|api.?key|apikey|passwd|pwd|credential).*
|
|
74
|
+
|
|
19
75
|
- id: tera-no-eval
|
|
20
76
|
pattern: eval(...)
|
|
21
77
|
message: >
|
|
@@ -44,23 +100,76 @@ rules:
|
|
|
44
100
|
metavariable: $VAR
|
|
45
101
|
regex: (?i).*
|
|
46
102
|
|
|
47
|
-
- id: tera-exposed-credentials
|
|
103
|
+
- id: tera-exposed-credentials-csharp
|
|
48
104
|
message: >
|
|
49
105
|
SECURITY [QG-SEC-001]: لا تخزن مفاتيح أو توكنز أو API Keys بشكل صريح في الكود.
|
|
50
106
|
severity: ERROR
|
|
51
107
|
languages:
|
|
52
108
|
- csharp
|
|
109
|
+
patterns:
|
|
110
|
+
- pattern: $VAR = $VAL
|
|
111
|
+
- metavariable-regex:
|
|
112
|
+
metavariable: $VAL
|
|
113
|
+
regex: ^"(sk-|ghp_|AKIA|=).*"
|
|
114
|
+
|
|
115
|
+
- id: tera-exposed-credentials-javascript
|
|
116
|
+
message: >
|
|
117
|
+
SECURITY [QG-SEC-001]: لا تخزن مفاتيح أو توكنز أو API Keys بشكل صريح في الكود.
|
|
118
|
+
severity: ERROR
|
|
119
|
+
languages:
|
|
53
120
|
- javascript
|
|
121
|
+
patterns:
|
|
122
|
+
- pattern: $VAR = $VAL
|
|
123
|
+
- metavariable-regex:
|
|
124
|
+
metavariable: $VAL
|
|
125
|
+
regex: ^"(sk-|ghp_|AKIA|=).*"
|
|
126
|
+
|
|
127
|
+
- id: tera-exposed-credentials-typescript
|
|
128
|
+
message: >
|
|
129
|
+
SECURITY [QG-SEC-001]: لا تخزن مفاتيح أو توكنز أو API Keys بشكل صريح في الكود.
|
|
130
|
+
severity: ERROR
|
|
131
|
+
languages:
|
|
54
132
|
- typescript
|
|
133
|
+
patterns:
|
|
134
|
+
- pattern: $VAR = $VAL
|
|
135
|
+
- metavariable-regex:
|
|
136
|
+
metavariable: $VAL
|
|
137
|
+
regex: ^"(sk-|ghp_|AKIA|=).*"
|
|
138
|
+
|
|
139
|
+
- id: tera-exposed-credentials-python
|
|
140
|
+
message: >
|
|
141
|
+
SECURITY [QG-SEC-001]: لا تخزن مفاتيح أو توكنز أو API Keys بشكل صريح في الكود.
|
|
142
|
+
severity: ERROR
|
|
143
|
+
languages:
|
|
55
144
|
- python
|
|
145
|
+
patterns:
|
|
146
|
+
- pattern: $VAR = $VAL
|
|
147
|
+
- metavariable-regex:
|
|
148
|
+
metavariable: $VAL
|
|
149
|
+
regex: ^"(sk-|ghp_|AKIA|=).*"
|
|
150
|
+
|
|
151
|
+
- id: tera-exposed-credentials-java
|
|
152
|
+
message: >
|
|
153
|
+
SECURITY [QG-SEC-001]: لا تخزن مفاتيح أو توكنز أو API Keys بشكل صريح في الكود.
|
|
154
|
+
severity: ERROR
|
|
155
|
+
languages:
|
|
56
156
|
- java
|
|
157
|
+
patterns:
|
|
158
|
+
- pattern: $VAR = $VAL
|
|
159
|
+
- metavariable-regex:
|
|
160
|
+
metavariable: $VAL
|
|
161
|
+
regex: ^"(sk-|ghp_|AKIA|=).*"
|
|
162
|
+
|
|
163
|
+
- id: tera-exposed-credentials-kotlin
|
|
164
|
+
message: >
|
|
165
|
+
SECURITY [QG-SEC-001]: لا تخزن مفاتيح أو توكنز أو API Keys بشكل صريح في الكود.
|
|
166
|
+
severity: ERROR
|
|
167
|
+
languages:
|
|
168
|
+
- kotlin
|
|
57
169
|
patterns:
|
|
58
170
|
- pattern-either:
|
|
59
|
-
- pattern:
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
$VAR = "ghp_..."
|
|
65
|
-
- pattern: |
|
|
66
|
-
$VAR = "AKIA..."
|
|
171
|
+
- pattern: val $VAR = $VAL
|
|
172
|
+
- pattern: var $VAR = $VAL
|
|
173
|
+
- metavariable-regex:
|
|
174
|
+
metavariable: $VAL
|
|
175
|
+
regex: ^"(sk-|ghp_|AKIA|=).*"
|
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
|
|
3
|
+
"version": "0.3.1",
|
|
4
|
+
"description": "Tera System OpenCode Plugin — governance core, 23 agents, 11 commands, distribution tools (personal edition)",
|
|
5
5
|
"license": "SEE LICENSE IN LICENSE.md",
|
|
6
6
|
"type": "module",
|
|
7
7
|
"engines": {
|
|
@@ -1,243 +0,0 @@
|
|
|
1
|
-
# OpenHands — مرجع معماري للدراسة المستقبلية
|
|
2
|
-
|
|
3
|
-
> **أنشئ:** 2026-07-26
|
|
4
|
-
> **المصدر:** https://github.com/OpenHands/OpenHands (82.2k★)
|
|
5
|
-
> **الغرض:** ملف مرجعي لدراسة OpenHands لاحقاً وتطبيق مفاهيمه على Tera
|
|
6
|
-
> **حالة الدراسة:** ⏳ لم تبدأ بعد — أنشئ للرجوع إليه
|
|
7
|
-
|
|
8
|
-
---
|
|
9
|
-
|
|
10
|
-
## 1. ما هو OpenHands؟
|
|
11
|
-
|
|
12
|
-
منصة **مفتوحة المصدر** لتشغيل وإدارة العملاء البرمجيين (Coding Agents) على نطاق واسع.
|
|
13
|
-
ليست مجرد IDE أو CLI — بل **نظام تشغيل كامل للعملاء**.
|
|
14
|
-
|
|
15
|
-
### الإحصائيات
|
|
16
|
-
- ⭐ 82.2k★
|
|
17
|
-
- 🍴 10.5k Fork
|
|
18
|
-
- 📝 7,082 Commit
|
|
19
|
-
- 📜 Apache 2.0 License
|
|
20
|
-
|
|
21
|
-
---
|
|
22
|
-
|
|
23
|
-
## 2. المكونات المعمارية الأساسية
|
|
24
|
-
|
|
25
|
-
```
|
|
26
|
-
┌────────────────────────────────────────────────────────────┐
|
|
27
|
-
│ OpenHands System │
|
|
28
|
-
├────────────────────────────────────────────────────────────┤
|
|
29
|
-
│ │
|
|
30
|
-
│ ┌───────────────────────┐ │
|
|
31
|
-
│ │ Agent Canvas │ ← واجهة تحكم Frontend (UI) │
|
|
32
|
-
│ │ @openhands/agent- │ تبوك: localhost:8000 │
|
|
33
|
-
│ │ canvas │ تشغيل محلي أو سحابي │
|
|
34
|
-
│ └──────────┬────────────┘ │
|
|
35
|
-
│ │ HTTP/REST │
|
|
36
|
-
│ ┌──────────▼────────────┐ │
|
|
37
|
-
│ │ Agent Server │ ← REST API لتشغيل العملاء │
|
|
38
|
-
│ │ (software-agent-sdk) │ • يشغّل عدة عملاء على Server │
|
|
39
|
-
│ │ │ • يمكن تشغيل Servers متعددة │
|
|
40
|
-
│ └──────────┬────────────┘ • Local / Docker / VM / Cloud│
|
|
41
|
-
│ │ │
|
|
42
|
-
│ ┌──────────▼────────────┐ │
|
|
43
|
-
│ │ Automation Server │ ← تشغيل مجدول + أحداث │
|
|
44
|
-
│ │ (github.com/ │ • Cron jobs │
|
|
45
|
-
│ │ OpenHands/ │ • Webhooks (GitHub, Linear) │
|
|
46
|
-
│ │ automation) │ • تكامل Slack, Discord │
|
|
47
|
-
│ └────────────────────────┘ │
|
|
48
|
-
│ │
|
|
49
|
-
│ ┌────────────────────────┐ │
|
|
50
|
-
│ │ ACP (Agent-Client │ ← بروتوكول تواصل موحّد │
|
|
51
|
-
│ │ Protocol) │ • أي عميل (Claude, Codex, │
|
|
52
|
-
│ │ │ Gemini, OpenHands) │
|
|
53
|
-
│ │ │ • يتواصل مع أي Server │
|
|
54
|
-
│ └────────────────────────┘ │
|
|
55
|
-
│ │
|
|
56
|
-
└────────────────────────────────────────────────────────────┘
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
---
|
|
60
|
-
|
|
61
|
-
## 3. Agent Canvas بالتفصيل
|
|
62
|
-
|
|
63
|
-
| الخاصية | الوصف |
|
|
64
|
-
|----------|--------|
|
|
65
|
-
| **التركيب** | `npm install -g @openhands/agent-canvas` |
|
|
66
|
-
| **التشغيل** | `agent-canvas` → localhost:8000 |
|
|
67
|
-
| **التقسيم** | `--frontend-only` لواجهة فقط، `--backend-only` لخادم فقط |
|
|
68
|
-
| **الغرض** | واجهة مرئية لعرض وتشغيل ومراقبة العملاء |
|
|
69
|
-
|
|
70
|
-
### الميزات
|
|
71
|
-
- تشغيل عدة عملاء بالتوازي
|
|
72
|
-
- Dashboard لكل عميل (حالته، مخرجاته، سجلاته)
|
|
73
|
-
- التبديل بين Backends مختلفة دون فقدان السياق
|
|
74
|
-
- إضافة Backends جديدة من الواجهة نفسها
|
|
75
|
-
|
|
76
|
-
---
|
|
77
|
-
|
|
78
|
-
## 4. Agent Server بالتفصيل
|
|
79
|
-
|
|
80
|
-
```
|
|
81
|
-
Agent Canvas → HTTP REST → Agent Server → Agent (OpenHands/Claude/Codex)
|
|
82
|
-
```
|
|
83
|
-
|
|
84
|
-
| الخاصية | الوصف |
|
|
85
|
-
|----------|--------|
|
|
86
|
-
| **التشغيل** | محلي، Docker، VM، Mac Mini، سحابة |
|
|
87
|
-
| **اللغة** | Python (uv) |
|
|
88
|
-
| **REST API** | نعم — endpoints لتشغيل وإدارة العملاء |
|
|
89
|
-
| **Multi-Server** | يمكن التبديل بين Servers متعددة |
|
|
90
|
-
| **Sandbox** | اختياري — Docker isolation |
|
|
91
|
-
|
|
92
|
-
### أين يُشغّل؟
|
|
93
|
-
- مباشرة على اللابتوب (⚠️ وصول كامل للملفات)
|
|
94
|
-
- على Mac Mini مخصص
|
|
95
|
-
- على VM في السحابة
|
|
96
|
-
- داخل Docker (موصى به)
|
|
97
|
-
- OpenHands Cloud (تجاري)
|
|
98
|
-
|
|
99
|
-
---
|
|
100
|
-
|
|
101
|
-
## 5. Automation Server
|
|
102
|
-
|
|
103
|
-
| الخاصية | الوصف |
|
|
104
|
-
|----------|--------|
|
|
105
|
-
| **الجدولة** | Cron — مجدولة زمنياً |
|
|
106
|
-
| **الأحداث** | Webhooks — GitHub, Linear, Slack |
|
|
107
|
-
| **التكاملات** | Slack, GitHub, Notion, Datadog |
|
|
108
|
-
| **الغرض** | تشغيل العملاء دون تدخل يدوي |
|
|
109
|
-
|
|
110
|
-
### أمثلة
|
|
111
|
-
- "كل صباح: راجع الـ PRs المفتوحة وقدم ملخصاً"
|
|
112
|
-
- "عند إغلاق Issue → حلل السبب الجذري"
|
|
113
|
-
- "عند Push إلى main → شغّل اختبارات الأمان"
|
|
114
|
-
|
|
115
|
-
---
|
|
116
|
-
|
|
117
|
-
## 6. ACP — Agent-Client Protocol
|
|
118
|
-
|
|
119
|
-
**هذا أهم ما في OpenHands معمارياً.**
|
|
120
|
-
|
|
121
|
-
```
|
|
122
|
-
[Agent Client Protocol - ACP]
|
|
123
|
-
┌─────────┐ ┌──────────────┐
|
|
124
|
-
│ Claude │ │ OpenHands │
|
|
125
|
-
│ Code │←────→│ Agent │
|
|
126
|
-
└─────────┘ └──────────────┘
|
|
127
|
-
┌─────────┐ ┌──────────────┐
|
|
128
|
-
│ Codex │←────→│ Agent │
|
|
129
|
-
└─────────┘ └──────────────┘
|
|
130
|
-
┌─────────┐ ┌──────────────┐
|
|
131
|
-
│ Gemini │←────→│ Agent │
|
|
132
|
-
└─────────┘ └──────────────┘
|
|
133
|
-
```
|
|
134
|
-
|
|
135
|
-
- بروتوكول REST موحّد
|
|
136
|
-
- أي عميل يتوافق مع ACP يعمل مع أي Server يدعم ACP
|
|
137
|
-
- يسمح بالتبديل بين العملاء دون تغيير البنية التحتية
|
|
138
|
-
- **يذكّرني بـ TeraSubAgents.md لكن كبروتوكول رسمي**
|
|
139
|
-
|
|
140
|
-
---
|
|
141
|
-
|
|
142
|
-
## 7. مقارنة مع Tera — الوضع الحالي
|
|
143
|
-
|
|
144
|
-
| المفهوم | OpenHands | Tera (حالياً) |
|
|
145
|
-
|---------|-----------|---------------|
|
|
146
|
-
| **واجهة تحكم** | Agent Canvas (UI) | ❌ لا يوجد |
|
|
147
|
-
| **تشغيل العملاء** | Agent Server (REST) | ✅ task tool + .opencode/agents/ |
|
|
148
|
-
| **أتمتة مجدولة** | Automation Server (Cron) | ❌ يدوي بالكامل |
|
|
149
|
-
| **بروتوكول موحّد** | ACP | 🟡 TeraSubAgents.md (نصي) |
|
|
150
|
-
| **عزل العملاء** | Sandbox (Docker) | ❌ لا يوجد |
|
|
151
|
-
| **Multi-Backend** | Local + Docker + VM + Cloud | ❌ جهاز واحد |
|
|
152
|
-
| **تكامل خارجي** | Slack, GitHub, Linear, Notion | ❌ لا يوجد |
|
|
153
|
-
| **التوسع** | أفقي (Servers متعددة) | 🟡 عمودي (عملاء أكثر) |
|
|
154
|
-
|
|
155
|
-
---
|
|
156
|
-
|
|
157
|
-
## 8. ما يمكن استلهامه لتطوير Tera
|
|
158
|
-
|
|
159
|
-
### 8.1 ACP → TeraSubAgents.md v2
|
|
160
|
-
تحويل TeraSubAgents.md من "ملف تعريف" إلى "بروتوكول اتصال" يحدد:
|
|
161
|
-
- كيف يستدعي عميل عميلاً آخر
|
|
162
|
-
- ما هي Request/Response format
|
|
163
|
-
- كيف يُدار السياق بين العملاء
|
|
164
|
-
|
|
165
|
-
### 8.2 Agent Canvas → Tera Dashboard
|
|
166
|
-
لوحة تحكم لـ Majed:
|
|
167
|
-
- يرى كل العملاء (TeraAgent, Engineering, UI, QA...)
|
|
168
|
-
- حالة كل عميل (شغال؟ منتظر؟ مكتمل؟)
|
|
169
|
-
- سجلات ومخرجات كل عميل
|
|
170
|
-
|
|
171
|
-
### 8.3 Automation Server → Tera Scheduler
|
|
172
|
-
تشغيل مهام دورية:
|
|
173
|
-
- "افحص جميع المشاريع بـ Trivy كل أسبوع"
|
|
174
|
-
- "أرسل تقرير الجودة كل يوم جمعة"
|
|
175
|
-
- "راقب تحديثات الأمان في dependencies"
|
|
176
|
-
|
|
177
|
-
### 8.4 Agent Server → Tera Execution Layer
|
|
178
|
-
فصل "من يقرر" عن "من ينفذ":
|
|
179
|
-
- TeraAgent يقرر فقط (كما هو الآن)
|
|
180
|
-
- Execution Layer جديد يشغّل العملاء (مثل Agent Server)
|
|
181
|
-
- يمكن تشغيل Execution Layer على Docker أو VM
|
|
182
|
-
|
|
183
|
-
---
|
|
184
|
-
|
|
185
|
-
## 9. سيناريو التطبيق الجذري (نسخة أخرى من Tera)
|
|
186
|
-
|
|
187
|
-
```
|
|
188
|
-
┌──────────────────────────────────────────────┐
|
|
189
|
-
│ Tera v2 (مقترح) │
|
|
190
|
-
├──────────────────────────────────────────────┤
|
|
191
|
-
│ │
|
|
192
|
-
│ ┌──────────────────────┐ │
|
|
193
|
-
│ │ Tera Dashboard │ ← UI لإدارة العملاء │
|
|
194
|
-
│ ├──────────────────────┤ │
|
|
195
|
-
│ │ Tera Execution │ ← REST API Layer │
|
|
196
|
-
│ │ Server │ لتشغيل العملاء │
|
|
197
|
-
│ ├──────────────────────┤ │
|
|
198
|
-
│ │ Tera Protocol │ ← ACP-like protocol│
|
|
199
|
-
│ │ (TP-1) │ للتواصل بين │
|
|
200
|
-
│ │ │ العملاء │
|
|
201
|
-
│ ├──────────────────────┤ │
|
|
202
|
-
│ │ Tera Scheduler │ ← Cron + Events │
|
|
203
|
-
│ ├──────────────────────┤ │
|
|
204
|
-
│ │ Sandbox Manager │ ← Docker isolation │
|
|
205
|
-
│ └──────────────────────┘ │
|
|
206
|
-
│ │
|
|
207
|
-
│ ════════════════════════════════════════ │
|
|
208
|
-
│ │
|
|
209
|
-
│ يبقى Tera v1 (الحالي) كما هو للإنتاج. │
|
|
210
|
-
│ Tera v2 يُبنى بالتوازي كإعادة هيكلة. │
|
|
211
|
-
│ │
|
|
212
|
-
└──────────────────────────────────────────────┘
|
|
213
|
-
```
|
|
214
|
-
|
|
215
|
-
---
|
|
216
|
-
|
|
217
|
-
## 10. روابط مهمة للدراسة
|
|
218
|
-
|
|
219
|
-
| الرابط | الوصف |
|
|
220
|
-
|--------|--------|
|
|
221
|
-
| https://github.com/OpenHands/OpenHands | المستودع الرئيسي |
|
|
222
|
-
| https://github.com/OpenHands/software-agent-sdk | الـ SDK الرسمي للـ Agent و Agent Server |
|
|
223
|
-
| https://github.com/OpenHands/agent-canvas | واجهة التحكم الأمامية |
|
|
224
|
-
| https://github.com/OpenHands/automation | سيرفر الأتمتة |
|
|
225
|
-
| https://docs.openhands.dev/overview/introduction | التوثيق الرسمي |
|
|
226
|
-
| https://docs.openhands.dev/openhands/usage/agent-canvas/acp-agents | ACP Protocol specs |
|
|
227
|
-
| https://docs.openhands.dev/openhands/usage/agent-canvas/backend-setup/vm | دليل Self-Hosting |
|
|
228
|
-
|
|
229
|
-
---
|
|
230
|
-
|
|
231
|
-
## 11. حالة الدراسة
|
|
232
|
-
|
|
233
|
-
- [ ] قراءة ACP Specifications
|
|
234
|
-
- [ ] تحليل Agent Server Architecture
|
|
235
|
-
- [ ] تحليل Agent Canvas Architecture
|
|
236
|
-
- [ ] دراسة Automation Server
|
|
237
|
-
- [ ] مقارنة مع TeraSubAgents.md
|
|
238
|
-
- [ ] إنتاج SYSTEM_CHANGE_PROPOSAL للتحسينات المستوحاة
|
|
239
|
-
- [ ] بدء Tera v2 بالتوازي (اختياري)
|
|
240
|
-
|
|
241
|
-
---
|
|
242
|
-
|
|
243
|
-
> **ملاحظة:** هذا الملف مرجعي بحت. أي دراسة أو تطبيق يتطلب الرجوع إلى المصادر الأصلية والموافقة على SYSTEM_CHANGE_PROPOSAL قبل التنفيذ.
|