afyx-engineering-kit 0.0.0-stage → 0.1.0-alpha.3
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/.afyx-source-revision +1 -0
- package/LICENSE +21 -0
- package/README.md +377 -2
- package/SECURITY.md +74 -0
- package/afyx-context/LICENSE +21 -0
- package/afyx-context/README.md +155 -0
- package/afyx-context/afyx-context.json +30 -0
- package/afyx-context/contracts/integration-v1.schema.json +34 -0
- package/afyx-context/package-lock.json +53 -0
- package/afyx-context/package.json +34 -0
- package/afyx-context/scripts/benchmark.mjs +39 -0
- package/afyx-context/scripts/build.mjs +15 -0
- package/afyx-context/scripts/comparative-benchmark.mjs +342 -0
- package/afyx-context/scripts/comparative-worker.mjs +74 -0
- package/afyx-context/scripts/graph-integration-e2e.mjs +188 -0
- package/afyx-context/scripts/integrated-dogfood.mjs +309 -0
- package/afyx-context/src/budget.js +166 -0
- package/afyx-context/src/cli.js +110 -0
- package/afyx-context/src/coordination.js +343 -0
- package/afyx-context/src/engine.js +198 -0
- package/afyx-context/src/errors.js +14 -0
- package/afyx-context/src/graph-integration-worker.js +70 -0
- package/afyx-context/src/graph-integration.js +373 -0
- package/afyx-context/src/graph-mcp-bridge.js +103 -0
- package/afyx-context/src/index.js +25 -0
- package/afyx-context/src/integrations.js +87 -0
- package/afyx-context/src/memory.js +255 -0
- package/afyx-context/src/storage.js +364 -0
- package/afyx-context/test-fixtures/coordination-worker.mjs +52 -0
- package/afyx-context/test-fixtures/graph-consumer-repo/addons/sale_extension/__init__.py +1 -0
- package/afyx-context/test-fixtures/graph-consumer-repo/addons/sale_extension/__manifest__.py +4 -0
- package/afyx-context/test-fixtures/graph-consumer-repo/addons/sale_extension/models/__init__.py +1 -0
- package/afyx-context/test-fixtures/graph-consumer-repo/addons/sale_extension/models/sale_order.py +5 -0
- package/afyx-context/test-fixtures/integrated-dogfood-repo/addons/integrated_sales/__init__.py +1 -0
- package/afyx-context/test-fixtures/integrated-dogfood-repo/addons/integrated_sales/__manifest__.py +10 -0
- package/afyx-context/test-fixtures/integrated-dogfood-repo/addons/integrated_sales/models/__init__.py +2 -0
- package/afyx-context/test-fixtures/integrated-dogfood-repo/addons/integrated_sales/models/sale_order.py +20 -0
- package/afyx-context/test-fixtures/integrated-dogfood-repo/addons/integrated_sales/models/sale_order_audit.py +11 -0
- package/afyx-context/test-fixtures/integrated-dogfood-repo/addons/integrated_sales/security/ir.model.access.csv +2 -0
- package/afyx-context/test-fixtures/integrated-dogfood-repo/addons/integrated_sales/views/sale_order_views.xml +14 -0
- package/afyx-forge/LICENSE +55 -0
- package/afyx-forge/README.md +126 -0
- package/afyx-forge/afyx-forge.json +28 -0
- package/afyx-forge/bin/afyx-forge +4 -0
- package/afyx-forge/bin/afyx-forge.cmd +3 -0
- package/afyx-forge/bin/afyx-forge.js +16 -0
- package/afyx-forge/contracts/forge-plan-v1.schema.json +172 -0
- package/afyx-forge/package.json +26 -0
- package/afyx-forge/src/classifier.js +190 -0
- package/afyx-forge/src/cli.js +111 -0
- package/afyx-forge/src/doctor.js +105 -0
- package/afyx-forge/src/guidance.js +120 -0
- package/afyx-forge/src/index.js +273 -0
- package/afyx-forge/src/planning.js +107 -0
- package/afyx-forge/src/policy.js +109 -0
- package/afyx-forge/src/workflow-refiner.js +151 -0
- package/afyx-graph/afyx-graph.json +20 -0
- package/afyx-graph/engine/LICENSE +21 -0
- package/afyx-graph/engine/README.md +104 -0
- package/afyx-graph/engine/release/RELEASE-MANIFEST.json +21 -0
- package/afyx-graph/engine/release/SHA256SUMS +2 -0
- package/afyx-graph/engine/release/afyx-graph-linux-x64.tar.gz +0 -0
- package/afyx-graph/engine/release/afyx-graph-win32-x64.zip +0 -0
- package/afyx-graph/engine/scripts/distribution-contract.mjs +212 -0
- package/afyx-graph/engine/scripts/distribution-product.json +33 -0
- package/bin/afyx-engineering-kit.mjs +61 -0
- package/install.ps1 +1053 -0
- package/install.sh +617 -0
- package/package.json +66 -4
- package/scripts/afyx-capability-orchestrator.mjs +752 -0
- package/scripts/afyx-claude-integration.mjs +547 -0
- package/scripts/afyx-context-artifact.mjs +105 -0
- package/scripts/afyx-credential-broker.mjs +75 -0
- package/scripts/afyx-doctor.ps1 +152 -0
- package/scripts/afyx-doctor.sh +146 -0
- package/scripts/afyx-forge-artifact.mjs +183 -0
- package/scripts/afyx-global-routing-policy.md +12 -0
- package/scripts/afyx-global-routing.mjs +168 -0
- package/scripts/afyx-graph-artifact.mjs +178 -0
- package/scripts/afyx-host-adapters.mjs +543 -0
- package/scripts/afyx-host-bridge-lifecycle.mjs +174 -0
- package/scripts/afyx-host-bridge.mjs +288 -0
- package/scripts/afyx-integration-contracts.mjs +825 -0
- package/scripts/afyx-mcp-integration.mjs +528 -0
- package/scripts/afyx-modular-integration.mjs +361 -0
- package/scripts/afyx-modular-runtime.mjs +451 -0
- package/scripts/afyx-native-skill-host.mjs +124 -0
- package/scripts/afyx-npm-installer.mjs +486 -0
- package/scripts/afyx-project.ps1 +205 -0
- package/scripts/afyx-project.sh +207 -0
- package/scripts/afyx-provider-backup.mjs +1206 -0
- package/scripts/afyx-provider-integration.mjs +724 -0
- package/scripts/afyx-provider-inventory.mjs +147 -0
- package/scripts/afyx-security-auditor.mjs +224 -0
- package/scripts/afyx-skill-engineering.mjs +354 -0
- package/scripts/afyx-tool-family-routing.mjs +64 -0
- package/scripts/afyx-universal-runtime.mjs +530 -0
- package/scripts/alpha_acceptance_preflight.py +240 -0
- package/scripts/benchmark-graph-memory.mjs +96 -0
- package/scripts/benchmark_capability_orchestrator.mjs +64 -0
- package/scripts/build-windows-installer.ps1 +259 -0
- package/scripts/build_forge_synthetic_image.py +328 -0
- package/scripts/check-reference-staleness.py +71 -0
- package/scripts/components.json +254 -0
- package/scripts/contracts/afyx-capability-request-v1.schema.json +189 -0
- package/scripts/contracts/afyx-capability-result-v1.schema.json +32 -0
- package/scripts/dogfood_engineering_comparison.mjs +303 -0
- package/scripts/engineering-assurance.json +28 -0
- package/scripts/install-afyx-context.ps1 +142 -0
- package/scripts/install-afyx-context.sh +126 -0
- package/scripts/install-afyx-forge.ps1 +265 -0
- package/scripts/install-afyx-forge.sh +273 -0
- package/scripts/install-afyx-graph.ps1 +571 -0
- package/scripts/install-afyx-graph.sh +438 -0
- package/scripts/install-codex-usage-tracker.ps1 +172 -0
- package/scripts/lib/AfyxComponents.psm1 +399 -0
- package/scripts/lib/AfyxSkillLifecycle.psm1 +289 -0
- package/scripts/lib/AfyxTerminal.psm1 +838 -0
- package/scripts/lib/afyx-components.sh +256 -0
- package/scripts/lib/afyx-skill-lifecycle.sh +271 -0
- package/scripts/link-global-dev.ps1 +193 -0
- package/scripts/link-global-dev.sh +130 -0
- package/scripts/phase8-paired-evidence.mjs +195 -0
- package/scripts/phase8-representative-workload.mjs +771 -0
- package/scripts/phase8-session-recorder.mjs +157 -0
- package/scripts/phase8_event_ledger.py +248 -0
- package/scripts/phase8_evidence_discovery.py +189 -0
- package/scripts/prepare-g6-package.mjs +349 -0
- package/scripts/resolve-git-release-artifacts.mjs +321 -0
- package/scripts/stage-npm-release.mjs +94 -0
- package/scripts/validate-afyx-graph.py +203 -0
- package/scripts/validate-components.py +194 -0
- package/scripts/validate-engineering-assurance.py +281 -0
- package/scripts/verify-graph-archive.mjs +64 -0
- package/skills/afyx-context/SKILL.md +26 -0
- package/skills/afyx-engineering-expert/README.md +42 -0
- package/skills/afyx-engineering-expert/SKILL.md +70 -0
- package/skills/afyx-engineering-expert/assets/result-template.md +15 -0
- package/skills/afyx-engineering-expert/references/ai-ml-engineer.md +17 -0
- package/skills/afyx-engineering-expert/references/business-analyst.md +17 -0
- package/skills/afyx-engineering-expert/references/clean-code-engineer.md +26 -0
- package/skills/afyx-engineering-expert/references/code-reviewer.md +24 -0
- package/skills/afyx-engineering-expert/references/cybersecurity-devsecops.md +17 -0
- package/skills/afyx-engineering-expert/references/data-analyst-bi.md +24 -0
- package/skills/afyx-engineering-expert/references/data-engineer.md +24 -0
- package/skills/afyx-engineering-expert/references/database-administrator.md +17 -0
- package/skills/afyx-engineering-expert/references/debugging-specialist.md +24 -0
- package/skills/afyx-engineering-expert/references/embedded-iot-engineer.md +24 -0
- package/skills/afyx-engineering-expert/references/erp-technical-specialist.md +17 -0
- package/skills/afyx-engineering-expert/references/hardware-diagnostics-auditor.md +24 -0
- package/skills/afyx-engineering-expert/references/hardware-electronics-engineer.md +24 -0
- package/skills/afyx-engineering-expert/references/integration-engineer.md +24 -0
- package/skills/afyx-engineering-expert/references/legacy-modernization-engineer.md +24 -0
- package/skills/afyx-engineering-expert/references/llmops-prompt-engineer.md +24 -0
- package/skills/afyx-engineering-expert/references/network-engineer.md +24 -0
- package/skills/afyx-engineering-expert/references/performance-benchmark-engineer.md +24 -0
- package/skills/afyx-engineering-expert/references/platform-engineer.md +24 -0
- package/skills/afyx-engineering-expert/references/product-manager.md +17 -0
- package/skills/afyx-engineering-expert/references/qa-engineer.md +17 -0
- package/skills/afyx-engineering-expert/references/site-reliability-engineer.md +17 -0
- package/skills/afyx-engineering-expert/references/software-engineer.md +17 -0
- package/skills/afyx-engineering-expert/references/solutions-architect.md +17 -0
- package/skills/afyx-engineering-expert/references/specialists-index.md +33 -0
- package/skills/afyx-engineering-expert/references/subject-matter-expert.md +17 -0
- package/skills/afyx-engineering-expert/references/system-analyst.md +17 -0
- package/skills/afyx-engineering-expert/references/technical-project-manager.md +24 -0
- package/skills/afyx-engineering-expert/references/technical-writer.md +24 -0
- package/skills/afyx-engineering-expert/references/ui-ux-designer.md +17 -0
- package/skills/afyx-engineering-expert/workflows/ai-data-erp.md +20 -0
- package/skills/afyx-engineering-expert/workflows/debugging.md +10 -0
- package/skills/afyx-engineering-expert/workflows/discovery-design.md +11 -0
- package/skills/afyx-engineering-expert/workflows/implementation.md +12 -0
- package/skills/afyx-engineering-expert/workflows/incident-reliability.md +12 -0
- package/skills/afyx-engineering-expert/workflows/review-audit.md +13 -0
- package/skills/afyx-forge/SKILL.md +43 -0
- package/skills/afyx-forge/references/adaptive-policy.md +19 -0
- package/skills/efficient-coding/SKILL.md +33 -0
- package/skills/efficient-coding/references/investigation.md +27 -0
- package/skills/efficient-coding/references/token-efficiency.md +25 -0
- package/skills/efficient-coding/references/tool-routing.md +13 -0
- package/skills/odoo-engineering/SKILL.md +33 -0
- package/skills/odoo-engineering/references/common.md +9 -0
- package/skills/odoo-engineering/references/odoo-10.md +32 -0
- package/skills/odoo-engineering/references/odoo-11.md +26 -0
- package/skills/odoo-engineering/references/odoo-12.md +31 -0
- package/skills/odoo-engineering/references/odoo-13.md +27 -0
- package/skills/odoo-engineering/references/odoo-14.md +31 -0
- package/skills/odoo-engineering/references/odoo-15.md +34 -0
- package/skills/odoo-engineering/references/odoo-16.md +37 -0
- package/skills/odoo-engineering/references/odoo-17.md +37 -0
- package/skills/odoo-engineering/references/odoo-18.md +48 -0
- package/skills/odoo-engineering/references/odoo-19.md +43 -0
- package/skills/odoo-engineering/references/odoo-20.md +39 -0
- package/skills/odoo-engineering/references/reference-schema.md +16 -0
- package/skills/odoo-engineering/references/version-detection.md +13 -0
- package/tools/codex-usage/CodexUsage.psm1 +496 -0
- package/tools/codex-usage/codex-usage-doctor.ps1 +150 -0
- package/tools/codex-usage/codex-usage-pricing.json +25 -0
- package/tools/codex-usage/codex-usage-stop.ps1 +167 -0
- package/tools/codex-usage/codex-usage-watch.ps1 +250 -0
- package/tools/codex-usage/vscode-user-task.json +31 -0
- package/tools/windows-setup/SetupBootstrapper.cs +258 -0
- package/uninstall.ps1 +189 -0
- package/uninstall.sh +167 -0
- package/update.ps1 +95 -0
- package/update.sh +67 -0
- package/verify.ps1 +411 -0
- package/verify.sh +265 -0
|
@@ -0,0 +1 @@
|
|
|
1
|
+
62aeb1a867c5ba35686710d76551608f0c97eff7
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Afyx
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,378 @@
|
|
|
1
|
-
#
|
|
1
|
+
# AFYX Engineering Kit
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**Local-first engineering intelligence, adaptive guidance, and evidence-driven validation for AI coding agents.**
|
|
4
|
+
|
|
5
|
+
> **Individually Reliable. Collectively Solid.**
|
|
6
|
+
>
|
|
7
|
+
> **Evidence-Led Guidance. Bounded Scopes. Strict Integrity. Reproducible Acceptance.**
|
|
8
|
+
>
|
|
9
|
+
> **Standalone by Design. Integrated by Contract. Activated by Need.**
|
|
10
|
+
|
|
11
|
+
AFYX Engineering Kit unites six independent engineering products in a
|
|
12
|
+
modular ecosystem for AI-assisted software development. Use each product
|
|
13
|
+
on its own or combine eligible capabilities through shared installation and
|
|
14
|
+
routing contracts. The design prioritizes source evidence, permission boundaries,
|
|
15
|
+
focused validation, and failure isolation over unqualified automation claims.
|
|
16
|
+
|
|
17
|
+
**Status:** Technical Alpha · **Full runtime tested:** Windows x64 and Linux x64
|
|
18
|
+
(WSL2 Ubuntu) · **macOS/ARM Full:** no bundled Graph archive; runtime untested ·
|
|
19
|
+
**Integration:** Optional and task-driven.
|
|
20
|
+
|
|
21
|
+
Graph, Forge, Context Engine, and Engineering Expert provide four foundational
|
|
22
|
+
engineering pillars. Efficient Coding and Odoo Engineering are **equally
|
|
23
|
+
recognized standalone products**, not merely auxiliary documentation.
|
|
24
|
+
|
|
25
|
+
## Why Afyx
|
|
26
|
+
|
|
27
|
+
Ordinary coding assistants can generate plausible changes while leaving the
|
|
28
|
+
engineer to establish repository structure, impact, version-specific behavior,
|
|
29
|
+
and acceptance evidence. Afyx adds reusable engineering controls around that
|
|
30
|
+
workflow:
|
|
31
|
+
|
|
32
|
+
- **Structural repository intelligence** with verifiable file, symbol, call-path,
|
|
33
|
+
dependency, impact, and index-health evidence.
|
|
34
|
+
- **Cross-disciplinary engineering orchestration** that selects only the product,
|
|
35
|
+
architecture, security, data, reliability, implementation, ERP, or QA guidance
|
|
36
|
+
relevant to the task.
|
|
37
|
+
- **Fail-closed evaluation contracts** for controlled engineering comparison and
|
|
38
|
+
evidence handling.
|
|
39
|
+
- **Optional context reduction with exact-original recovery**, never replacing the
|
|
40
|
+
original when doing so would be unsafe or more expensive.
|
|
41
|
+
- **Transactional installation and recovery** with ownership boundaries, preview,
|
|
42
|
+
verification, backup, update, and uninstall behavior shared across platforms.
|
|
43
|
+
|
|
44
|
+
Afyx is aimed at engineers and technical owners who value source evidence,
|
|
45
|
+
bounded change, explicit limitations, and reproducible acceptance more than
|
|
46
|
+
unqualified automation claims.
|
|
47
|
+
|
|
48
|
+
## Six standalone Afyx products
|
|
49
|
+
|
|
50
|
+
The ecosystem consists of **six independently usable products**. Each provides
|
|
51
|
+
a distinct engineering capability; no product requires the whole Kit. An installed
|
|
52
|
+
capability is selected only when relevant, healthy, and authorized.
|
|
53
|
+
|
|
54
|
+
| Product | Core capability | Implementation and maturity |
|
|
55
|
+
|---|---|---|
|
|
56
|
+
| [**Afyx Graph**](afyx-graph/engine/README.md) | Local indexing, structural code intelligence, symbol/dependency navigation, impact and affected-test analysis, CLI and optional MCP. | **Standalone Node.js runtime · Technical Alpha**; static evidence requires runtime/test verification. |
|
|
57
|
+
| [**Afyx Forge**](afyx-forge/README.md) | Deterministic task classification, engineering policies, bounded plans, and diagnostics through Forge Core; distinct evaluation infrastructure. | **Standalone Node.js CLI/API v0.1.0 · Technical Alpha**; bounded local assistive planning approved, not autonomous code changes; historical 36-cell evaluation remains `NOT_RUN`. |
|
|
58
|
+
| [**Afyx Efficient Coding**](docs/tool-guides/AFYX_EFFICIENT_CODING.md) | Evidence-led coding, debugging, refactoring, focused validation, and engineering reporting. | **Standalone agent skill v1.2.2 · Implemented**; guidance, not an execution engine. |
|
|
59
|
+
| [**Afyx Odoo Engineering**](docs/tool-guides/AFYX_ODOO_ENGINEERING.md) | Odoo-specific ORM, views, security, module development, migration, and troubleshooting. | **Standalone agent skill v1.2.0 · Implemented**; reference coverage Odoo 10–20, with target-version verification required. |
|
|
60
|
+
| [**Afyx Context Engine (ACE)**](afyx-context/README.md) | Conservative context reduction, local storage, integrity checks, and exact-original recovery. | **Standalone Node.js runtime v0.1.0 · Technical Alpha**; explicit Kit selection, no universal savings guarantee. |
|
|
61
|
+
| [**Afyx Engineering Expert**](skills/afyx-engineering-expert/README.md) | Adaptive engineering guidance across 13 disciplines and six optional workflows. | **Standalone agent skill v0.1.1 · Implemented**; final D.6 substantive acceptance remains pending. |
|
|
62
|
+
|
|
63
|
+
### Platform services and supporting utilities
|
|
64
|
+
|
|
65
|
+
The cross-platform **installer, updater, verifier, doctor, and capability router**
|
|
66
|
+
are shared Kit infrastructure, **not separate products**. Optional Windows
|
|
67
|
+
[Afyx Codex Usage Tracking](docs/CODEX_USAGE_TRACKER.md) is a seventh registered
|
|
68
|
+
observability utility, not one of the six primary engineering products.
|
|
69
|
+
|
|
70
|
+
The [component registry](scripts/components.json) is authoritative for
|
|
71
|
+
installable IDs, presets, supported platforms, and ownership. Consult the
|
|
72
|
+
[Component Guide](docs/COMPONENTS.md) for detailed functionality and limitations.
|
|
73
|
+
|
|
74
|
+
## How the products fit together
|
|
75
|
+
|
|
76
|
+
```mermaid
|
|
77
|
+
flowchart TB
|
|
78
|
+
H["Engineer or AI coding host"]
|
|
79
|
+
K["Afyx Kit lifecycle and capability router"]
|
|
80
|
+
G["Afyx Graph"]
|
|
81
|
+
F["Afyx Forge"]
|
|
82
|
+
EC["Afyx Efficient Coding"]
|
|
83
|
+
O["Afyx Odoo Engineering"]
|
|
84
|
+
ACE["Afyx Context Engine"]
|
|
85
|
+
E["Afyx Engineering Expert"]
|
|
86
|
+
|
|
87
|
+
H --> K
|
|
88
|
+
K -.-> G
|
|
89
|
+
K -.-> F
|
|
90
|
+
K -.-> EC
|
|
91
|
+
K -.-> O
|
|
92
|
+
K -.-> ACE
|
|
93
|
+
K -.-> E
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
**Diagram legend:** The solid arrow shows the Kit entry point; dashed arrows
|
|
97
|
+
mean **optional, task-scoped selection**, not automatic activation or a claim
|
|
98
|
+
that every provider integration has passed acceptance. Every Afyx product can
|
|
99
|
+
also run independently through its advertised interface. Installation alone
|
|
100
|
+
does not imply execution; user-disabled capabilities remain disabled.
|
|
101
|
+
|
|
102
|
+
Registry-based routing and interaction contracts have source-level
|
|
103
|
+
implementations. Full installed-host interoperability is not claimed as
|
|
104
|
+
accepted. Graph-to-ACE automatic MCP interception remains default **OFF**;
|
|
105
|
+
Forge Core offers assistive plans and has no autonomous execution authority.
|
|
106
|
+
The [interoperability contract](docs/AFYX_UNIVERSAL_COMPONENT_INTEROPERABILITY.md)
|
|
107
|
+
distinguishes approved target behavior from proven current behavior.
|
|
108
|
+
|
|
109
|
+
## Current product status
|
|
110
|
+
|
|
111
|
+
This repository is a **Technical Alpha prerelease**. It is not Stable v1, no
|
|
112
|
+
formal public Alpha approval is implied, and publisher authenticity remains
|
|
113
|
+
unverified unless an artifact has an independently verified attestation.
|
|
114
|
+
|
|
115
|
+
- Graph, the Kit lifecycle, ACE, Efficient Coding, Odoo Engineering, and
|
|
116
|
+
Engineering Expert have implemented runtime or skill contracts with regression
|
|
117
|
+
evidence appropriate to their respective interfaces.
|
|
118
|
+
- ACE and Forge are included in the Full preset; Minimal and Recommended omit
|
|
119
|
+
them. Installation does not grant autonomous execution. Healthy installed ACE
|
|
120
|
+
is used only for eligible on-demand work and respects explicit OFF.
|
|
121
|
+
- Automatic Graph–ACE MCP interception remains unproven/default OFF; optional
|
|
122
|
+
consumer paths have exact-original fallback. Context measurements include
|
|
123
|
+
positive and negative net results—no universal savings claim is made.
|
|
124
|
+
- Forge Core has a real standalone assistive CLI/API and explicitly selectable
|
|
125
|
+
runtime on supported installation paths. This is distinct from the formal Forge
|
|
126
|
+
B0–B5 evaluator campaign: its 36 cells remain `NOT_RUN`; the Owner's A8 GO
|
|
127
|
+
applies only to bounded local assistive planning, never autonomous execution.
|
|
128
|
+
- Engineering Expert is usable as a skill, while final D.6 substantive review is
|
|
129
|
+
still outside the accepted claims.
|
|
130
|
+
|
|
131
|
+
**Verified CI checkpoint (2026-11-05):** the `dev` merge
|
|
132
|
+
[`e332230`](https://github.com/a5zero7/afyx-engineering-kit/commit/e332230a2c0ba162b447af1359cf591057ce26b6)
|
|
133
|
+
closed a Windows Vitest hook-timeout regression. The four post-merge workflows
|
|
134
|
+
reported `SUCCESS`: [Graph Build](https://github.com/a5zero7/afyx-engineering-kit/actions/runs/41988333699),
|
|
135
|
+
[Kit CI](https://github.com/a5zero7/afyx-engineering-kit/actions/runs/41988333765),
|
|
136
|
+
[Windows Installer](https://github.com/a5zero7/afyx-engineering-kit/actions/runs/41988333733), and
|
|
137
|
+
[Phase 8 Dogfood](https://github.com/a5zero7/afyx-engineering-kit/actions/runs/41988333780).
|
|
138
|
+
This is a CI checkpoint, **not** independent installed-product or Stable v1 acceptance.
|
|
139
|
+
|
|
140
|
+
See [Product Vision](docs/PRODUCT_VISION.md) for the maintained product contract
|
|
141
|
+
and [Component Guide](docs/COMPONENTS.md) for capability and limitation details.
|
|
142
|
+
|
|
143
|
+
## Install AFYX Engineering Kit — Windows & WSL2
|
|
144
|
+
|
|
145
|
+
### Public npm Alpha (pending release clearance)
|
|
146
|
+
|
|
147
|
+
With Node.js 22.5 or newer, the intended public registry command is:
|
|
148
|
+
|
|
149
|
+
```bash
|
|
150
|
+
npx afyx-engineering-kit install
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
Use `--preset recommended` for core engineering skills or `--preset full`
|
|
154
|
+
for the prebuilt Graph, Context, Forge, and applicable skills. `full` requires
|
|
155
|
+
Windows x64 or Linux x64 for Graph. Provider configuration is optional and
|
|
156
|
+
remains subject to each host's native prerequisites. Confirm the intended Alpha
|
|
157
|
+
version with `npm view afyx-engineering-kit@latest version`. Until the registry
|
|
158
|
+
lists a cleared release, use the GitHub prerelease tarball below.
|
|
159
|
+
|
|
160
|
+
### Local Developer Setup (Bare NPX Resolution)
|
|
161
|
+
|
|
162
|
+
For local development or offline environments where `npx afyx-engineering-kit install` must resolve without contacting public registries:
|
|
163
|
+
|
|
164
|
+
Windows 11 (PowerShell 7):
|
|
165
|
+
```powershell
|
|
166
|
+
.\scripts\link-global-dev.ps1 -Install
|
|
167
|
+
.\scripts\link-global-dev.ps1 -Verify
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
WSL2 Ubuntu (Bash):
|
|
171
|
+
```bash
|
|
172
|
+
./scripts/link-global-dev.sh --install
|
|
173
|
+
./scripts/link-global-dev.sh --verify
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
Once linked, bare `npx` resolves locally from any directory completely offline:
|
|
177
|
+
```bash
|
|
178
|
+
npx afyx-engineering-kit install --preset full --skip-provider-configuration
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
To remove the link:
|
|
182
|
+
```powershell
|
|
183
|
+
.\scripts\link-global-dev.ps1 -Uninstall
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
### GitHub prerelease tarball fallback
|
|
187
|
+
|
|
188
|
+
Alternatively, use the prebuilt tarball from the [v0.1.0-alpha.2 GitHub prerelease](https://github.com/a5zero7/afyx-engineering-kit/releases/tag/v0.1.0-alpha.2):
|
|
189
|
+
|
|
190
|
+
```bash
|
|
191
|
+
npm exec --yes --package="https://github.com/a5zero7/afyx-engineering-kit/releases/download/v0.1.0-alpha.2/afyx-engineering-kit-0.1.0-alpha.2.tgz" -- afyx-engineering-kit install --preset full --no-build-fallback --non-interactive --skip-provider-configuration
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
`full` installs the prebuilt Graph runtime, Context, Forge, and applicable
|
|
195
|
+
skills. Provider configuration is skipped by the example; select a supported
|
|
196
|
+
provider explicitly when you are ready to register its MCP integration. Verify
|
|
197
|
+
the installation with the same `npm exec --package=... --` prefix followed by
|
|
198
|
+
`afyx-engineering-kit verify --preset full`. Run `afyx-engineering-kit update`
|
|
199
|
+
with that prefix for an ownership-aware update, or `afyx-engineering-kit uninstall`
|
|
200
|
+
with an explicit component to remove it. See the [installation guide](docs/INSTALLATION.md)
|
|
201
|
+
for provider selection, recovery, and platform limits.
|
|
202
|
+
|
|
203
|
+
## Quick start
|
|
204
|
+
|
|
205
|
+
### Prerequisites
|
|
206
|
+
|
|
207
|
+
- Git.
|
|
208
|
+
- Windows PowerShell 5.1+ / PowerShell 7, or Bash 3.2+ on Linux/macOS.
|
|
209
|
+
- Supported AI coding host (Codex, Antigravity, or Claude Code; or run host-independent).
|
|
210
|
+
- Node.js 22.5+ when selecting Afyx Graph, ACE, or Forge Core.
|
|
211
|
+
- npm only when a local build fallback is needed.
|
|
212
|
+
|
|
213
|
+
### 1. Clone and preview
|
|
214
|
+
|
|
215
|
+
Windows:
|
|
216
|
+
|
|
217
|
+
```powershell
|
|
218
|
+
git clone https://github.com/a5zero7/afyx-engineering-kit.git
|
|
219
|
+
Set-Location afyx-engineering-kit
|
|
220
|
+
.\install.ps1 -ValidateOnly
|
|
221
|
+
.\install.ps1 -WhatIf -Preset recommended
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
Linux or macOS:
|
|
225
|
+
|
|
226
|
+
```bash
|
|
227
|
+
git clone https://github.com/a5zero7/afyx-engineering-kit.git
|
|
228
|
+
cd afyx-engineering-kit
|
|
229
|
+
./install.sh --validate-only
|
|
230
|
+
./install.sh --dry-run --preset recommended
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
Preview is non-mutating. Inspect every destination and planned action before
|
|
234
|
+
continuing.
|
|
235
|
+
|
|
236
|
+
### 2. Select an actual preset
|
|
237
|
+
|
|
238
|
+
| Preset | Desired components |
|
|
239
|
+
|---|---|
|
|
240
|
+
| `minimal` | Efficient Coding, Odoo Engineering |
|
|
241
|
+
| `recommended` | Minimal + Afyx Engineering Expert |
|
|
242
|
+
| `full` | Recommended + Afyx Graph, Context, Forge, and Windows-only Usage Tracking |
|
|
243
|
+
| `custom` | Only components repeated with `CustomComponent` / `--custom-component` |
|
|
244
|
+
|
|
245
|
+
ACE and Forge Core are included only in `full`. Installation does not authorize autonomous
|
|
246
|
+
Forge execution or automatic Graph MCP interception:
|
|
247
|
+
|
|
248
|
+
```powershell
|
|
249
|
+
.\install.ps1 -Preset custom -CustomComponent afyx-context -Confirm:$false
|
|
250
|
+
.\install.ps1 -Preset custom -CustomComponent afyx-forge -Confirm:$false
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
```bash
|
|
254
|
+
./install.sh --preset custom --custom-component afyx-context
|
|
255
|
+
# Forge Core has a dedicated standalone Unix installer:
|
|
256
|
+
./scripts/install-afyx-forge.sh --validate-only
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
Install Recommended:
|
|
260
|
+
|
|
261
|
+
```powershell
|
|
262
|
+
.\install.ps1 -Preset recommended
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
Supported AI coding host integrations include Codex, Antigravity, and Claude Code
|
|
266
|
+
(both standalone CLI and VS Code extension-only). Native provider-aware onboarding
|
|
267
|
+
registers integrations without changing credentials, models, or host routing:
|
|
268
|
+
|
|
269
|
+
```powershell
|
|
270
|
+
.\install.ps1 -Preset full -Provider codex,antigravity,claude -ProviderScope workspace -WorkspaceRoot (Get-Location)
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
Antigravity-only plans exclude the Codex Usage Tracking component. See the
|
|
274
|
+
[Installation Guide](docs/INSTALLATION.md#provider-aware-onboarding) for global
|
|
275
|
+
IDE/CLI skill paths, dry-run, verification, and ownership-safe rollback.
|
|
276
|
+
|
|
277
|
+
```bash
|
|
278
|
+
./install.sh --preset recommended
|
|
279
|
+
```
|
|
280
|
+
|
|
281
|
+
Open a new Codex session after skill installation.
|
|
282
|
+
|
|
283
|
+
### 3. Verify
|
|
284
|
+
|
|
285
|
+
```powershell
|
|
286
|
+
.\verify.ps1 -Preset recommended
|
|
287
|
+
.\scripts\afyx-doctor.ps1 -ProjectPath .
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
```bash
|
|
291
|
+
./verify.sh --preset recommended
|
|
292
|
+
./scripts/afyx-doctor.sh --project .
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
`verify` checks the desired lifecycle state. `doctor` reports local environment
|
|
296
|
+
and project diagnostics without installing, repairing, or calling a model.
|
|
297
|
+
|
|
298
|
+
## First useful workflows
|
|
299
|
+
|
|
300
|
+
### Discover and navigate a repository
|
|
301
|
+
|
|
302
|
+
```bash
|
|
303
|
+
afyx-graph init . --yes
|
|
304
|
+
afyx-graph query getAfyxGraphDir --path .
|
|
305
|
+
afyx-graph explore "external state database lifecycle" --path . --max-files 4
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
### Review change impact
|
|
309
|
+
|
|
310
|
+
```bash
|
|
311
|
+
afyx-graph impact getAfyxGraphDir --path . --depth 2
|
|
312
|
+
afyx-graph affected --path . src/directory.ts
|
|
313
|
+
```
|
|
314
|
+
|
|
315
|
+
Graph output is static repository evidence. It does not prove runtime behavior;
|
|
316
|
+
run the relevant tests and runtime checks before accepting a change.
|
|
317
|
+
|
|
318
|
+
### Plan a substantial engineering task with Forge Core
|
|
319
|
+
|
|
320
|
+
After installing the explicitly selected Forge runtime, ask it for a bounded
|
|
321
|
+
plan; it does not edit source files or execute tests on your behalf:
|
|
322
|
+
|
|
323
|
+
```bash
|
|
324
|
+
afyx-forge doctor
|
|
325
|
+
afyx-forge plan --task "Trace a cross-module data consistency regression" --format markdown
|
|
326
|
+
```
|
|
327
|
+
|
|
328
|
+
For source and full usage, see [Forge Core](afyx-forge/README.md). A planned
|
|
329
|
+
validation checklist is **not** a completed validation or formal A8 verdict.
|
|
330
|
+
|
|
331
|
+
### Ask for a cross-disciplinary review
|
|
332
|
+
|
|
333
|
+
```text
|
|
334
|
+
Use afyx-engineering-expert to review this authentication change. Cover the
|
|
335
|
+
architecture, threat boundary, operational failure modes, and acceptance tests;
|
|
336
|
+
load only the relevant disciplines.
|
|
337
|
+
```
|
|
338
|
+
|
|
339
|
+
For Odoo implementation facts, pair Expert with Odoo Engineering and establish
|
|
340
|
+
the target Odoo major version from repository or runtime evidence.
|
|
341
|
+
|
|
342
|
+
### Reduce and recover exact content with ACE
|
|
343
|
+
|
|
344
|
+
```bash
|
|
345
|
+
afyx-context reduce --state /absolute/owned/ace-state --owner local-owner \
|
|
346
|
+
--session reviewed-source-sha --input request.json --budget 16000
|
|
347
|
+
afyx-context get --state /absolute/owned/ace-state --owner local-owner \
|
|
348
|
+
--session reviewed-source-sha --reference 'ace:v1:...'
|
|
349
|
+
```
|
|
350
|
+
|
|
351
|
+
ACE state is local plaintext and must be protected by host filesystem controls.
|
|
352
|
+
References are owner/session-bound, and retrieval verifies the stored digest.
|
|
353
|
+
|
|
354
|
+
## Lifecycle and safety
|
|
355
|
+
|
|
356
|
+
The installer inventories before mutation and distinguishes `NOT INSTALLED`,
|
|
357
|
+
`HEALTHY`, `INCOMPLETE`, `INVALID`, `DRIFTED`, and `UNKNOWN`. Unknown or foreign
|
|
358
|
+
ownership is not silently adopted. Update/repair uses staging, validation,
|
|
359
|
+
backup, atomic promotion, and rollback. Project Graph indexes, credentials,
|
|
360
|
+
providers, models, unrelated MCP entries, and external tools are preserved.
|
|
361
|
+
|
|
362
|
+
- Safe installation, update, uninstall, and recovery: [Installation Guide](docs/INSTALLATION.md)
|
|
363
|
+
- Component capabilities and troubleshooting: [Component Guide](docs/COMPONENTS.md)
|
|
364
|
+
- Read-only diagnostics: [Diagnostics](docs/DIAGNOSTICS.md)
|
|
365
|
+
- Product principles and maturity: [Product Vision](docs/PRODUCT_VISION.md)
|
|
366
|
+
- Canonical development plan: [Afyx v1 Master Roadmap](docs/AFYX_V1_MASTER_ROADMAP.md)
|
|
367
|
+
- Benchmark scope and interpretation: [Benchmarks](docs/BENCHMARKS.md)
|
|
368
|
+
|
|
369
|
+
## License and third-party boundaries
|
|
370
|
+
|
|
371
|
+
License scope must be checked **per package**. The Kit root, Graph and ACE are
|
|
372
|
+
MIT-licensed in their respective license/metadata files; the standalone Forge
|
|
373
|
+
Core package currently declares `Apache-2.0` in `afyx-forge/package.json`.
|
|
374
|
+
Do not infer one blanket license from the umbrella README. The Phase 5/AFYX-320
|
|
375
|
+
native Graph/UI replacement and provenance review are recorded as completed
|
|
376
|
+
for their declared artifact boundary, not as a legal guarantee about every
|
|
377
|
+
future dependency or distribution. External tools remain under their own terms;
|
|
378
|
+
retain required notices and review provenance before release.
|
package/SECURITY.md
ADDED
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
# Security Policy
|
|
2
|
+
|
|
3
|
+
AFYX Engineering Kit is an open-source, local-first engineering toolkit designed for AI-assisted software engineering. Security and integrity are central design tenets. This document details the threat model, security boundaries, vulnerability reporting procedure, and best practices for safe operation.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Supported Versions
|
|
8
|
+
|
|
9
|
+
During the Technical Alpha phase, only the latest published Alpha release and the active `dev` branch receive security patches and vulnerability evaluations.
|
|
10
|
+
|
|
11
|
+
| Version | Status | Supported |
|
|
12
|
+
|---|---|---|
|
|
13
|
+
| `0.1.0-alpha.*` (latest) | Technical Alpha | Yes |
|
|
14
|
+
| Historical Alpha (< latest) | Superseded | No (upgrade required) |
|
|
15
|
+
| `< 0.1.0` | Prototype / Pre-Alpha | No |
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## Reporting a Vulnerability
|
|
20
|
+
|
|
21
|
+
We take vulnerabilities seriously. If you discover a security flaw, unauthorized privilege escalation, path traversal, injection vulnerability, or credential leak in AFYX Engineering Kit:
|
|
22
|
+
|
|
23
|
+
1. **Do not disclose publicly:** Do not open a public issue, discussion, or pull request on GitHub.
|
|
24
|
+
2. **Contact:** Report via GitHub Private Vulnerability Reporting at:
|
|
25
|
+
`https://github.com/a5zero7/afyx-engineering-kit/security/advisories/new`
|
|
26
|
+
or contact the repository maintainers through the official security contact mechanism designated on the repository homepage.
|
|
27
|
+
3. **Include details:**
|
|
28
|
+
- Affected component(s) and version.
|
|
29
|
+
- Operating system and shell environment.
|
|
30
|
+
- Minimal proof-of-concept (PoC) or reproduction steps.
|
|
31
|
+
- Potential impact and threat assessment.
|
|
32
|
+
4. **Response time:** The maintainers will acknowledge receipt within 48 hours and coordinate remediation before public disclosure.
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## Threat Model and Trust Boundaries
|
|
37
|
+
|
|
38
|
+
### 1. Model Context Protocol (MCP) Boundaries
|
|
39
|
+
|
|
40
|
+
- **Local-first execution:** AFYX Graph provides an optional stdio MCP server (`afyx_graph`) that executes locally on the operator's machine.
|
|
41
|
+
- **Untrusted MCP Servers:** AFYX components interact only with explicitly configured, authorized MCP servers. The toolkit enforces strict schema validation and will never execute foreign binaries or connect to unregistered network endpoints on behalf of unauthenticated third parties.
|
|
42
|
+
- **Prompt Injection Defense:** MCP tool outputs (graph exploration, file contents, symbols, call paths) return repository data that may originate from untrusted repositories. Agents consuming AFYX tool outputs must treat returned source code and docstrings as passive data, never as higher-priority system instructions.
|
|
43
|
+
|
|
44
|
+
### 2. Credential and Provider Authentication Boundaries
|
|
45
|
+
|
|
46
|
+
- **Zero credential custody:** AFYX does not broker, intercept, store, or transmit API keys, tokens, or credentials for AI coding hosts (Anthropic Claude Code, OpenAI Codex, Google Antigravity).
|
|
47
|
+
- **Independent provider state:** The installer and updater never mutate provider-private state, credentials, or session history. Provider configuration merges only AFYX-owned entries into host configuration files (`~/.claude.json`, `<workspace>/.mcp.json`, `mcp_config.json`, etc.) while strictly preserving unrelated entries.
|
|
48
|
+
- **Environment isolation:** AFYX does not read or expose host environment variables containing secrets or private tokens unless explicitly provided through designated configuration arguments.
|
|
49
|
+
|
|
50
|
+
### 3. File System & Path Traversal Security
|
|
51
|
+
|
|
52
|
+
- **Path containment:** All archive extraction routines, path sanitizers, and installer scripts validate that target paths remain strictly inside intended installation roots.
|
|
53
|
+
- **Reparse points and symlinks:** Archive extraction rejects directory traversal sequences (`..`), absolute paths, and Windows junction/reparse points or Unix symlinks that could escape designated directories.
|
|
54
|
+
- **Transactional modifications:** Configuration and skill file updates perform pre-modification backups and atomic writes (`atomicJson` / transactional swap) to prevent partial writes or corruption upon unexpected interruption.
|
|
55
|
+
|
|
56
|
+
### 4. Package & Archive Provenance
|
|
57
|
+
|
|
58
|
+
- **Precompiled archive verification:** All precompiled Graph binaries are validated against an authoritative `RELEASE-MANIFEST.json` and `SHA256SUMS`.
|
|
59
|
+
- **Integrity verification:** Checksums are computed and verified before extraction. Corrupted, truncated, or tampered archives trigger immediate fail-closed aborts without executing fallback compilations or executing untrusted code.
|
|
60
|
+
- **Deterministic source revision stamping:** Every official release candidate contains a validated `.afyx-source-revision` matching the exact Git commit from which it was built.
|
|
61
|
+
|
|
62
|
+
### 5. Package Lifecycle Scripts
|
|
63
|
+
|
|
64
|
+
- **No arbitrary postinstall execution:** The npm package does not execute invasive postinstall scripts that modify system PATH, install daemons, or mutate user files without explicit invocation.
|
|
65
|
+
- **Explicit user command:** Installation and updates execute only when the operator explicitly invokes `npx afyx-engineering-kit install` or related CLI commands.
|
|
66
|
+
|
|
67
|
+
---
|
|
68
|
+
|
|
69
|
+
## Operational Recommendations (Least Privilege)
|
|
70
|
+
|
|
71
|
+
1. **Run with least privilege:** Do not run AFYX installers, CLI commands, or MCP servers as `Administrator` (Windows) or `root` (Linux/macOS). User-level permissions are sufficient.
|
|
72
|
+
2. **Review repository sources:** When indexing third-party repositories with AFYX Graph, be aware that static analysis reads repository files. Ensure repositories from untrusted sources do not contain malicious executable files or exploit payloads.
|
|
73
|
+
3. **Review provider scopes:** Prefer workspace-scoped MCP configuration (`<workspace>/.mcp.json` or `.agents/mcp_config.json`) when working on isolated repositories to minimize the surface area of global host configuration.
|
|
74
|
+
4. **Keep runtimes updated:** Ensure Node.js is kept up to date with the latest LTS security releases.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Afyx
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,155 @@
|
|
|
1
|
+
# Afyx Context Engine
|
|
2
|
+
|
|
3
|
+
**Standalone local context optimization — Technical Alpha v0.1.0.**
|
|
4
|
+
|
|
5
|
+
Afyx Context Engine (ACE) is an Afyx-owned, standalone Node.js component for
|
|
6
|
+
conservative context reduction with byte-exact original recovery. It does not
|
|
7
|
+
require Afyx Graph, Forge, Engineering Expert, an external proxy, or the Kit installer.
|
|
8
|
+
|
|
9
|
+
## API
|
|
10
|
+
|
|
11
|
+
```js
|
|
12
|
+
import { AfyxContextEngine } from '@a5zero7/afyx-context';
|
|
13
|
+
|
|
14
|
+
const engine = new AfyxContextEngine({
|
|
15
|
+
stateDir: 'C:\\owned\\absolute\\ace-state',
|
|
16
|
+
ownerId: 'agent-owner',
|
|
17
|
+
sessionId: 'session-1',
|
|
18
|
+
// Optional bounded coordination controls (defaults: 5000 ms / 25 ms).
|
|
19
|
+
lockTimeoutMs: 5_000,
|
|
20
|
+
lockRetryMs: 25,
|
|
21
|
+
});
|
|
22
|
+
|
|
23
|
+
const result = engine.reduce({
|
|
24
|
+
budgetChars: 16_000,
|
|
25
|
+
segments: [
|
|
26
|
+
{ id: 'diagnostic', classification: 'diagnostic', content: 'exact failure text' },
|
|
27
|
+
{ id: 'output-1', content: 'repeated tool output' },
|
|
28
|
+
{ id: 'output-2', content: 'repeated tool output' },
|
|
29
|
+
],
|
|
30
|
+
});
|
|
31
|
+
|
|
32
|
+
const original = engine.retrieve(result.items[2].reference);
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
`diagnostic`, `security`, and `source-evidence` segments remain inline. ACE
|
|
36
|
+
only replaces normal content when the stable reference is smaller. If the
|
|
37
|
+
budget cannot safely represent the complete selection, ACE returns all
|
|
38
|
+
original content in `passthrough` mode.
|
|
39
|
+
|
|
40
|
+
The state directory must be absolute, empty or already bound to the same
|
|
41
|
+
owner, and not itself a symbolic link. References are bound to both owner and
|
|
42
|
+
session. A content hash is verified on every retrieval. Original blobs and
|
|
43
|
+
session metadata are committed through owned temporary files followed by
|
|
44
|
+
`fsync` and rename. A retry can adopt a complete orphan blob left by an
|
|
45
|
+
interruption; malformed metadata and corrupt existing blobs fail closed.
|
|
46
|
+
|
|
47
|
+
Every state read and mutation participates in one local, state-root-wide
|
|
48
|
+
exclusive lock. The deliberately coarse scope protects first initialization,
|
|
49
|
+
all sessions, and the shared content-addressed store across cooperating local
|
|
50
|
+
processes on Windows, Linux, and macOS. Lock acquisition is bounded; contention
|
|
51
|
+
reports `LOCK_TIMEOUT`. A lock is recovered only on the same host after the OS
|
|
52
|
+
proves that its recorded PID is absent. A present or unverifiable PID—including
|
|
53
|
+
a possible reused PID—never authorizes removal. Missing, foreign, or ambiguous
|
|
54
|
+
ownership fails closed with `LOCK_RECOVERY_UNSAFE`; lock age alone is never
|
|
55
|
+
recovery evidence.
|
|
56
|
+
|
|
57
|
+
After a verified process interruption, complete content temporaries are adopted
|
|
58
|
+
only after SHA-256 validation. Complete uncommitted session metadata is removed
|
|
59
|
+
without replacing the last committed session, so references cannot expose an
|
|
60
|
+
interrupted write. Unknown files and ambiguous coordination artifacts are not
|
|
61
|
+
deleted automatically.
|
|
62
|
+
|
|
63
|
+
## CLI
|
|
64
|
+
|
|
65
|
+
```text
|
|
66
|
+
afyx-context reduce --state <absolute-path> --owner <id> --session <id> --input <request.json|-> [--budget <chars>]
|
|
67
|
+
afyx-context get --state <absolute-path> --owner <id> --session <id> --reference <ace:v1:...>
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Build and test without third-party runtime dependencies:
|
|
71
|
+
|
|
72
|
+
```text
|
|
73
|
+
npm ci
|
|
74
|
+
npm run build:clean
|
|
75
|
+
npm test
|
|
76
|
+
npm run test:benchmark
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
## Installation and activation status
|
|
80
|
+
|
|
81
|
+
ACE is an explicit, optional Kit component (`afyx-context`), absent from
|
|
82
|
+
`minimal`, `recommended` and `full`. The runtime can operate completely alone,
|
|
83
|
+
and a supported provider may discover its on-demand companion skill after an
|
|
84
|
+
explicit installation. A healthy installed component being eligible for a task
|
|
85
|
+
is **not** the same as ACE executing or reducing output.
|
|
86
|
+
|
|
87
|
+
Explicit `AFYX_CONTEXT_OPT_IN=0` and user/provider OFF settings must be honored.
|
|
88
|
+
Automatic Graph MCP interception is still a separate, default-OFF path; no
|
|
89
|
+
universal net-token or cost savings are claimed. See the
|
|
90
|
+
[Kit Component Guide](../docs/COMPONENTS.md#afyx-context-engine) and
|
|
91
|
+
[installation guide](../docs/INSTALLATION.md#ace-standalone-versus-kit-managed).
|
|
92
|
+
|
|
93
|
+
## Optional integration
|
|
94
|
+
|
|
95
|
+
`contracts/integration-v1.schema.json` defines `ace.integration/v1` for Graph,
|
|
96
|
+
Engineering Expert, Forge, and Kit consumers. `createOptionalIntegrationAdapter`
|
|
97
|
+
catches an unavailable/failed ACE and returns original content, so the consumer
|
|
98
|
+
remains independently functional. The Kit can install, update, verify, repair,
|
|
99
|
+
and uninstall ACE as a managed explicit component, but ACE is absent from all
|
|
100
|
+
implicit presets and installation never enables a consumer integration.
|
|
101
|
+
|
|
102
|
+
AFYX-293 adds the first real consumer as a separate, default-OFF bridge. It does
|
|
103
|
+
not alter Graph's CLI, API, MCP tools, or default responses:
|
|
104
|
+
|
|
105
|
+
```js
|
|
106
|
+
import { createGraphAceConsumer, deriveGraphAceIdentity } from '@a5zero7/afyx-context';
|
|
107
|
+
|
|
108
|
+
const sourceIdentity = 'git:reviewed-source-sha';
|
|
109
|
+
const identity = deriveGraphAceIdentity({
|
|
110
|
+
projectRoot,
|
|
111
|
+
sourceIdentity,
|
|
112
|
+
consumerId: 'local-codex-session',
|
|
113
|
+
});
|
|
114
|
+
const consumer = createGraphAceConsumer({
|
|
115
|
+
enabled: true,
|
|
116
|
+
stateDir: absoluteOwnedAceState,
|
|
117
|
+
...identity,
|
|
118
|
+
timeoutMs: 5_000,
|
|
119
|
+
});
|
|
120
|
+
const output = await consumer.execute({
|
|
121
|
+
executeGraph: (toolName, args) => graphToolHandler.execute(toolName, args),
|
|
122
|
+
toolName: 'afyx_graph_search',
|
|
123
|
+
args: { query: 'target symbol' },
|
|
124
|
+
projectRoot,
|
|
125
|
+
sourceIdentity,
|
|
126
|
+
});
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
The bridge runs Graph first and retains its validated result as the authoritative
|
|
130
|
+
fallback. ACE runs only after explicit enablement in an owned local Node child
|
|
131
|
+
process with a distinct OS PID. Timeout terminates that child and waits for its
|
|
132
|
+
exit before returning the exact Graph result; an unconfirmed termination fails
|
|
133
|
+
closed instead of reporting completion while mutation may continue. Disabled,
|
|
134
|
+
unavailable, malformed, or corrupt ACE also returns the exact Graph result.
|
|
135
|
+
`explore`, `files`, `node`, and diagnostic output is protected and bypasses the
|
|
136
|
+
ACE worker because it must remain inline byte-for-byte. References are
|
|
137
|
+
recoverable only through the same
|
|
138
|
+
owner/session; invalid or corrupt recovery fails closed. Callers should use
|
|
139
|
+
`deriveGraphAceIdentity` to bind an owner to the canonical project/consumer and a
|
|
140
|
+
session to the exact source identity.
|
|
141
|
+
|
|
142
|
+
Malformed or unavailable optional integration requests return a bounded
|
|
143
|
+
fallback. `originalInput` retains the supplied input, and `originalComplete`
|
|
144
|
+
states whether `renderedContext` contains its complete render.
|
|
145
|
+
|
|
146
|
+
The v1 boundary accepts at most 1,024 segments, 1 MiB content and 64 KiB
|
|
147
|
+
provenance per segment, 8 MiB aggregate request content, 512-byte segment and
|
|
148
|
+
owner/session identities, and 10 MiB CLI input. State/session metadata are
|
|
149
|
+
bounded at 64 KiB/16 MiB; a stored blob is bounded at 1 MiB, a session at
|
|
150
|
+
100,000 unique contents, and provenance at 256 observations per digest.
|
|
151
|
+
|
|
152
|
+
Coordination is local and exclusive, not distributed. A process-liveness check
|
|
153
|
+
that is unavailable, cross-host, or inconclusive requires operator inspection
|
|
154
|
+
instead of automatic lock removal. Stored content remains local plaintext, and
|
|
155
|
+
the caller owns filesystem access control and retention policy.
|