afyx-engineering-kit 0.1.0-alpha.4 → 0.1.0-alpha.6

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 (33) hide show
  1. package/.afyx-source-revision +1 -1
  2. package/README.md +12 -0
  3. package/afyx-graph/engine/release/RELEASE-MANIFEST.json +3 -3
  4. package/afyx-graph/engine/release/SHA256SUMS +2 -2
  5. package/afyx-graph/engine/release/afyx-graph-linux-x64.tar.gz +0 -0
  6. package/afyx-graph/engine/release/afyx-graph-win32-x64.zip +0 -0
  7. package/bin/afyx-engineering-kit.mjs +22 -1
  8. package/install.ps1 +84 -13
  9. package/install.sh +81 -1
  10. package/package.json +2 -1
  11. package/scripts/afyx-install-backend.mjs +46 -0
  12. package/scripts/afyx-install-contract.mjs +139 -0
  13. package/scripts/afyx-midnight-circuit.mjs +328 -0
  14. package/scripts/afyx-npm-installer.mjs +27 -5
  15. package/scripts/install-afyx-graph.ps1 +75 -29
  16. package/scripts/lib/AfyxPlatform.ps1 +133 -0
  17. package/scripts/lib/AfyxPlatform.psm1 +6 -0
  18. package/scripts/package-release-zip.ps1 +124 -0
  19. package/scripts/validate-release-zip-graph.mjs +55 -0
  20. package/verify.ps1 +25 -9
  21. package/verify.sh +9 -1
  22. package/afyx-context/test-fixtures/coordination-worker.mjs +0 -52
  23. package/afyx-context/test-fixtures/graph-consumer-repo/addons/sale_extension/__init__.py +0 -1
  24. package/afyx-context/test-fixtures/graph-consumer-repo/addons/sale_extension/__manifest__.py +0 -4
  25. package/afyx-context/test-fixtures/graph-consumer-repo/addons/sale_extension/models/__init__.py +0 -1
  26. package/afyx-context/test-fixtures/graph-consumer-repo/addons/sale_extension/models/sale_order.py +0 -5
  27. package/afyx-context/test-fixtures/integrated-dogfood-repo/addons/integrated_sales/__init__.py +0 -1
  28. package/afyx-context/test-fixtures/integrated-dogfood-repo/addons/integrated_sales/__manifest__.py +0 -10
  29. package/afyx-context/test-fixtures/integrated-dogfood-repo/addons/integrated_sales/models/__init__.py +0 -2
  30. package/afyx-context/test-fixtures/integrated-dogfood-repo/addons/integrated_sales/models/sale_order.py +0 -20
  31. package/afyx-context/test-fixtures/integrated-dogfood-repo/addons/integrated_sales/models/sale_order_audit.py +0 -11
  32. package/afyx-context/test-fixtures/integrated-dogfood-repo/addons/integrated_sales/security/ir.model.access.csv +0 -2
  33. package/afyx-context/test-fixtures/integrated-dogfood-repo/addons/integrated_sales/views/sale_order_views.xml +0 -14
@@ -1 +1 @@
1
- 838b5b0bf1d3413579281cbd6c5250ec767ba79d
1
+ 70352243e5f312a082ac394c470031750ba32f36
package/README.md CHANGED
@@ -150,6 +150,11 @@ With Node.js 22.5 or newer, the intended public registry command is:
150
150
  npx afyx-engineering-kit install
151
151
  ```
152
152
 
153
+ In a release containing Midnight Circuit, an interactive ANSI terminal shows
154
+ Detect → Select → Configure → Review/Apply → Finish. Use `--ui plain` for text
155
+ output; CI and terminals without ANSI support use the text flow automatically.
156
+ macOS does not yet have a verified Full Graph archive.
157
+
153
158
  Use `--preset recommended` for core engineering skills or `--preset full`
154
159
  for the prebuilt Graph, Context, Forge, and applicable skills. `full` requires
155
160
  Windows x64 or Linux x64 for Graph. Provider configuration is optional and
@@ -185,6 +190,13 @@ To remove the link:
185
190
 
186
191
  ### GitHub prerelease tarball fallback
187
192
 
193
+ The GitHub-generated `dev.zip` is a source snapshot. It does not include the
194
+ revision-matched Graph runtime needed by the Full preset. A Windows x64 Full
195
+ release ZIP is built separately from an immutable commit with a verified Graph
196
+ archive and `.afyx-source-revision` marker. Its download link will be added
197
+ after the public release and anonymous installation checks pass. Node.js 22.5+
198
+ is required; Windows PowerShell 5.1 and PowerShell 7 are the intended hosts.
199
+
188
200
  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
201
 
190
202
  ```bash
@@ -3,19 +3,19 @@
3
3
  "product": "Afyx Graph",
4
4
  "product_version": "1.0.0",
5
5
  "release_tag": "afyx-graph-v1.0.0",
6
- "source_revision": "838b5b0bf1d3413579281cbd6c5250ec767ba79d",
6
+ "source_revision": "70352243e5f312a082ac394c470031750ba32f36",
7
7
  "integrity_claim": "sha256",
8
8
  "publisher_authenticity": "requires-independent-attestation",
9
9
  "artifacts": [
10
10
  {
11
11
  "file": "afyx-graph-linux-x64.tar.gz",
12
12
  "target": "linux-x64",
13
- "sha256": "edc4c47f1ed3ca3778117999c27446eebf72b5eccfb8c4ce7f989f27a8d8a9e7"
13
+ "sha256": "6d8f7870431a58e460850ca237ceeed82d5f4e32ca3348a753a2d14084eccc6a"
14
14
  },
15
15
  {
16
16
  "file": "afyx-graph-win32-x64.zip",
17
17
  "target": "win32-x64",
18
- "sha256": "956de055032e821b6af734f8644dac6921da87716567244b3669d8c218590883"
18
+ "sha256": "98223eb13c1a6196f90c610f945ac6a94cc3255c803c735fbd790cf7448f2f63"
19
19
  }
20
20
  ]
21
21
  }
@@ -1,2 +1,2 @@
1
- edc4c47f1ed3ca3778117999c27446eebf72b5eccfb8c4ce7f989f27a8d8a9e7 afyx-graph-linux-x64.tar.gz
2
- 956de055032e821b6af734f8644dac6921da87716567244b3669d8c218590883 afyx-graph-win32-x64.zip
1
+ 6d8f7870431a58e460850ca237ceeed82d5f4e32ca3348a753a2d14084eccc6a afyx-graph-linux-x64.tar.gz
2
+ 98223eb13c1a6196f90c610f945ac6a94cc3255c803c735fbd790cf7448f2f63 afyx-graph-win32-x64.zip
@@ -12,6 +12,7 @@ import {
12
12
  buildSubprocessCall,
13
13
  executeSubprocess,
14
14
  } from '../scripts/afyx-npm-installer.mjs';
15
+ import { runMidnightCircuit, terminalMode } from '../scripts/afyx-midnight-circuit.mjs';
15
16
 
16
17
  function verifyNodeRuntime() {
17
18
  const version = process.versions.node;
@@ -44,12 +45,32 @@ async function main() {
44
45
  process.exit(1);
45
46
  }
46
47
 
48
+ let finish;
49
+ if (parsed.command === 'install') {
50
+ const mode = terminalMode({ requested: parsed.options.ui || 'auto' });
51
+ const hasSelections = parsed.options.preset || parsed.options.provider || parsed.options.providerScope ||
52
+ parsed.options.skipProviderConfiguration || parsed.options.componentActions.length || parsed.options.customComponents.length;
53
+ if (parsed.options.ui === 'tui' && (hasSelections || parsed.options.nonInteractive || parsed.options.dryRun || parsed.options.validateOnly)) {
54
+ throw new Error('--ui tui runs the interactive installer; remove scripted selection/preview flags or use --ui plain.');
55
+ }
56
+ if (mode === 'tui' && !hasSelections &&
57
+ !parsed.options.nonInteractive && !parsed.options.dryRun && !parsed.options.validateOnly) {
58
+ const selection = await runMidnightCircuit({ options: parsed.options });
59
+ if (!selection) { console.log('Installation canceled without changes.'); return; }
60
+ finish = selection.finish;
61
+ Object.assign(parsed.options, selection);
62
+ delete parsed.options.finish;
63
+ }
64
+ }
47
65
  const callInfo = buildSubprocessCall(parsed.command, parsed.options);
66
+ if (parsed.options.ui === 'plain') callInfo.env = { ...callInfo.env, NO_COLOR: '1' };
48
67
 
49
68
  try {
50
69
  const exitCode = await executeSubprocess(callInfo);
51
- process.exit(exitCode);
70
+ const finalCode = finish ? await finish(exitCode) : exitCode;
71
+ process.exit(finalCode);
52
72
  } catch (err) {
73
+ if (finish) await finish(1);
53
74
  console.error(`Failed to launch installer lifecycle subprocess (${callInfo.executable}):`, err.message);
54
75
  process.exit(1);
55
76
  }
package/install.ps1 CHANGED
@@ -22,8 +22,11 @@ param(
22
22
  [string]$ClaudeHome = $(if ($env:CLAUDE_CONFIG_DIR) { $env:CLAUDE_CONFIG_DIR } else { Join-Path $env:USERPROFILE '.claude' }),
23
23
  [string]$ClaudeConfigDir = $(if ($env:CLAUDE_CONFIG_DIR) { $env:CLAUDE_CONFIG_DIR } else { '' }),
24
24
  [switch]$SkipProviderConfiguration,
25
+ [switch]$PlanJson,
26
+ [string]$ExpectedPlan = '',
25
27
  [string]$ContextRuntimeRoot = $(if ($env:AFYX_CONTEXT_RUNTIME_ROOT) { $env:AFYX_CONTEXT_RUNTIME_ROOT } else { Join-Path $env:USERPROFILE '.afyx\context' }),
26
28
  [string]$ForgeRuntimeRoot = $(if ($env:AFYX_FORGE_RUNTIME_ROOT) { $env:AFYX_FORGE_RUNTIME_ROOT } else { Join-Path $env:USERPROFILE '.afyx\forge' }),
29
+ [string]$GraphRuntimeRoot = $(if ($env:AFYX_GRAPH_RUNTIME_ROOT) { $env:AFYX_GRAPH_RUNTIME_ROOT } else { Join-Path $env:USERPROFILE '.afyx\graph' }),
27
30
  [string]$AfyxInstallRoot = $(if ($env:AFYX_INSTALL_ROOT) { $env:AFYX_INSTALL_ROOT } else { Join-Path $env:USERPROFILE '.afyx' }),
28
31
  [string]$HostBridgeRuntimeRoot = $(if ($env:AFYX_HOST_BRIDGE_RUNTIME_ROOT) { $env:AFYX_HOST_BRIDGE_RUNTIME_ROOT } else { Join-Path $env:USERPROFILE '.afyx\host-bridge' })
29
32
  )
@@ -32,6 +35,7 @@ Set-StrictMode -Version Latest
32
35
  $ErrorActionPreference = 'Stop'
33
36
 
34
37
  $packageRoot = $PSScriptRoot
38
+ if (($PlanJson -or $ExpectedPlan) -and -not $Preset) { throw 'Structured planning requires an explicit preset.' }
35
39
  if ($CustomComponent.Count) {
36
40
  $CustomComponent = @($CustomComponent | ForEach-Object { $_ -split ',' } | ForEach-Object { $_.Trim() } | Where-Object { $_ })
37
41
  }
@@ -53,13 +57,14 @@ $contextCompanionSource = Join-Path $packageRoot 'skills\afyx-context'
53
57
  $forgeInstaller = Join-Path $packageRoot 'scripts\install-afyx-forge.ps1'
54
58
  $forgeMetadataPath = Join-Path $packageRoot 'afyx-forge\afyx-forge.json'
55
59
  $forgeCompanionSource = Join-Path $packageRoot 'skills\afyx-forge'
56
- $graphRuntimeRoot = if ($env:AFYX_GRAPH_RUNTIME_ROOT) { $env:AFYX_GRAPH_RUNTIME_ROOT } else { Join-Path $env:USERPROFILE '.afyx\graph' }
60
+ $graphRuntimeRoot = if ($GraphRuntimeRoot) { $GraphRuntimeRoot } elseif ($env:AFYX_GRAPH_RUNTIME_ROOT) { $env:AFYX_GRAPH_RUNTIME_ROOT } else { Join-Path $env:USERPROFILE '.afyx\graph' }
57
61
  $codexHome = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $env:USERPROFILE '.codex' }
58
62
 
59
63
  if ($InstallUsageTracker -and $SkipUsageTracker) { throw '-InstallUsageTracker and -SkipUsageTracker cannot be used together.' }
60
64
 
61
65
  # One component truth: scripts/components.json, read through the shared module.
62
66
  Import-Module (Join-Path $packageRoot 'scripts\lib\AfyxComponents.psm1') -Force
67
+ Import-Module (Join-Path $packageRoot 'scripts\lib\AfyxPlatform.psm1') -Force
63
68
  Import-Module (Join-Path $packageRoot 'scripts\lib\AfyxSkillLifecycle.psm1') -Force -DisableNameChecking
64
69
  Import-Module (Join-Path $packageRoot 'scripts\lib\AfyxTerminal.psm1') -Force
65
70
  $terminal = New-AfyxTerminalContext
@@ -464,6 +469,60 @@ if ($controlPlan) {
464
469
  }
465
470
  }
466
471
 
472
+ if ($PlanJson -or $ExpectedPlan) {
473
+ $planRows = @()
474
+ foreach ($component in (Get-AfyxComponentContract)) {
475
+ $id = [string]$component.id
476
+ $state = $componentStates[$id]
477
+ $item = @($controlPlan.Components | Where-Object { $_.Id -eq $id })[0]
478
+ $planRows += [ordered]@{
479
+ id = $id; name = [string]$component.name; type = [string]$component.type
480
+ currentState = [string]$state.State; desired = [bool]$item.Desired
481
+ backendAction = [string]$actionDecisions[$id]; target = [string]$state.Path
482
+ ownership = [string]$item.ActualOwnership; version = [string]$state.Version
483
+ availableVersion = Get-AvailableVersion $id
484
+ compatibility = $(if ($item.Drift -eq 'NOT_APPLICABLE') { 'NOT SUPPORTED' } else { 'SUPPORTED' })
485
+ detail = [string]$state.Detail
486
+ }
487
+ }
488
+ $configurationPaths = @()
489
+ if (-not $SkipProviderConfiguration) {
490
+ if ('codex' -in $Provider) { $configurationPaths += (Join-Path $codexHome 'config.toml') }
491
+ if ('antigravity' -in $Provider) { $configurationPaths += $(if ($ProviderScope -eq 'workspace') { Join-Path $WorkspaceRoot '.agents\mcp_config.json' } else { Join-Path $GeminiHome 'config\mcp_config.json' }) }
492
+ if ('claude' -in $Provider) { $configurationPaths += $(if ($ProviderScope -eq 'workspace') { Join-Path $WorkspaceRoot '.mcp.json' } else { Join-Path $(if ($ClaudeConfigDir) { $ClaudeConfigDir } else { $env:USERPROFILE }) '.claude.json' }) }
493
+ }
494
+ $planInput = [ordered]@{ preset = $Preset; providers = ($Provider -join ','); scope = $ProviderScope
495
+ configureProviders = -not [bool]$SkipProviderConfiguration; workspaceRoot = $WorkspaceRoot
496
+ sourceRoot = $packageRoot; platform = 'windows'; components = $planRows
497
+ configurationPaths = $configurationPaths; expectedFingerprint = $ExpectedPlan }
498
+ $planInput.blockers = @()
499
+ $planInput.additionalTargets = @()
500
+ foreach ($root in @($SkillsRoot) + @($additionalSkillRoots)) {
501
+ foreach ($item in @($controlPlan.Components | Where-Object { $_.Desired })) {
502
+ if ($item.Id -in @('efficient-coding', 'odoo-engineering', 'afyx-engineering-expert') -or
503
+ (-not $SkipProviderConfiguration -and $item.Id -in @('afyx-context', 'afyx-forge'))) {
504
+ $planInput.additionalTargets += [ordered]@{ id = $item.Id; type = 'skill'; target = (Join-Path $root $item.Id) }
505
+ }
506
+ }
507
+ }
508
+ if (-not $SkipProviderConfiguration -and $Provider.Count) {
509
+ $planInput.additionalTargets += [ordered]@{ id = 'afyx-host-bridge'; type = 'runtime'; target = $HostBridgeRuntimeRoot }
510
+ }
511
+ if (-not (Get-Command git -ErrorAction SilentlyContinue)) { $planInput.blockers += 'Git is required by the installer.' }
512
+ if (-not $SkipProviderConfiguration) {
513
+ if ('codex' -in $Provider -and -not ($codexCommandDetected -or $vscodeExtensionDetected)) { $planInput.blockers += 'Selected Codex host is unavailable.' }
514
+ if ('antigravity' -in $Provider -and -not ($antigravityCommandDetected -or $antigravityIdeDetected)) { $planInput.blockers += 'Selected Antigravity host is unavailable.' }
515
+ if ('claude' -in $Provider -and -not ($claudeCommandDetected -or $claudeVsCodeDetected)) { $planInput.blockers += 'Selected Claude Code host is unavailable.' }
516
+ }
517
+ $previousOutputEncoding = $OutputEncoding
518
+ try {
519
+ $OutputEncoding = [Text.UTF8Encoding]::new($false)
520
+ $planOutput = $planInput | ConvertTo-Json -Depth 8 -Compress | & node (Join-Path $packageRoot 'scripts\afyx-install-contract.mjs') plan
521
+ if ($LASTEXITCODE -ne 0) { throw 'PLAN_CHANGED or backend plan could not be created; review a new plan before applying.' }
522
+ } finally { $OutputEncoding = $previousOutputEncoding }
523
+ if ($PlanJson) { Write-Output $planOutput; return }
524
+ }
525
+
467
526
  $codexCliDetected = [bool]$codexCommandDetected
468
527
  $graphMetadata = Get-Content -Raw -LiteralPath $graphMetadataPath | ConvertFrom-Json
469
528
  $distProductPath = Join-Path $packageRoot 'afyx-graph\engine\scripts\distribution-product.json'
@@ -513,7 +572,7 @@ Write-AfyxSection -Title 'Prerequisite Inventory' -Terminal $terminal
513
572
  $gitVersion = try { (& git --version 2>$null) -join ' ' } catch { '' }
514
573
  $nodeVersion = try { (& node --version 2>$null) -join ' ' } catch { '' }
515
574
  $npmVersion = try { (& npm --version 2>$null) -join ' ' } catch { '' }
516
- Write-AfyxStatus -Status HEALTHY -Name 'OS/architecture [REQUIRED]' -Detail "$([System.Runtime.InteropServices.RuntimeInformation]::OSDescription) / $([System.Runtime.InteropServices.RuntimeInformation]::OSArchitecture)" -Terminal $terminal
575
+ Write-AfyxStatus -Status HEALTHY -Name 'OS/architecture [REQUIRED]' -Detail (Get-AfyxPlatformDescription) -Terminal $terminal
517
576
  Write-AfyxStatus -Status HEALTHY -Name 'Platform shell [REQUIRED]' -Detail "PowerShell $($PSVersionTable.PSVersion)" -Terminal $terminal
518
577
  Write-AfyxStatus -Status $(if ($gitVersion) { 'HEALTHY' } else { 'BLOCKED' }) -Name 'Git [REQUIRED]' -Detail $(if ($gitVersion) { $gitVersion } else { 'missing; install Git for Windows from https://git-scm.com/' }) -Terminal $terminal
519
578
  $codexRequired = 'codex' -in $Provider -or -not $Provider.Count
@@ -688,18 +747,22 @@ if ($graphAction -ne 'skip') {
688
747
  $gitCmd = Get-Command git -ErrorAction SilentlyContinue
689
748
  $tarCmd = Get-Command tar -ErrorAction SilentlyContinue
690
749
  $enginePackage = Join-Path $packageRoot 'afyx-graph\engine\package.json'
691
- if (-not (Test-Path -LiteralPath $enginePackage -PathType Leaf)) {
692
- throw "Afyx Graph installation is BLOCKED: release cache is absent and source engine is missing at $enginePackage."
693
- }
694
- if (-not $sourceIsCheckout -or -not $gitCmd -or -not $tarCmd) {
695
- throw "Afyx Graph installation is BLOCKED: Git and tar are required for clean source staging when building from local repository."
750
+ if ($Offline) {
751
+ if (-not (Test-Path -LiteralPath $enginePackage -PathType Leaf)) {
752
+ throw "Afyx Graph installation is BLOCKED: release cache is absent and source engine is missing at $enginePackage."
753
+ }
754
+ if (-not $sourceIsCheckout -or -not $gitCmd -or -not $tarCmd) {
755
+ throw "Afyx Graph installation is BLOCKED: offline installation requires a precompiled release cache or a clean Git checkout with tar."
756
+ }
696
757
  }
697
- $gitStatus = & $gitCmd.Source -C $packageRoot status --porcelain -- afyx-graph 2>$null
698
- $graphSourceDirty = [bool]($gitStatus -join '')
699
- if ($graphSourceDirty -and -not $AllowDirtySource) {
700
- $headCommit = (& $gitCmd.Source -C $packageRoot rev-parse HEAD 2>$null).Trim()
701
- if (-not $headCommit -or $headCommit -notmatch '^[0-9a-f]{7,64}$') {
702
- throw "Afyx Graph installation is BLOCKED: local afyx-graph source has uncommitted changes and HEAD commit is unavailable. Commit the changes or specify -AllowDirtySource for development builds."
758
+ if ($sourceIsCheckout -and $gitCmd) {
759
+ $gitStatus = & $gitCmd.Source -C $packageRoot status --porcelain -- afyx-graph 2>$null
760
+ $graphSourceDirty = [bool]($gitStatus -join '')
761
+ if ($graphSourceDirty -and -not $AllowDirtySource) {
762
+ $headCommit = (& $gitCmd.Source -C $packageRoot rev-parse HEAD 2>$null).Trim()
763
+ if (-not $headCommit -or $headCommit -notmatch '^[0-9a-f]{7,64}$') {
764
+ throw "Afyx Graph installation is BLOCKED: local afyx-graph source has uncommitted changes and HEAD commit is unavailable. Commit the changes or specify -AllowDirtySource for development builds."
765
+ }
703
766
  }
704
767
  }
705
768
  }
@@ -796,6 +859,14 @@ function Invoke-AfyxInstallStage {
796
859
 
797
860
  if ($wizardMode) { Show-AfyxStep -Current 4 -Terminal $terminal }
798
861
 
862
+ if ($ExpectedPlan) {
863
+ $previousOutputEncoding = $OutputEncoding
864
+ try {
865
+ $OutputEncoding = [Text.UTF8Encoding]::new($false)
866
+ $null = $planInput | ConvertTo-Json -Depth 8 -Compress | & node (Join-Path $packageRoot 'scripts\afyx-install-contract.mjs') plan
867
+ if ($LASTEXITCODE -ne 0) { throw 'PLAN_CHANGED: state changed before mutation; review a new plan.' }
868
+ } finally { $OutputEncoding = $previousOutputEncoding }
869
+ }
799
870
  $summary = [ordered]@{}
800
871
  $changesApplied = $false
801
872
  $skillActions = @{}
package/install.sh CHANGED
@@ -31,6 +31,10 @@ gemini_home="${AFYX_GEMINI_HOME:-$HOME/.gemini}"
31
31
  claude_home="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
32
32
  claude_config_dir="${CLAUDE_CONFIG_DIR:-}"
33
33
  skip_provider_configuration=false
34
+ plan_json=false
35
+ expected_plan=
36
+ contract_plan_ready=false
37
+ contract_plan_actions=()
34
38
 
35
39
  usage() {
36
40
  printf '%s\n' 'Usage: ./install.sh [--skills-root PATH] [--context-runtime-root PATH] [--forge-runtime-root PATH] [--provider codex|antigravity|claude[,..]] [--provider-scope global|workspace] [--workspace-root PATH] [--gemini-home PATH] [--claude-home PATH] [--claude-config-dir PATH] [--skip-provider-configuration] [--preset minimal|recommended|full|custom] [--custom-component ID] [--component ID=skip|install|update|repair|adopt] [--update-installed] [--force] [--validate-only] [--dry-run]'
@@ -58,12 +62,17 @@ while (($#)); do
58
62
  --claude-home) (($# >= 2)) || { printf '%s\n' '--claude-home requires a value.' >&2; exit 2; }; claude_home="$2"; shift 2 ;;
59
63
  --claude-config-dir) (($# >= 2)) || { printf '%s\n' '--claude-config-dir requires a value.' >&2; exit 2; }; claude_config_dir="$2"; shift 2 ;;
60
64
  --skip-provider-configuration) skip_provider_configuration=true; shift ;;
65
+ --plan-json) plan_json=true; shift ;;
66
+ --expected-plan) (($# >= 2)) || exit 2; expected_plan="$2"; shift 2 ;;
61
67
  --validate-only) validate_only=true; shift ;;
62
68
  --dry-run) dry_run=true; shift ;;
63
69
  -h|--help) usage; exit 0 ;;
64
70
  *) printf 'Unknown option: %s\n' "$1" >&2; usage >&2; exit 2 ;;
65
71
  esac
66
72
  done
73
+ if { "$plan_json" || [[ -n "$expected_plan" ]]; } && [[ -z "$preset" ]]; then
74
+ printf 'Structured planning requires an explicit preset.\n' >&2; exit 2
75
+ fi
67
76
 
68
77
  if [[ "$provider_explicit" == false && -t 0 && -t 1 && -z "${CI:-}" ]]; then
69
78
  detected_providers=
@@ -86,6 +95,17 @@ if [[ "$provider_explicit" == false && -t 0 && -t 1 && -z "${CI:-}" ]]; then
86
95
  esac
87
96
  fi
88
97
 
98
+ # An implicit provider is optional when its host is absent. Explicit selections
99
+ # still fail the host preflight below instead of silently skipping registration.
100
+ if [[ "$provider_explicit" == false && "$provider_list" == codex && "$skip_provider_configuration" == false ]] &&
101
+ ! command -v codex >/dev/null 2>&1; then
102
+ codex_extension_present=false
103
+ for extension in "$HOME"/.vscode/extensions/openai.chatgpt-*; do
104
+ [[ -d "$extension" ]] && { codex_extension_present=true; break; }
105
+ done
106
+ if ! "$codex_extension_present"; then skip_provider_configuration=true; fi
107
+ fi
108
+
89
109
  case "$provider_scope" in global|workspace) ;; *) printf 'Unknown provider scope: %s\n' "$provider_scope" >&2; exit 2 ;; esac
90
110
  old_ifs=$IFS; IFS=','
91
111
  for provider_id in $provider_list; do case "$provider_id" in codex|antigravity|claude) ;; *) printf 'Unknown provider: %s\n' "$provider_id" >&2; exit 2 ;; esac; done
@@ -153,6 +173,10 @@ component_version() { afyx_component_evaluate "$1"; printf '%s' "$AFYX_VERSION";
153
173
  run() { if "$dry_run"; then printf '+ '; printf '%q ' "$@"; printf '\n'; else "$@"; fi; }
154
174
  interactive=false
155
175
  if [[ -t 0 && -z "${CI:-}" ]] && ! "$dry_run"; then interactive=true; fi
176
+ if [[ -z "$preset" && "$component_action_count" -eq 0 && "$interactive" == false &&
177
+ "$validate_only" == false && "$update_installed" == false && "$force" == false ]]; then
178
+ preset=recommended
179
+ fi
156
180
 
157
181
  available_version() {
158
182
  case "$1" in
@@ -187,6 +211,12 @@ explicit_action() {
187
211
 
188
212
  component_action() {
189
213
  local id="$1" label="$2" state="$3" installed="$4" available action= answer default
214
+ if "$contract_plan_ready"; then
215
+ local contract_decision
216
+ for contract_decision in ${contract_plan_actions[@]+"${contract_plan_actions[@]}"}; do
217
+ if [[ "${contract_decision%%=*}" == "$id" ]]; then printf '%s' "${contract_decision#*=}"; return; fi
218
+ done
219
+ fi
190
220
  available="$(available_version "$id")"
191
221
  if action="$(explicit_action "$id")"; then :
192
222
  elif [[ -n "$preset" ]]; then
@@ -331,7 +361,7 @@ if [[ -n "$preset" ]]; then
331
361
  done
332
362
  fi
333
363
  printf '\nProvider Plan\n'
334
- if "$skip_provider_configuration"; then printf 'Provider configuration: skipped explicitly\n'; fi
364
+ if "$skip_provider_configuration"; then printf 'Provider configuration: skipped (requested or no implicit host)\n'; fi
335
365
  old_ifs=$IFS; IFS=','
336
366
  for provider_id in $provider_list; do
337
367
  if [[ "$provider_id" == codex ]]; then
@@ -423,6 +453,53 @@ if "$validate_only"; then
423
453
  exit 0
424
454
  fi
425
455
 
456
+ if "$plan_json" || [[ -n "$expected_plan" ]]; then
457
+ command -v node >/dev/null 2>&1 || { printf 'Node.js is required for structured planning.\n' >&2; exit 1; }
458
+ contract_args=(plan-rows "$preset" "$provider_list" "$provider_scope" "$([[ "$skip_provider_configuration" == true ]] && printf false || printf true)" "$workspace_root" "$PACKAGE_ROOT" "$(afyx_platform)" "$expected_plan")
459
+ command -v git >/dev/null 2>&1 || contract_args+=(--block 'Git is required by the installer.')
460
+ if ! "$skip_provider_configuration"; then
461
+ if [[ ",$provider_list," == *,codex,* ]] && ! "$codex_cli_detected" && ! "$vscode_extension_detected"; then contract_args+=(--block 'Selected Codex host is unavailable.'); fi
462
+ if [[ ",$provider_list," == *,antigravity,* ]] && ! "$antigravity_detected"; then contract_args+=(--block 'Selected Antigravity host is unavailable.'); fi
463
+ if [[ ",$provider_list," == *,claude,* ]] && ! "$claude_cli_detected" && ! "$claude_vscode_detected"; then contract_args+=(--block 'Selected Claude Code host is unavailable.'); fi
464
+ fi
465
+ for plan_id in $(afyx_component_ids); do
466
+ plan_state="$(component_state "$plan_id")"
467
+ afyx_component_evaluate "$plan_id"
468
+ plan_detail="$AFYX_DETAIL"; plan_version="$AFYX_VERSION"
469
+ afyx_control_classify "$plan_id" "$plan_state" "$preset" "$custom_component_list" "$provider_list"
470
+ plan_desired="$AFYX_DESIRED"; plan_ownership="$AFYX_ACTUAL_OWNERSHIP"
471
+ plan_compatibility=SUPPORTED
472
+ [[ "$AFYX_DRIFT" == NOT_APPLICABLE ]] && plan_compatibility='NOT SUPPORTED'
473
+ if [[ "$AFYX_REPAIR" == BLOCKED ]]; then plan_action=blocked
474
+ else plan_action="$(component_action "$plan_id" "$(afyx_component_field "$plan_id" name)" "$plan_state" "$plan_version")"; fi
475
+ contract_plan_actions+=("$plan_id=$plan_action")
476
+ contract_args+=(--component "$plan_id" "$(afyx_component_field "$plan_id" name)" "$(afyx_component_field "$plan_id" type)" "$plan_state" "$plan_desired" "$plan_action" "$(afyx_component_root "$plan_id")" "$plan_ownership" "$plan_version" "$(available_version "$plan_id")" "$plan_compatibility" "$plan_detail")
477
+ done
478
+ for plan_root in "$skills_root" ${additional_skill_roots[@]+"${additional_skill_roots[@]}"}; do
479
+ for plan_id in $(afyx_component_ids); do
480
+ afyx_component_desired "$plan_id" "$preset" "$custom_component_list" "$provider_list" || continue
481
+ if [[ "$(afyx_component_field "$plan_id" type)" == skill ]] ||
482
+ { ! "$skip_provider_configuration" && [[ "$plan_id" == afyx-context || "$plan_id" == afyx-forge ]]; }; then
483
+ contract_args+=(--extra-target "$plan_id" skill "$plan_root/$plan_id")
484
+ fi
485
+ done
486
+ done
487
+ if ! "$skip_provider_configuration"; then
488
+ [[ ",$provider_list," != *,codex,* ]] || contract_args+=(--config "${CODEX_HOME:-$HOME/.codex}/config.toml")
489
+ if [[ ",$provider_list," == *,antigravity,* ]]; then
490
+ if [[ "$provider_scope" == workspace ]]; then contract_args+=(--config "$workspace_root/.agents/mcp_config.json")
491
+ else contract_args+=(--config "$gemini_home/config/mcp_config.json"); fi
492
+ fi
493
+ if [[ ",$provider_list," == *,claude,* ]]; then
494
+ if [[ "$provider_scope" == workspace ]]; then contract_args+=(--config "$workspace_root/.mcp.json")
495
+ else contract_args+=(--config "${claude_config_dir:-$HOME}/.claude.json"); fi
496
+ fi
497
+ fi
498
+ contract_output="$(node "$PACKAGE_ROOT/scripts/afyx-install-contract.mjs" "${contract_args[@]}")" || exit $?
499
+ if "$plan_json"; then printf '%s\n' "$contract_output"; exit 0; fi
500
+ contract_plan_ready=true
501
+ fi
502
+
426
503
  if [[ -n "$preset" ]]; then
427
504
  blocked_plan=
428
505
  for plan_id in $(afyx_component_ids); do
@@ -452,6 +529,9 @@ for additional_root in ${additional_skill_roots[@]+"${additional_skill_roots[@]}
452
529
  case "$AFYX_OWNERSHIP_STATE" in NOT_INSTALLED|AFYX_OWNED_UNMODIFIED|AFYX_OWNED_MODIFIED) ;; *) printf 'Provider skill plan is blocked at %s because ownership is %s.\n' "$target" "$AFYX_OWNERSHIP_STATE" >&2; exit 1 ;; esac
453
530
  done
454
531
  done
532
+ if [[ -n "$expected_plan" ]]; then
533
+ node "$PACKAGE_ROOT/scripts/afyx-install-contract.mjs" "${contract_args[@]}" >/dev/null || exit $?
534
+ fi
455
535
  run mkdir -p "$skills_root"
456
536
  efficient_result=skipped
457
537
  odoo_result=skipped
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "afyx-engineering-kit",
3
- "version": "0.1.0-alpha.4",
3
+ "version": "0.1.0-alpha.6",
4
4
  "description": "Universal cross-platform CLI installer and lifecycle manager for AFYX Engineering Kit",
5
5
  "type": "module",
6
6
  "main": "./bin/afyx-engineering-kit.mjs",
@@ -25,6 +25,7 @@
25
25
  "skills/",
26
26
  "afyx-context/",
27
27
  "!afyx-context/test/**",
28
+ "!afyx-context/test-fixtures/**",
28
29
  "!afyx-context/benchmark/**",
29
30
  "afyx-forge/",
30
31
  "!afyx-forge/test/**",
@@ -0,0 +1,46 @@
1
+ import { spawnSync } from 'node:child_process';
2
+ import { buildSubprocessCall, PACKAGE_ROOT, subprocessEnvironment } from './afyx-npm-installer.mjs';
3
+ import { decodeContract } from './afyx-install-contract.mjs';
4
+
5
+ function capture(call) {
6
+ const invoke = (program) => spawnSync(program, call.args, {
7
+ encoding: 'utf8', windowsHide: true, timeout: 300000, maxBuffer: 8 * 1024 * 1024,
8
+ env: subprocessEnvironment(program, { ...call.env, CI: '1', NO_COLOR: '1' }),
9
+ });
10
+ let result = invoke(call.executable);
11
+ if (result.error?.code === 'ENOENT' && call.fallbackExecutable) result = invoke(call.fallbackExecutable);
12
+ if (result.error) throw result.error;
13
+ return { exitCode: result.status ?? 1, output: `${result.stdout || ''}\n${result.stderr || ''}` };
14
+ }
15
+
16
+ export function createBackendAdapter({ platform = process.platform, pkgRoot = PACKAGE_ROOT } = {}) {
17
+ return {
18
+ plan(options) {
19
+ const { expectedPlan: _expectedPlan, ...query } = options;
20
+ const result = capture(buildSubprocessCall('install', { ...query, planJson: true, nonInteractive: true }, platform, pkgRoot));
21
+ if (result.exitCode !== 0) throw new Error(`Backend plan failed (${result.exitCode}): ${result.output}`);
22
+ return decodeContract(result.output, 'AfyxInstallPlan/v1');
23
+ },
24
+ verify(options) {
25
+ const allowed = ['preset', 'provider', 'providerScope', 'workspaceRoot', 'skillsRoot',
26
+ 'contextRuntimeRoot', 'forgeRuntimeRoot', 'graphRuntimeRoot', 'customComponents', 'skipProviderConfiguration'];
27
+ const query = Object.fromEntries(allowed.filter((key) => options[key] !== undefined).map((key) => [key, options[key]]));
28
+ const result = capture(buildSubprocessCall('verify', { ...query, reportJson: true }, platform, pkgRoot));
29
+ return { ...decodeContract(result.output, 'AfyxVerification/v1'), exitCode: result.exitCode };
30
+ },
31
+ };
32
+ }
33
+
34
+ export function summarizeExecution(plan, verification, installerExit, reviewedPlan = plan) {
35
+ const rows = Array.isArray(verification.rows) ? verification.rows : [];
36
+ const components = plan.components.map((entry) => {
37
+ const reviewed = reviewedPlan.components.find((item) => item.id === entry.id);
38
+ const status = !entry.desired ? 'SKIPPED' : entry.compatibility === 'NOT SUPPORTED' ? 'NOT SUPPORTED'
39
+ : entry.currentState === 'HEALTHY' ? 'PASS' : 'FAILED';
40
+ const completed = { install: 'INSTALLED', update: 'UPDATED', downgrade: 'UPDATED', repair: 'REPAIRED', adopt: 'ADOPTED', skip: 'SKIPPED' };
41
+ const outcome = status === 'PASS' ? completed[reviewed?.backendAction] || 'VERIFIED' : status;
42
+ return { id: entry.id, name: entry.name, version: entry.version, status, outcome, detail: entry.detail };
43
+ });
44
+ const failed = installerExit !== 0 || verification.exitCode !== 0 || components.some((entry) => entry.status === 'FAILED');
45
+ return { status: failed ? 'FAILED' : 'PASS', components, rows };
46
+ }
@@ -0,0 +1,139 @@
1
+ import { createHash } from 'node:crypto';
2
+ import { existsSync, lstatSync, readFileSync, readdirSync, readlinkSync, realpathSync } from 'node:fs';
3
+ import { isAbsolute, join, relative, resolve } from 'node:path';
4
+ import { fileURLToPath } from 'node:url';
5
+
6
+ const digest = (value) => createHash('sha256').update(value).digest('hex');
7
+ const inside = (root, path) => { const part = relative(root, path); return part === '' || (!part.startsWith('..') && !isAbsolute(part)); };
8
+
9
+ // Snapshot owned program files only. Runtime indexes, backups and old releases
10
+ // are deliberately outside current/. No component-state decisions live here.
11
+ export function targetFingerprint(target, type) {
12
+ const hash = createHash('sha256');
13
+ let count = 0;
14
+ let bytes = 0;
15
+ const activeLinks = new Set();
16
+ const visit = (path, label, boundary) => {
17
+ let stat;
18
+ try { stat = lstatSync(path); } catch (error) {
19
+ if (error.code !== 'ENOENT') throw error;
20
+ hash.update(`${label}:MISSING\n`); return;
21
+ }
22
+ if (stat.isSymbolicLink()) {
23
+ hash.update(`${label}:LINK:${readlinkSync(path)}\n`);
24
+ const actual = realpathSync(path);
25
+ if (!inside(boundary, actual)) throw new Error(`Plan snapshot refuses a link outside its component: ${path}`);
26
+ if (activeLinks.has(actual)) throw new Error(`Plan snapshot refuses a link cycle: ${path}`);
27
+ activeLinks.add(actual);
28
+ try { visit(actual, `${label}/resolved`, boundary); } finally { activeLinks.delete(actual); }
29
+ return;
30
+ }
31
+ if (++count > 20000) throw new Error('Plan snapshot file limit exceeded');
32
+ if (stat.isDirectory()) {
33
+ hash.update(`${label}:DIRECTORY\n`);
34
+ for (const name of readdirSync(path).sort()) visit(join(path, name), `${label}/${name}`, boundary);
35
+ } else if (stat.isFile()) {
36
+ bytes += stat.size;
37
+ if (bytes > 256 * 1024 * 1024) throw new Error('Plan snapshot byte limit exceeded');
38
+ hash.update(`${label}:${stat.size}:`).update(readFileSync(path)).update('\n');
39
+ } else throw new Error(`Unsupported component filesystem entry: ${path}`);
40
+ };
41
+ const root = resolve(target);
42
+ if (type === 'runtime') {
43
+ for (const name of ['metadata.json', 'integrity.sha256', 'current']) visit(join(root, name), name, root);
44
+ } else visit(root, '.', root);
45
+ return hash.digest('hex');
46
+ }
47
+
48
+ export function createInstallPlan(input) {
49
+ if (!input || !Array.isArray(input.components) || !input.sourceRoot) throw new Error('Invalid backend install plan');
50
+ const contract = JSON.parse(readFileSync(join(input.sourceRoot, 'scripts/components.json'), 'utf8'));
51
+ const configureProviders = input.configureProviders === true || input.configureProviders === 'true';
52
+ const providers = String(input.providers || '').split(',').filter(Boolean);
53
+ const components = input.components.map((entry) => ({
54
+ id: String(entry.id), name: String(entry.name), type: String(entry.type),
55
+ currentState: String(entry.currentState), desired: entry.desired === true || entry.desired === 'true',
56
+ backendAction: String(entry.backendAction).toLowerCase(), target: resolve(entry.target),
57
+ ownership: String(entry.ownership), version: String(entry.version || ''),
58
+ availableVersion: String(entry.availableVersion || ''), compatibility: String(entry.compatibility),
59
+ detail: String(entry.detail || ''),
60
+ prerequisites: (contract.prerequisites || []).filter((requirement) =>
61
+ (!requirement.component || requirement.component === entry.id) &&
62
+ (requirement.key !== 'codex-or-vscode' || (configureProviders && providers.includes('codex')))),
63
+ snapshot: targetFingerprint(entry.target, entry.type),
64
+ }));
65
+ const configPaths = [...new Set(input.configurationPaths || [])].map((path) => resolve(path)).sort();
66
+ const configuration = configPaths.map((path) => ({ path,
67
+ snapshot: existsSync(path) ? digest(readFileSync(path)) : 'MISSING' }));
68
+ const seenTargets = new Set(components.map((entry) => entry.target));
69
+ const additionalTargets = (input.additionalTargets || []).filter((entry) => {
70
+ const target = resolve(entry.target);
71
+ if (seenTargets.has(target)) return false;
72
+ seenTargets.add(target); return true;
73
+ }).map((entry) => ({ id: entry.id, target: resolve(entry.target), type: entry.type,
74
+ snapshot: targetFingerprint(entry.target, entry.type) }));
75
+ const source = ['install.ps1', 'install.sh', 'verify.ps1', 'verify.sh', 'scripts/components.json',
76
+ 'scripts/afyx-install-contract.mjs', 'scripts/afyx-npm-installer.mjs']
77
+ .map((path) => [path, digest(readFileSync(join(input.sourceRoot, path)))]);
78
+ const plan = { schema: 'AfyxInstallPlan/v1', preset: input.preset,
79
+ providers, scope: input.scope, configureProviders,
80
+ workspaceRoot: resolve(input.workspaceRoot), platform: input.platform,
81
+ components, additionalTargets, configuration, source, warnings: input.warnings || [], blockers: input.blockers || [],
82
+ policy: { contextOptIn: process.env.AFYX_CONTEXT_OPT_IN ?? '' } };
83
+ return { ...plan, fingerprint: digest(JSON.stringify(plan)) };
84
+ }
85
+
86
+ export function encodeContract(value) {
87
+ return `AFYX_CONTRACT=${Buffer.from(JSON.stringify(value)).toString('base64')}`;
88
+ }
89
+
90
+ export function decodeContract(output, schema) {
91
+ const matches = [...String(output).matchAll(/^AFYX_CONTRACT=([A-Za-z0-9+/=]+)\r?$/gm)];
92
+ if (matches.length !== 1) throw new Error('Backend did not return exactly one structured contract');
93
+ const value = JSON.parse(Buffer.from(matches[0][1], 'base64').toString('utf8'));
94
+ if (value.schema !== schema) throw new Error(`Unexpected backend contract: ${value.schema}`);
95
+ return value;
96
+ }
97
+
98
+ function main(args) {
99
+ const mode = args.shift();
100
+ if (mode === 'plan') {
101
+ const input = JSON.parse(readFileSync(0, 'utf8').replace(/^\uFEFF/, ''));
102
+ const plan = createInstallPlan(input);
103
+ if (input.expectedFingerprint && input.expectedFingerprint !== plan.fingerprint) throw new Error('PLAN_CHANGED: installation state changed; review a new plan before applying');
104
+ process.stdout.write(`${encodeContract(plan)}\n`);
105
+ } else if (mode === 'plan-rows') {
106
+ const [preset, providers, scope, configureProviders, workspaceRoot, sourceRoot, platform, expectedFingerprint, ...rest] = args;
107
+ const input = { preset, providers, scope, configureProviders, workspaceRoot, sourceRoot, platform, expectedFingerprint, components: [], additionalTargets: [], configurationPaths: [], blockers: [] };
108
+ while (rest.length) {
109
+ const kind = rest.shift();
110
+ if (kind === '--config') input.configurationPaths.push(rest.shift());
111
+ else if (kind === '--block') input.blockers.push(rest.shift());
112
+ else if (kind === '--extra-target') {
113
+ const [id, type, target] = rest.splice(0, 3);
114
+ if (!target) throw new Error('Incomplete additional target');
115
+ input.additionalTargets.push({ id, type, target });
116
+ }
117
+ else if (kind === '--component') {
118
+ if (rest.length < 12) throw new Error('Incomplete backend component row');
119
+ const [id, name, type, currentState, desired, backendAction, target, ownership, version, availableVersion, compatibility, detail] = rest.splice(0, 12);
120
+ input.components.push({ id, name, type, currentState, desired, backendAction, target, ownership, version, availableVersion, compatibility, detail });
121
+ } else throw new Error(`Unknown plan row: ${kind}`);
122
+ }
123
+ const plan = createInstallPlan(input);
124
+ if (expectedFingerprint && expectedFingerprint !== plan.fingerprint) throw new Error('PLAN_CHANGED: installation state changed; review a new plan before applying');
125
+ process.stdout.write(`${encodeContract(plan)}\n`);
126
+ } else if (mode === 'verification') {
127
+ const rows = JSON.parse(readFileSync(0, 'utf8').replace(/^\uFEFF/, ''));
128
+ process.stdout.write(`${encodeContract({ schema: 'AfyxVerification/v1', rows })}\n`);
129
+ } else if (mode === 'verification-rows') {
130
+ if (args.length % 3) throw new Error('Incomplete verification row');
131
+ const rows = [];
132
+ while (args.length) { const [state, name, detail] = args.splice(0, 3); rows.push({ state, name, detail }); }
133
+ process.stdout.write(`${encodeContract({ schema: 'AfyxVerification/v1', rows })}\n`);
134
+ } else throw new Error('Unknown install contract operation');
135
+ }
136
+
137
+ if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
138
+ try { main(process.argv.slice(2)); } catch (error) { console.error(error.message); process.exitCode = 3; }
139
+ }