afyx-engineering-kit 0.0.0-stage → 0.1.0-alpha.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (208) hide show
  1. package/.afyx-source-revision +1 -0
  2. package/LICENSE +21 -0
  3. package/README.md +377 -2
  4. package/SECURITY.md +74 -0
  5. package/afyx-context/LICENSE +21 -0
  6. package/afyx-context/README.md +155 -0
  7. package/afyx-context/afyx-context.json +30 -0
  8. package/afyx-context/contracts/integration-v1.schema.json +34 -0
  9. package/afyx-context/package-lock.json +53 -0
  10. package/afyx-context/package.json +34 -0
  11. package/afyx-context/scripts/benchmark.mjs +39 -0
  12. package/afyx-context/scripts/build.mjs +15 -0
  13. package/afyx-context/scripts/comparative-benchmark.mjs +342 -0
  14. package/afyx-context/scripts/comparative-worker.mjs +74 -0
  15. package/afyx-context/scripts/graph-integration-e2e.mjs +188 -0
  16. package/afyx-context/scripts/integrated-dogfood.mjs +309 -0
  17. package/afyx-context/src/budget.js +166 -0
  18. package/afyx-context/src/cli.js +110 -0
  19. package/afyx-context/src/coordination.js +343 -0
  20. package/afyx-context/src/engine.js +198 -0
  21. package/afyx-context/src/errors.js +14 -0
  22. package/afyx-context/src/graph-integration-worker.js +70 -0
  23. package/afyx-context/src/graph-integration.js +373 -0
  24. package/afyx-context/src/graph-mcp-bridge.js +103 -0
  25. package/afyx-context/src/index.js +25 -0
  26. package/afyx-context/src/integrations.js +87 -0
  27. package/afyx-context/src/memory.js +255 -0
  28. package/afyx-context/src/storage.js +364 -0
  29. package/afyx-context/test-fixtures/coordination-worker.mjs +52 -0
  30. package/afyx-context/test-fixtures/graph-consumer-repo/addons/sale_extension/__init__.py +1 -0
  31. package/afyx-context/test-fixtures/graph-consumer-repo/addons/sale_extension/__manifest__.py +4 -0
  32. package/afyx-context/test-fixtures/graph-consumer-repo/addons/sale_extension/models/__init__.py +1 -0
  33. package/afyx-context/test-fixtures/graph-consumer-repo/addons/sale_extension/models/sale_order.py +5 -0
  34. package/afyx-context/test-fixtures/integrated-dogfood-repo/addons/integrated_sales/__init__.py +1 -0
  35. package/afyx-context/test-fixtures/integrated-dogfood-repo/addons/integrated_sales/__manifest__.py +10 -0
  36. package/afyx-context/test-fixtures/integrated-dogfood-repo/addons/integrated_sales/models/__init__.py +2 -0
  37. package/afyx-context/test-fixtures/integrated-dogfood-repo/addons/integrated_sales/models/sale_order.py +20 -0
  38. package/afyx-context/test-fixtures/integrated-dogfood-repo/addons/integrated_sales/models/sale_order_audit.py +11 -0
  39. package/afyx-context/test-fixtures/integrated-dogfood-repo/addons/integrated_sales/security/ir.model.access.csv +2 -0
  40. package/afyx-context/test-fixtures/integrated-dogfood-repo/addons/integrated_sales/views/sale_order_views.xml +14 -0
  41. package/afyx-forge/LICENSE +55 -0
  42. package/afyx-forge/README.md +126 -0
  43. package/afyx-forge/afyx-forge.json +28 -0
  44. package/afyx-forge/bin/afyx-forge +4 -0
  45. package/afyx-forge/bin/afyx-forge.cmd +3 -0
  46. package/afyx-forge/bin/afyx-forge.js +16 -0
  47. package/afyx-forge/contracts/forge-plan-v1.schema.json +172 -0
  48. package/afyx-forge/package.json +26 -0
  49. package/afyx-forge/src/classifier.js +190 -0
  50. package/afyx-forge/src/cli.js +111 -0
  51. package/afyx-forge/src/doctor.js +105 -0
  52. package/afyx-forge/src/guidance.js +120 -0
  53. package/afyx-forge/src/index.js +273 -0
  54. package/afyx-forge/src/planning.js +107 -0
  55. package/afyx-forge/src/policy.js +109 -0
  56. package/afyx-forge/src/workflow-refiner.js +151 -0
  57. package/afyx-graph/afyx-graph.json +20 -0
  58. package/afyx-graph/engine/LICENSE +21 -0
  59. package/afyx-graph/engine/README.md +104 -0
  60. package/afyx-graph/engine/release/RELEASE-MANIFEST.json +21 -0
  61. package/afyx-graph/engine/release/SHA256SUMS +2 -0
  62. package/afyx-graph/engine/release/afyx-graph-linux-x64.tar.gz +0 -0
  63. package/afyx-graph/engine/release/afyx-graph-win32-x64.zip +0 -0
  64. package/afyx-graph/engine/scripts/distribution-contract.mjs +212 -0
  65. package/afyx-graph/engine/scripts/distribution-product.json +33 -0
  66. package/bin/afyx-engineering-kit.mjs +61 -0
  67. package/install.ps1 +1053 -0
  68. package/install.sh +617 -0
  69. package/package.json +66 -4
  70. package/scripts/afyx-capability-orchestrator.mjs +752 -0
  71. package/scripts/afyx-claude-integration.mjs +547 -0
  72. package/scripts/afyx-context-artifact.mjs +105 -0
  73. package/scripts/afyx-credential-broker.mjs +75 -0
  74. package/scripts/afyx-doctor.ps1 +152 -0
  75. package/scripts/afyx-doctor.sh +146 -0
  76. package/scripts/afyx-forge-artifact.mjs +183 -0
  77. package/scripts/afyx-global-routing-policy.md +12 -0
  78. package/scripts/afyx-global-routing.mjs +168 -0
  79. package/scripts/afyx-graph-artifact.mjs +178 -0
  80. package/scripts/afyx-host-adapters.mjs +543 -0
  81. package/scripts/afyx-host-bridge-lifecycle.mjs +174 -0
  82. package/scripts/afyx-host-bridge.mjs +288 -0
  83. package/scripts/afyx-integration-contracts.mjs +825 -0
  84. package/scripts/afyx-mcp-integration.mjs +528 -0
  85. package/scripts/afyx-modular-integration.mjs +361 -0
  86. package/scripts/afyx-modular-runtime.mjs +451 -0
  87. package/scripts/afyx-native-skill-host.mjs +124 -0
  88. package/scripts/afyx-npm-installer.mjs +486 -0
  89. package/scripts/afyx-project.ps1 +205 -0
  90. package/scripts/afyx-project.sh +207 -0
  91. package/scripts/afyx-provider-backup.mjs +1206 -0
  92. package/scripts/afyx-provider-integration.mjs +724 -0
  93. package/scripts/afyx-provider-inventory.mjs +147 -0
  94. package/scripts/afyx-security-auditor.mjs +224 -0
  95. package/scripts/afyx-skill-engineering.mjs +354 -0
  96. package/scripts/afyx-tool-family-routing.mjs +64 -0
  97. package/scripts/afyx-universal-runtime.mjs +530 -0
  98. package/scripts/alpha_acceptance_preflight.py +240 -0
  99. package/scripts/benchmark-graph-memory.mjs +96 -0
  100. package/scripts/benchmark_capability_orchestrator.mjs +64 -0
  101. package/scripts/build-windows-installer.ps1 +259 -0
  102. package/scripts/build_forge_synthetic_image.py +328 -0
  103. package/scripts/check-reference-staleness.py +71 -0
  104. package/scripts/components.json +254 -0
  105. package/scripts/contracts/afyx-capability-request-v1.schema.json +189 -0
  106. package/scripts/contracts/afyx-capability-result-v1.schema.json +32 -0
  107. package/scripts/dogfood_engineering_comparison.mjs +303 -0
  108. package/scripts/engineering-assurance.json +28 -0
  109. package/scripts/install-afyx-context.ps1 +142 -0
  110. package/scripts/install-afyx-context.sh +126 -0
  111. package/scripts/install-afyx-forge.ps1 +265 -0
  112. package/scripts/install-afyx-forge.sh +273 -0
  113. package/scripts/install-afyx-graph.ps1 +571 -0
  114. package/scripts/install-afyx-graph.sh +438 -0
  115. package/scripts/install-codex-usage-tracker.ps1 +172 -0
  116. package/scripts/lib/AfyxComponents.psm1 +399 -0
  117. package/scripts/lib/AfyxSkillLifecycle.psm1 +289 -0
  118. package/scripts/lib/AfyxTerminal.psm1 +838 -0
  119. package/scripts/lib/afyx-components.sh +256 -0
  120. package/scripts/lib/afyx-skill-lifecycle.sh +271 -0
  121. package/scripts/link-global-dev.ps1 +193 -0
  122. package/scripts/link-global-dev.sh +130 -0
  123. package/scripts/phase8-paired-evidence.mjs +195 -0
  124. package/scripts/phase8-representative-workload.mjs +771 -0
  125. package/scripts/phase8-session-recorder.mjs +157 -0
  126. package/scripts/phase8_event_ledger.py +248 -0
  127. package/scripts/phase8_evidence_discovery.py +189 -0
  128. package/scripts/prepare-g6-package.mjs +349 -0
  129. package/scripts/resolve-git-release-artifacts.mjs +321 -0
  130. package/scripts/stage-npm-release.mjs +94 -0
  131. package/scripts/validate-afyx-graph.py +203 -0
  132. package/scripts/validate-components.py +194 -0
  133. package/scripts/validate-engineering-assurance.py +281 -0
  134. package/scripts/verify-graph-archive.mjs +64 -0
  135. package/skills/afyx-context/SKILL.md +26 -0
  136. package/skills/afyx-engineering-expert/README.md +42 -0
  137. package/skills/afyx-engineering-expert/SKILL.md +70 -0
  138. package/skills/afyx-engineering-expert/assets/result-template.md +15 -0
  139. package/skills/afyx-engineering-expert/references/ai-ml-engineer.md +17 -0
  140. package/skills/afyx-engineering-expert/references/business-analyst.md +17 -0
  141. package/skills/afyx-engineering-expert/references/clean-code-engineer.md +26 -0
  142. package/skills/afyx-engineering-expert/references/code-reviewer.md +24 -0
  143. package/skills/afyx-engineering-expert/references/cybersecurity-devsecops.md +17 -0
  144. package/skills/afyx-engineering-expert/references/data-analyst-bi.md +24 -0
  145. package/skills/afyx-engineering-expert/references/data-engineer.md +24 -0
  146. package/skills/afyx-engineering-expert/references/database-administrator.md +17 -0
  147. package/skills/afyx-engineering-expert/references/debugging-specialist.md +24 -0
  148. package/skills/afyx-engineering-expert/references/embedded-iot-engineer.md +24 -0
  149. package/skills/afyx-engineering-expert/references/erp-technical-specialist.md +17 -0
  150. package/skills/afyx-engineering-expert/references/hardware-diagnostics-auditor.md +24 -0
  151. package/skills/afyx-engineering-expert/references/hardware-electronics-engineer.md +24 -0
  152. package/skills/afyx-engineering-expert/references/integration-engineer.md +24 -0
  153. package/skills/afyx-engineering-expert/references/legacy-modernization-engineer.md +24 -0
  154. package/skills/afyx-engineering-expert/references/llmops-prompt-engineer.md +24 -0
  155. package/skills/afyx-engineering-expert/references/network-engineer.md +24 -0
  156. package/skills/afyx-engineering-expert/references/performance-benchmark-engineer.md +24 -0
  157. package/skills/afyx-engineering-expert/references/platform-engineer.md +24 -0
  158. package/skills/afyx-engineering-expert/references/product-manager.md +17 -0
  159. package/skills/afyx-engineering-expert/references/qa-engineer.md +17 -0
  160. package/skills/afyx-engineering-expert/references/site-reliability-engineer.md +17 -0
  161. package/skills/afyx-engineering-expert/references/software-engineer.md +17 -0
  162. package/skills/afyx-engineering-expert/references/solutions-architect.md +17 -0
  163. package/skills/afyx-engineering-expert/references/specialists-index.md +33 -0
  164. package/skills/afyx-engineering-expert/references/subject-matter-expert.md +17 -0
  165. package/skills/afyx-engineering-expert/references/system-analyst.md +17 -0
  166. package/skills/afyx-engineering-expert/references/technical-project-manager.md +24 -0
  167. package/skills/afyx-engineering-expert/references/technical-writer.md +24 -0
  168. package/skills/afyx-engineering-expert/references/ui-ux-designer.md +17 -0
  169. package/skills/afyx-engineering-expert/workflows/ai-data-erp.md +20 -0
  170. package/skills/afyx-engineering-expert/workflows/debugging.md +10 -0
  171. package/skills/afyx-engineering-expert/workflows/discovery-design.md +11 -0
  172. package/skills/afyx-engineering-expert/workflows/implementation.md +12 -0
  173. package/skills/afyx-engineering-expert/workflows/incident-reliability.md +12 -0
  174. package/skills/afyx-engineering-expert/workflows/review-audit.md +13 -0
  175. package/skills/afyx-forge/SKILL.md +43 -0
  176. package/skills/afyx-forge/references/adaptive-policy.md +19 -0
  177. package/skills/efficient-coding/SKILL.md +33 -0
  178. package/skills/efficient-coding/references/investigation.md +27 -0
  179. package/skills/efficient-coding/references/token-efficiency.md +25 -0
  180. package/skills/efficient-coding/references/tool-routing.md +13 -0
  181. package/skills/odoo-engineering/SKILL.md +33 -0
  182. package/skills/odoo-engineering/references/common.md +9 -0
  183. package/skills/odoo-engineering/references/odoo-10.md +32 -0
  184. package/skills/odoo-engineering/references/odoo-11.md +26 -0
  185. package/skills/odoo-engineering/references/odoo-12.md +31 -0
  186. package/skills/odoo-engineering/references/odoo-13.md +27 -0
  187. package/skills/odoo-engineering/references/odoo-14.md +31 -0
  188. package/skills/odoo-engineering/references/odoo-15.md +34 -0
  189. package/skills/odoo-engineering/references/odoo-16.md +37 -0
  190. package/skills/odoo-engineering/references/odoo-17.md +37 -0
  191. package/skills/odoo-engineering/references/odoo-18.md +48 -0
  192. package/skills/odoo-engineering/references/odoo-19.md +43 -0
  193. package/skills/odoo-engineering/references/odoo-20.md +39 -0
  194. package/skills/odoo-engineering/references/reference-schema.md +16 -0
  195. package/skills/odoo-engineering/references/version-detection.md +13 -0
  196. package/tools/codex-usage/CodexUsage.psm1 +496 -0
  197. package/tools/codex-usage/codex-usage-doctor.ps1 +150 -0
  198. package/tools/codex-usage/codex-usage-pricing.json +25 -0
  199. package/tools/codex-usage/codex-usage-stop.ps1 +167 -0
  200. package/tools/codex-usage/codex-usage-watch.ps1 +250 -0
  201. package/tools/codex-usage/vscode-user-task.json +31 -0
  202. package/tools/windows-setup/SetupBootstrapper.cs +258 -0
  203. package/uninstall.ps1 +189 -0
  204. package/uninstall.sh +167 -0
  205. package/update.ps1 +95 -0
  206. package/update.sh +67 -0
  207. package/verify.ps1 +411 -0
  208. package/verify.sh +265 -0
@@ -0,0 +1,104 @@
1
+ # Afyx Graph Engine
2
+
3
+ **Local repository intelligence — Technical Alpha source.**
4
+
5
+ This directory contains the standalone Afyx Graph engine. It indexes supported
6
+ source structures and relationships, provides symbol discovery, exploration,
7
+ impact/affected-test analysis, freshness and coverage reporting, CLI/MCP
8
+ interfaces, and a bundled local viewer. Its evidence remains structural and
9
+ bounded by indexed content, language routes and index freshness.
10
+
11
+ Build and test from this directory with `npm ci`, `npm run build:clean`, and
12
+ `npm test`. The package metadata version `1.0.0` is **not** a Stable v1 release
13
+ claim; rely on the repository release gate and artifact identity instead.
14
+
15
+ For public capability, lifecycle, command, limitation, and troubleshooting
16
+ guidance, see the repository [Component Guide](../../docs/COMPONENTS.md#afyx-graph)
17
+ and [Installation Guide](../../docs/INSTALLATION.md#graph-installation-and-project-initialization).
18
+
19
+ Afyx Graph is static structural evidence, not runtime proof. Check index health
20
+ and coverage before using a result, verify source when precision matters, and run
21
+ the affected behavioral tests before accepting a code change.
22
+
23
+ Regression gates, all local and deterministic (no model calls):
24
+
25
+ - `npm run test:semantic` compares the built engine with the frozen structural
26
+ snapshot in `tests/semantic-baseline.json` (see `tests/semantic-baseline.meta.json`
27
+ for its provenance). Never refreeze it from this implementation.
28
+ - `npm run test:smoke` drives the built CLI and the MCP server end to end.
29
+ - `npm test` runs the unit suites and first refuses stale build artifacts
30
+ (`scripts/check-dist-clean.mjs`).
31
+
32
+ Project state lives in `.afyx-graph/` by default (database
33
+ `afyx-graph.db`). `AFYX_GRAPH_DIR` remains the backward-compatible override
34
+ for a single directory name inside the project root.
35
+
36
+ For a read-only corpus, set `AFYX_GRAPH_STATE_DIR` to a dedicated absolute
37
+ directory outside the corpus before every CLI or MCP invocation:
38
+
39
+ ```powershell
40
+ $env:AFYX_GRAPH_STATE_DIR = 'D:\AfyxState\my-project'
41
+ afyx-graph init 'D:\Source\my-project' --yes
42
+ afyx-graph status 'D:\Source\my-project'
43
+ ```
44
+
45
+ The first initialization writes `project.json` into that state directory and
46
+ binds it to the corpus's canonical path. CLI, MCP, daemon, watchdog, freshness,
47
+ locks, logs, database/WAL, saved trails, and daemon discovery then use the same
48
+ external location. The directory must be absolute, outside and non-overlapping
49
+ with the corpus, writable, free of path aliases/reparse points, and either empty
50
+ or already bound to that exact corpus. Invalid, unavailable, unbound non-empty,
51
+ or cross-project state fails closed; it never falls back to `.afyx-graph/`. Use
52
+ one state directory and one MCP process configuration per corpus. External-state
53
+ mode never auto-writes `afyx-graph.json` into the corpus.
54
+
55
+ An optional, committed `afyx-graph.json` at the project root maps custom file
56
+ extensions to supported languages.
57
+ The shipped product requires external Node.js 22.5.0 or newer on `PATH`; release
58
+ archives do not bundle Node or a `node_modules` dependency tree.
59
+ `afyx-graph status` reports index freshness (`MISSING`, `FRESH`, `STALE`,
60
+ `INVALID`, `UNKNOWN`) from `freshness.json` in the effective state, which the engine
61
+ rewrites after every successful index or sync. Afyx Graph makes no outbound network
62
+ requests and collects no telemetry.
63
+
64
+ ## Latest verified CI checkpoint
65
+
66
+ The 2026-11-05 `dev` merge
67
+ [`e332230`](https://github.com/a5zero7/afyx-engineering-kit/commit/e332230a2c0ba162b447af1359cf591057ce26b6)
68
+ resolved a Windows Vitest `beforeEach` hook timeout in the Git/SQLite-heavy
69
+ `sync.test.ts` fixture. The hook now has an explicit 30-second budget and
70
+ Windows temporary-directory removal retries; the global CI `hookTimeout`
71
+ permits 30 seconds while local default remains 10 seconds. This preserves the
72
+ tests rather than skipping them. The [post-merge Graph Build](https://github.com/a5zero7/afyx-engineering-kit/actions/runs/41988333699)
73
+ passed Windows, Linux, and macOS; its report includes 5,836 unit tests and
74
+ 21/21 CLI/MCP smoke checks. This is CI evidence for this commit, **not**
75
+ representative installed-host acceptance or a Stable v1 certification.
76
+
77
+ ## File catalog coverage
78
+
79
+ The persisted file catalog reports one explicit depth per indexed file:
80
+
81
+ - `metadata`: path, content hash, language, size, and timestamps only;
82
+ - `content`: reserved for a future bounded searchable-content contract;
83
+ - `structural`: the native structural extraction contract ran, including valid
84
+ files that contain no declarations and therefore produce zero symbols.
85
+
86
+ Generic Markdown (`.md`, `.markdown`) and JSON (`.json`) are metadata-indexed.
87
+ Their prose and values do not enter symbol search, FTS, nodes, or edges. Shopify
88
+ `templates/**/*.json` and `sections/**/*.json` retain their existing Liquid
89
+ structural route. PowerShell and shell files retain bounded direct-source
90
+ inspection but are not part of native structural extraction in this change.
91
+
92
+ `status`, MCP status, Inventory coverage, and Files metadata distinguish these
93
+ depths. Discovery accounting keeps ignored paths unenumerated; `ignored` remains
94
+ unknown rather than leaking excluded names. Existing `.gitignore`, Git exclude,
95
+ project exclude/include, path-safety, and generated-file rules apply before a
96
+ file may enter the catalog.
97
+
98
+ Install and release Afyx Graph only through the kit-level scripts and workflows:
99
+ `scripts/install-afyx-graph.ps1`, `scripts/install-afyx-graph.sh`,
100
+ `.github/workflows/graph-build.yml`, and `.github/workflows/graph-release.yml`.
101
+
102
+ Afyx Graph is licensed under the MIT License in `LICENSE`. Historical
103
+ implementation and attribution evidence is retained in the repository's Phase
104
+ 5 documentation and Git history; it is not part of the current release payload.
@@ -0,0 +1,21 @@
1
+ {
2
+ "schema": 1,
3
+ "product": "Afyx Graph",
4
+ "product_version": "1.0.0",
5
+ "release_tag": "afyx-graph-v1.0.0",
6
+ "source_revision": "838b5b0bf1d3413579281cbd6c5250ec767ba79d",
7
+ "integrity_claim": "sha256",
8
+ "publisher_authenticity": "requires-independent-attestation",
9
+ "artifacts": [
10
+ {
11
+ "file": "afyx-graph-linux-x64.tar.gz",
12
+ "target": "linux-x64",
13
+ "sha256": "edc4c47f1ed3ca3778117999c27446eebf72b5eccfb8c4ce7f989f27a8d8a9e7"
14
+ },
15
+ {
16
+ "file": "afyx-graph-win32-x64.zip",
17
+ "target": "win32-x64",
18
+ "sha256": "956de055032e821b6af734f8644dac6921da87716567244b3669d8c218590883"
19
+ }
20
+ ]
21
+ }
@@ -0,0 +1,2 @@
1
+ edc4c47f1ed3ca3778117999c27446eebf72b5eccfb8c4ce7f989f27a8d8a9e7 afyx-graph-linux-x64.tar.gz
2
+ 956de055032e821b6af734f8644dac6921da87716567244b3669d8c218590883 afyx-graph-win32-x64.zip
@@ -0,0 +1,212 @@
1
+ #!/usr/bin/env node
2
+ import { createHash } from 'node:crypto';
3
+ import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
4
+ import { dirname, join, relative, resolve, sep } from 'node:path';
5
+ import { fileURLToPath } from 'node:url';
6
+
7
+ const SCRIPT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
8
+ const PRODUCT_FILE = join(SCRIPT_ROOT, 'scripts', 'distribution-product.json');
9
+ export const DISTRIBUTION_PRODUCT = Object.freeze(
10
+ JSON.parse(readFileSync(PRODUCT_FILE, 'utf8')),
11
+ );
12
+
13
+ export function distributionTargets() {
14
+ return [...DISTRIBUTION_PRODUCT.targets];
15
+ }
16
+
17
+ export function artifactPlan(target) {
18
+ if (!DISTRIBUTION_PRODUCT.targets.includes(target)) {
19
+ throw new DistributionError(`unsupported target: ${target}`);
20
+ }
21
+ const separator = target.indexOf('-');
22
+ const family = target.slice(0, separator);
23
+ const arch = target.slice(separator + 1);
24
+ const bundleName = `${DISTRIBUTION_PRODUCT.bundlePrefix}-${target}`;
25
+ return {
26
+ target,
27
+ family,
28
+ arch,
29
+ bundleName,
30
+ archiveName: `${bundleName}.${family === 'win32' ? 'zip' : 'tar.gz'}`,
31
+ runtime: { ...DISTRIBUTION_PRODUCT.runtime },
32
+ launcherPath: `bin/${family === 'win32' ? `${DISTRIBUTION_PRODUCT.cli}.cmd` : DISTRIBUTION_PRODUCT.cli}`,
33
+ legalFiles: DISTRIBUTION_PRODUCT.legalFiles.map((entry) => ({ ...entry })),
34
+ };
35
+ }
36
+
37
+ export class DistributionError extends Error {}
38
+
39
+ function requireFile(path, label = path) {
40
+ if (!existsSync(path) || !statSync(path).isFile()) throw new DistributionError(`missing ${label}`);
41
+ return path;
42
+ }
43
+
44
+ function localAssetPaths(html) {
45
+ return [...html.matchAll(/\s(?:src|href)="([^"]+)"/g)]
46
+ .map((match) => match[1])
47
+ .filter((url) => !/^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(url) && !url.startsWith('#'))
48
+ .map((url) => url.replace(/^\.\//, '').replace(/[?#].*$/, ''))
49
+ .filter(Boolean);
50
+ }
51
+
52
+ export function verifyEngineDistribution(root = SCRIPT_ROOT) {
53
+ const dist = join(resolve(root), 'dist');
54
+ const viewer = join(dist, 'viewer');
55
+ const index = requireFile(join(viewer, 'index.html'), 'dist/viewer/index.html');
56
+ const html = readFileSync(index, 'utf8');
57
+ if (html.length < 200 || !/<div id="app">/.test(html)) {
58
+ throw new DistributionError(`dist/viewer/index.html is not a complete viewer (${html.length} bytes)`);
59
+ }
60
+ const assets = localAssetPaths(html);
61
+ if (assets.length === 0) throw new DistributionError('dist/viewer/index.html references no bundled assets');
62
+ for (const asset of assets) requireFile(join(viewer, ...asset.split('/')), `dist/viewer/${asset}`);
63
+ for (const file of DISTRIBUTION_PRODUCT.engineSentinels) {
64
+ requireFile(join(dist, ...file.split('/')), `dist/${file}`);
65
+ }
66
+ const shippedGrammars = walkFiles(dist).filter((file) => file.endsWith('.wasm'));
67
+ if (shippedGrammars.length > 0) {
68
+ throw new DistributionError('dist must not contain grammar WASM');
69
+ }
70
+
71
+ const engineMaps = walkFiles(dist).filter((file) => file.endsWith('.js.map') && !file.includes(`${sep}viewer${sep}`));
72
+ if (engineMaps.length === 0) throw new DistributionError('engine JavaScript source maps are missing');
73
+ const viewerMaps = walkFiles(viewer).filter((file) => file.endsWith('.map'));
74
+ if (viewerMaps.length > 0) throw new DistributionError('viewer source maps must remain disabled');
75
+ return { assets: assets.length, engineSourceMaps: engineMaps.length };
76
+ }
77
+
78
+ export function verifyBundle(root, target) {
79
+ const bundle = resolve(root);
80
+ const plan = artifactPlan(target);
81
+ const windows = plan.family === 'win32';
82
+ const lib = join(bundle, 'lib');
83
+ const engine = verifyEngineDistribution(lib);
84
+ const manifest = JSON.parse(readFileSync(requireFile(join(lib, 'package.json'), 'lib/package.json'), 'utf8'));
85
+ if (manifest.name !== DISTRIBUTION_PRODUCT.packageName ||
86
+ manifest.bin?.[DISTRIBUTION_PRODUCT.cli] !== `./dist/bin/${DISTRIBUTION_PRODUCT.cli}.js`) {
87
+ throw new DistributionError('lib/package.json has the wrong package identity or CLI entrypoint');
88
+ }
89
+ const metadata = JSON.parse(readFileSync(requireFile(join(bundle, 'metadata.json'), 'metadata.json'), 'utf8'));
90
+ if (metadata.product_name !== DISTRIBUTION_PRODUCT.productName || metadata.cli !== DISTRIBUTION_PRODUCT.cli) {
91
+ throw new DistributionError('metadata.json has the wrong operational identity');
92
+ }
93
+ if (metadata.release_channel !== DISTRIBUTION_PRODUCT.releaseChannel) {
94
+ throw new DistributionError('metadata.json has the wrong release channel');
95
+ }
96
+ if (metadata.artifact_identity_schema !== undefined) {
97
+ if (metadata.artifact_identity_schema !== 1 || metadata.artifact_target !== target) {
98
+ throw new DistributionError('metadata.json has an invalid artifact identity schema or target');
99
+ }
100
+ if (!/^[0-9a-f]{7,64}$|^UNKNOWN$/i.test(String(metadata.source_revision || '')) ||
101
+ !String(metadata.build_identity || '').trim() ||
102
+ !Number.isSafeInteger(metadata.extraction_version)) {
103
+ throw new DistributionError('metadata.json has incomplete revision/build/extraction identity');
104
+ }
105
+ }
106
+ for (const legal of plan.legalFiles) {
107
+ const file = requireFile(join(bundle, ...legal.bundlePath.split('/')), legal.bundlePath);
108
+ if (statSync(file).size === 0) throw new DistributionError(`${legal.bundlePath} is empty`);
109
+ }
110
+ for (const bundledRuntime of ['node', 'node.exe']) {
111
+ if (existsSync(join(bundle, bundledRuntime))) {
112
+ throw new DistributionError(`bundle must not contain a bundled Node runtime: ${bundledRuntime}`);
113
+ }
114
+ }
115
+ const launcher = requireFile(
116
+ join(bundle, ...plan.launcherPath.split('/')),
117
+ plan.launcherPath,
118
+ );
119
+ const launcherText = readFileSync(launcher, 'utf8');
120
+ if (!launcherText.includes('lib') || !launcherText.includes('dist') || !launcherText.includes('afyx-graph.js')) {
121
+ throw new DistributionError('launcher does not target lib/dist/bin/afyx-graph.js');
122
+ }
123
+ if (!launcherText.includes('Node.js was not found on PATH') || !launcherText.includes('node ')) {
124
+ throw new DistributionError('launcher does not enforce the external Node.js runtime contract');
125
+ }
126
+ const parserRuntimeFiles = walkFiles(lib).filter((file) => {
127
+ const shippedPath = relative(lib, file).split(sep).join('/').toLowerCase();
128
+ return shippedPath.includes('web-tree-sitter') ||
129
+ shippedPath.includes('tree-sitter-wasms') ||
130
+ shippedPath.endsWith('/tree-sitter.wasm');
131
+ });
132
+ if (parserRuntimeFiles.length > 0) {
133
+ throw new DistributionError('bundle must not contain a third-party parser runtime');
134
+ }
135
+ const kernelFiles = walkFiles(lib).filter((file) => {
136
+ const shippedPath = relative(lib, file).split(sep).join('/').toLowerCase();
137
+ return shippedPath.includes('afyx-graph-kernel') ||
138
+ shippedPath.startsWith('kernel/') ||
139
+ shippedPath.endsWith('/cargo.toml') ||
140
+ shippedPath.endsWith('/cargo.lock');
141
+ });
142
+ if (kernelFiles.length > 0) {
143
+ throw new DistributionError('bundle must not contain native kernel source or runtime');
144
+ }
145
+ const shippedDependencies = walkFiles(bundle).filter((file) =>
146
+ relative(bundle, file).split(sep).some((part) => part === 'node_modules')
147
+ );
148
+ if (shippedDependencies.length > 0) {
149
+ throw new DistributionError('bundle must not contain node_modules');
150
+ }
151
+ for (const forbidden of ['src', '__tests__', 'ui']) {
152
+ if (existsSync(join(lib, forbidden))) throw new DistributionError(`development-only lib/${forbidden} is packaged`);
153
+ }
154
+ return { ...engine, legalFiles: plan.legalFiles.length, target };
155
+ }
156
+
157
+ function walkFiles(root) {
158
+ if (!existsSync(root)) return [];
159
+ const files = [];
160
+ const pending = [root];
161
+ while (pending.length > 0) {
162
+ const directory = pending.pop();
163
+ for (const entry of readdirSync(directory, { withFileTypes: true })) {
164
+ const absolute = join(directory, entry.name);
165
+ if (entry.isDirectory()) pending.push(absolute);
166
+ else if (entry.isFile()) files.push(absolute);
167
+ }
168
+ }
169
+ return files.sort();
170
+ }
171
+
172
+ export function artifactManifest(root) {
173
+ const base = resolve(root);
174
+ return walkFiles(base).map((absolute) => {
175
+ const bytes = readFileSync(absolute);
176
+ return {
177
+ path: relative(base, absolute).split(sep).join('/'),
178
+ type: 'file',
179
+ size: bytes.length,
180
+ executable: process.platform === 'win32' ? null : Boolean(statSync(absolute).mode & 0o111),
181
+ sha256: createHash('sha256').update(bytes).digest('hex'),
182
+ };
183
+ });
184
+ }
185
+
186
+ function argument(flag, fallback) {
187
+ const at = process.argv.indexOf(flag);
188
+ return at >= 0 ? process.argv[at + 1] : fallback;
189
+ }
190
+
191
+ if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
192
+ try {
193
+ const command = process.argv[2];
194
+ const root = resolve(argument('--root', SCRIPT_ROOT));
195
+ if (command === 'targets') console.log(distributionTargets().join(' '));
196
+ else if (command === 'plan') {
197
+ const plan = artifactPlan(argument('--target', ''));
198
+ const field = argument('--field', '');
199
+ console.log(field ? String(plan[field] ?? '') : JSON.stringify(plan, null, 2));
200
+ }
201
+ else if (command === 'legal-files') {
202
+ for (const file of DISTRIBUTION_PRODUCT.legalFiles) console.log(`${file.source}|${file.bundlePath}`);
203
+ }
204
+ else if (command === 'verify-dist') console.log(JSON.stringify(verifyEngineDistribution(root), null, 2));
205
+ else if (command === 'verify-bundle') console.log(JSON.stringify(verifyBundle(root, argument('--target', '')), null, 2));
206
+ else if (command === 'manifest') console.log(JSON.stringify(artifactManifest(root), null, 2));
207
+ else throw new DistributionError('usage: distribution-contract.mjs targets|plan|legal-files|verify-dist|verify-bundle|manifest [options]');
208
+ } catch (error) {
209
+ console.error(`[distribution] ${error instanceof Error ? error.message : String(error)}`);
210
+ process.exitCode = 1;
211
+ }
212
+ }
@@ -0,0 +1,33 @@
1
+ {
2
+ "productName": "Afyx Graph",
3
+ "releaseChannel": "technical-alpha",
4
+ "packageName": "@a5zero7/afyx-graph",
5
+ "cli": "afyx-graph",
6
+ "bundlePrefix": "afyx-graph",
7
+ "runtime": {
8
+ "name": "Node.js",
9
+ "ownership": "external_platform",
10
+ "executable": "node",
11
+ "minimumVersion": "22.5.0"
12
+ },
13
+ "targets": [
14
+ "darwin-arm64",
15
+ "darwin-x64",
16
+ "linux-arm64",
17
+ "linux-x64",
18
+ "win32-arm64",
19
+ "win32-x64"
20
+ ],
21
+ "engineSentinels": [
22
+ "bin/afyx-graph.js",
23
+ "db/schema.sql",
24
+ "index.js",
25
+ "ui/shimmer-progress.js"
26
+ ],
27
+ "legalFiles": [
28
+ {
29
+ "source": "LICENSE",
30
+ "bundlePath": "LICENSE"
31
+ }
32
+ ]
33
+ }
@@ -0,0 +1,61 @@
1
+ #!/usr/bin/env node
2
+
3
+ /**
4
+ * afyx-engineering-kit
5
+ * Universal CLI entrypoint for AFYX Engineering Kit.
6
+ */
7
+
8
+ import {
9
+ getPackageVersion,
10
+ getHelpText,
11
+ parseCliArgs,
12
+ buildSubprocessCall,
13
+ executeSubprocess,
14
+ } from '../scripts/afyx-npm-installer.mjs';
15
+
16
+ function verifyNodeRuntime() {
17
+ const version = process.versions.node;
18
+ const [major, minor] = version.split('.').map(Number);
19
+ if (major < 22 || (major === 22 && minor < 5)) {
20
+ console.error(`Error: AFYX Engineering Kit requires Node.js >= 22.5.0 (current: v${version}).`);
21
+ process.exit(1);
22
+ }
23
+ }
24
+
25
+ async function main() {
26
+ verifyNodeRuntime();
27
+ const parsed = parseCliArgs(process.argv.slice(2));
28
+
29
+ if (parsed.showVersion) {
30
+ console.log(`afyx-engineering-kit v${getPackageVersion()}`);
31
+ process.exit(0);
32
+ }
33
+
34
+ if (parsed.showHelp) {
35
+ console.log(getHelpText());
36
+ process.exit(0);
37
+ }
38
+
39
+ if (parsed.errors.length > 0) {
40
+ for (const err of parsed.errors) {
41
+ console.error(`Error: ${err}`);
42
+ }
43
+ console.error('\nRun "afyx-engineering-kit --help" for usage information.');
44
+ process.exit(1);
45
+ }
46
+
47
+ const callInfo = buildSubprocessCall(parsed.command, parsed.options);
48
+
49
+ try {
50
+ const exitCode = await executeSubprocess(callInfo);
51
+ process.exit(exitCode);
52
+ } catch (err) {
53
+ console.error(`Failed to launch installer lifecycle subprocess (${callInfo.executable}):`, err.message);
54
+ process.exit(1);
55
+ }
56
+ }
57
+
58
+ main().catch((err) => {
59
+ console.error('Fatal CLI execution error:', err);
60
+ process.exit(1);
61
+ });