@aifabrix/builder 2.56.0 → 2.57.0

package/lib/schema/installation-environment.schema.json

@@ -0,0 +1,601 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/esystemsdev/aifabrix-builder/refs/heads/main/lib/schema/installation-environment.schema.json",
+  "title": "AI Fabrix Installation Environment File",
+  "description": "Committed, non-secret infrastructure/<resource-group>/environment-dev|tst|pro.json. Inherited shared values name environment-infra.json as their source; request is the exact non-secret Miso deploy projection.",
+  "metadata": {
+    "key": "installation-environment-schema",
+    "name": "Installation Environment File Schema",
+    "description": "JSON schema for installation workspace environment-dev.json, environment-tst.json and environment-pro.json",
+    "version": "2.0.0",
+    "type": "schema",
+    "category": "infrastructure",
+    "author": "AI Fabrix Team",
+    "createdAt": "2026-09-16T00:00:00Z",
+    "updatedAt": "2026-09-16T00:00:00Z",
+    "compatibility": {
+      "minVersion": "2.0.0",
+      "maxVersion": "2.0.0",
+      "deprecated": false
+    },
+    "tags": [
+      "schema",
+      "environment",
+      "installation"
+    ],
+    "dependencies": [
+      "environment-deploy-request.schema.json"
+    ],
+    "changelog": [
+      {
+        "version": "2.0.0",
+        "date": "2026-09-16T00:00:00Z",
+        "breaking": false,
+        "changes": [
+          "Initial installation environment file schema"
+        ]
+      }
+    ]
+  },
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "environment",
+    "name",
+    "preset",
+    "controllerUrl",
+    "serviceName",
+    "location",
+    "subscriptionId",
+    "resourceGroupName",
+    "networking",
+    "allowedIPs",
+    "infrastructureAccess",
+    "applications",
+    "variables",
+    "request",
+    "deployment"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": "2.0.0"
+    },
+    "environment": {
+      "type": "object",
+      "required": [
+        "value",
+        "source",
+        "description"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "value": {
+          "enum": [
+            "dev",
+            "tst",
+            "pro"
+          ]
+        },
+        "source": {
+          "type": "string",
+          "minLength": 1
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "name": {
+      "type": "object",
+      "required": [
+        "value",
+        "source",
+        "description"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "value": {
+          "type": "string",
+          "minLength": 1
+        },
+        "source": {
+          "type": "string",
+          "minLength": 1
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "preset": {
+      "type": "object",
+      "required": [
+        "value",
+        "source",
+        "description"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "value": {
+          "enum": [
+            "s",
+            "m",
+            "l",
+            "xl"
+          ]
+        },
+        "source": {
+          "type": "string",
+          "minLength": 1
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "controllerUrl": {
+      "type": "object",
+      "required": [
+        "value",
+        "source",
+        "description"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "value": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "pattern": "^https://"
+        },
+        "source": {
+          "type": "string",
+          "minLength": 1
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1
+        },
+        "valueFromEnv": {
+          "const": "CONTROLLER_URL"
+        }
+      }
+    },
+    "serviceName": {
+      "type": "object",
+      "required": [
+        "source",
+        "description"
+      ],
+      "additionalProperties": false,
+      "anyOf": [
+        {
+          "required": [
+            "value"
+          ]
+        },
+        {
+          "required": [
+            "inheritFrom"
+          ]
+        }
+      ],
+      "properties": {
+        "value": {
+          "type": "string",
+          "pattern": "^[a-z0-9-]{2,40}$"
+        },
+        "inheritFrom": {
+          "type": "string",
+          "pattern": "^[A-Za-z]+(\\.[A-Za-z]+)*$"
+        },
+        "source": {
+          "type": "string",
+          "minLength": 1
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "location": {
+      "type": "object",
+      "required": [
+        "source",
+        "description"
+      ],
+      "additionalProperties": false,
+      "anyOf": [
+        {
+          "required": [
+            "value"
+          ]
+        },
+        {
+          "required": [
+            "inheritFrom"
+          ]
+        }
+      ],
+      "properties": {
+        "value": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+$"
+        },
+        "inheritFrom": {
+          "type": "string",
+          "pattern": "^[A-Za-z]+(\\.[A-Za-z]+)*$"
+        },
+        "source": {
+          "type": "string",
+          "minLength": 1
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "subscriptionId": {
+      "type": "object",
+      "required": [
+        "source",
+        "description"
+      ],
+      "additionalProperties": false,
+      "anyOf": [
+        {
+          "required": [
+            "value"
+          ]
+        },
+        {
+          "required": [
+            "inheritFrom"
+          ]
+        }
+      ],
+      "properties": {
+        "value": {
+          "type": "string",
+          "pattern": "^[0-9a-fA-F-]{36}$"
+        },
+        "inheritFrom": {
+          "type": "string",
+          "pattern": "^[A-Za-z]+(\\.[A-Za-z]+)*$"
+        },
+        "source": {
+          "type": "string",
+          "minLength": 1
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "resourceGroupName": {
+      "type": "object",
+      "required": [
+        "value",
+        "source",
+        "description"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "value": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "pattern": "^[a-zA-Z0-9._()-]{1,90}$"
+        },
+        "source": {
+          "type": "string",
+          "minLength": 1
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "networking": {
+      "type": "object",
+      "required": [
+        "value",
+        "source",
+        "description"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "value": {
+          "type": "object"
+        },
+        "source": {
+          "type": "string",
+          "minLength": 1
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "allowedIPs": {
+      "type": "object",
+      "required": [
+        "value",
+        "source",
+        "description"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "value": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "source": {
+          "type": "string",
+          "minLength": 1
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "infrastructureAccess": {
+      "type": "object",
+      "required": [
+        "value",
+        "source",
+        "description"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "value": {
+          "type": "array",
+          "items": {
+            "type": "object"
+          }
+        },
+        "source": {
+          "type": "string",
+          "minLength": 1
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "applications": {
+      "type": "object",
+      "required": [
+        "value",
+        "source",
+        "description"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "value": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z0-9-]+$"
+          }
+        },
+        "source": {
+          "type": "string",
+          "minLength": 1
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "variables": {
+      "type": "object",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^[A-Z_][A-Z0-9_]*$": {
+          "type": "object",
+          "required": [
+            "valueFromEnv",
+            "requiredBy",
+            "source",
+            "description"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "valueFromEnv": {
+              "type": "string",
+              "pattern": "^[A-Z_][A-Z0-9_]*$"
+            },
+            "requiredBy": {
+              "type": "array",
+              "uniqueItems": true,
+              "items": {
+                "type": "string"
+              }
+            },
+            "source": {
+              "type": "string",
+              "minLength": 1
+            },
+            "description": {
+              "type": "string",
+              "minLength": 1
+            },
+            "resolution": {
+              "enum": [
+                "resolved",
+                "missing"
+              ]
+            }
+          }
+        }
+      }
+    },
+    "request": {
+      "type": "object",
+      "required": [
+        "value",
+        "source",
+        "description"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "value": {
+          "anyOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "environmentConfig"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "environmentConfig": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": [
+                    "key",
+                    "environment",
+                    "preset",
+                    "serviceName",
+                    "location",
+                    "resourceGroupName",
+                    "subscriptionId"
+                  ],
+                  "properties": {
+                    "key": {
+                      "type": "string"
+                    },
+                    "environment": {
+                      "type": "string"
+                    },
+                    "preset": {
+                      "type": "string"
+                    },
+                    "serviceName": {
+                      "type": "string"
+                    },
+                    "location": {
+                      "type": "string"
+                    },
+                    "resourceGroupName": {
+                      "type": "string"
+                    },
+                    "subscriptionId": {
+                      "type": "string"
+                    }
+                  }
+                }
+              }
+            }
+          ]
+        },
+        "source": {
+          "type": "string",
+          "minLength": 1
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "deployment": {
+      "type": "object",
+      "required": [
+        "status",
+        "id"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "status": {
+          "type": "object",
+          "required": [
+            "value",
+            "source",
+            "description"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "value": {
+              "enum": [
+                "not-deployed",
+                "running",
+                "completed",
+                "failed",
+                "error",
+                "cancelled",
+                "timeout"
+              ]
+            },
+            "source": {
+              "type": "string",
+              "minLength": 1
+            },
+            "description": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        },
+        "id": {
+          "type": "object",
+          "required": [
+            "value",
+            "source",
+            "description"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "value": {
+              "type": [
+                "string",
+                "null"
+              ]
+            },
+            "source": {
+              "type": "string",
+              "minLength": 1
+            },
+            "description": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        },
+        "updatedAt": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "format": "date-time"
+        },
+        "error": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    }
+  }
+}

package/lib/utils/variable-transformer.js

@@ -301,6 +301,9 @@ function transformSimpleOptionalFields(variables, transformed) {
   if (variables.externalIntegration) {
     transformed.externalIntegration = variables.externalIntegration;
   }
+  if (variables.required !== undefined) {
+    transformed.required = variables.required;
+  }
 }
 
 /**

package/lib/validation/required-variables.js

@@ -0,0 +1,41 @@
+/**
+ * @fileoverview Semantic checks for the application top-level `required` variable list:
+ * every name must be declared by the manifest configuration and have a resolvable source.
+ * Shape (array, unique, name pattern) is enforced by application-schema.json.
+ * @author AI Fabrix Team
+ * @version 2.0.0
+ */
+
+'use strict';
+
+function hasResolvableValue(item) {
+  if (item.location === 'keyvault') return typeof item.value === 'string' && item.value !== '';
+  return (typeof item.value === 'string' && item.value !== '') || Boolean(item.portalInput);
+}
+
+/**
+ * Validates top-level `required` names against the deployment manifest configuration.
+ * @param {Object} manifest - Deployment manifest (application schema shape)
+ * @returns {string[]} Error messages (empty when valid or when `required` is absent)
+ */
+function validateRequiredVariables(manifest) {
+  const required = manifest && manifest.required;
+  if (!Array.isArray(required) || required.length === 0) return [];
+  const byName = new Map();
+  for (const item of Array.isArray(manifest.configuration) ? manifest.configuration : []) {
+    if (item && typeof item.name === 'string') byName.set(item.name, item);
+  }
+  const errors = [];
+  for (const name of required) {
+    if (typeof name !== 'string') continue;
+    const item = byName.get(name);
+    if (!item) {
+      errors.push(`required: ${name} is not declared in the application configuration (env.template)`);
+    } else if (!hasResolvableValue(item)) {
+      errors.push(`required: ${name} has no value or portal input, so it cannot resolve for the target`);
+    }
+  }
+  return errors;
+}
+
+module.exports = { validateRequiredVariables };

package/lib/validation/validator.js

@@ -24,6 +24,7 @@ const { loadConfigFile } = require('../utils/config-format');
 const { validateAuthKvCoverage, validateAuthSecurityPathConsistency } = require('./env-template-auth');
 const { validateKvReferencesInLines } = require('./env-template-kv');
 
+const { validateRequiredVariables } = require('./required-variables');
 /**
  * Validates application config file against application schema
  * Provides detailed error messages for configuration issues
@@ -366,13 +367,15 @@ function validateDeploymentJson(deployment) {
   ajv.addSchema(externalDataSourceSchemaCopy, externalDataSourceSchema.$id);
   const validate = ajv.compile(applicationSchema);
   const valid = validate(deployment);
+  const schemaErrors = valid ? [] : formatValidationErrors(validate.errors, {
+    deploymentManifest: deployment,
+    rootData: deployment
+  });
+  const requiredErrors = validateRequiredVariables(deployment);
 
   return {
-    valid,
-    errors: valid ? [] : formatValidationErrors(validate.errors, {
-      deploymentManifest: deployment,
-      rootData: deployment
-    })
+    valid: valid && requiredErrors.length === 0,
+    errors: [...schemaErrors, ...requiredErrors]
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aifabrix/builder",
-  "version": "2.56.0",
+  "version": "2.57.0",
   "description": "AI Fabrix Builder — CLI and developer scripts (pnpm + af)",
   "main": "lib/index.js",
   "bin": {
@@ -24,6 +24,10 @@
     "dev-deploy": "node scripts/pnpm/dev-deploy.mjs",
     "af": "node scripts/pnpm/af.mjs",
     "check-quiet": "node scripts/pnpm/check-quiet.mjs",
+    "agent-skills:sync": "node scripts/pnpm/agent-skills-sync.mjs",
+    "agent-skills:check": "node scripts/pnpm/agent-skills-sync.mjs --check",
+    "agent-skills:sync:codex": "node scripts/pnpm/agent-skills-sync.mjs --codex-home",
+    "agent-skills:test": "node --test scripts/pnpm/agent-skills-sync.test.mjs",
     "check": "npm run lint && npm run test",
     "lint": "eslint . --ext .js",
     "lint:fix": "eslint . --ext .js --fix",