@aifabrix/builder 2.54.1 → 2.55.0

package/lib/utils/external-system-readiness-compact-display.js

@@ -29,12 +29,33 @@ const PILLAR_LABELS = Object.freeze({
   governance: 'Governance'
 });
 
+/** Connected System lifecycle labels — same Draft / Published / Archived as the web. */
+const CONNECTED_SYSTEM_LIFECYCLE_LABELS = Object.freeze({
+  draft: 'Draft',
+  published: 'Published',
+  archived: 'Archived',
+  deployed: 'Published'
+});
+
+/**
+ * Product lifecycle label, or null when the value is not Draft/Published/Archived
+ * (controller `active` is not Published).
+ * @param {string|null|undefined} status
+ * @returns {string|null}
+ */
+function formatConnectedSystemLifecycleLabel(status) {
+  const raw = String(status || '').trim().toLowerCase();
+  return CONNECTED_SYSTEM_LIFECYCLE_LABELS[raw] || null;
+}
+
 /**
  * @param {string|null|undefined} status
  * @returns {string}
  */
 function formatLifecycleLabel(status) {
   const raw = String(status || 'unknown').trim().toLowerCase();
+  const lifecycle = formatConnectedSystemLifecycleLabel(raw);
+  if (lifecycle) return lifecycle;
   if (!raw || raw === 'unknown') return 'Unknown';
   return raw.charAt(0).toUpperCase() + raw.slice(1);
 }
@@ -159,8 +180,14 @@ function resolveManifestAuthMethod(systemCfg) {
  * @returns {string}
  */
 function resolveConnectedSystemStatus(opts = {}) {
-  const fromPub = opts.publication?.system?.status;
   const fromGet = opts.systemFromDataplane?.status;
+  if (fromGet) {
+    return formatLifecycleLabel(fromGet);
+  }
+  if (opts.command === 'upload') {
+    return formatLifecycleLabel('draft');
+  }
+  const fromPub = opts.publication?.system?.status;
   return formatLifecycleLabel(fromGet || fromPub || opts.status);
 }
 
@@ -307,6 +334,8 @@ function logCompactTip(opts) {
 
 module.exports = {
   PILLAR_LABELS,
+  CONNECTED_SYSTEM_LIFECYCLE_LABELS,
+  formatConnectedSystemLifecycleLabel,
   formatLifecycleLabel,
   truncateKeyList,
   formatCredentialPushLine,

package/lib/utils/external-system-validators.js

@@ -52,7 +52,8 @@ function validateFieldMappingExpression(expression) {
     'replace',
     'join',
     'split',
-    'normalizeWhitespace'
+    'normalizeWhitespace',
+    'index'
   ];
   for (const trans of transformations) {
     const transName = trans.split('(')[0].trim();

package/lib/utils/help-builder.js

@@ -80,6 +80,7 @@ const CATEGORIES = [
       { name: 'resource-type' },
       { name: 'role' },
       { name: 'role-assistant' },
+      { name: 'search' },
       { name: 'evidence-kind' },
       { name: 'enterprise-knowledge' },
       { name: 'identity' },
@@ -133,7 +134,8 @@ const CATEGORIES = [
       { name: 'dev' },
       { name: 'secret' },
       { name: 'npm', term: 'npm config' },
-      { name: 'secure' }
+      { name: 'secure' },
+      { name: 'agent-kit' }
     ]
   }
 ];

package/lib/utils/schema-loader.js

@@ -19,6 +19,7 @@ const addFormats = require('ajv-formats');
 let externalSystemValidator = null;
 let externalDataSourceValidator = null;
 let roleAssistantSettingsValidator = null;
+let roleAssistantTestCaseValidator = null;
 
 /**
  * Reset validators cache (for testing)
@@ -28,6 +29,7 @@ function resetValidators() {
   externalSystemValidator = null;
   externalDataSourceValidator = null;
   roleAssistantSettingsValidator = null;
+  roleAssistantTestCaseValidator = null;
 }
 
 /**
@@ -172,6 +174,37 @@ function loadRoleAssistantSettingsSchema() {
   return roleAssistantSettingsValidator;
 }
 
+/**
+ * Loads and compiles role-assistant test-case schema.
+ * @function loadRoleAssistantTestCaseSchema
+ * @returns {Function}
+ */
+function loadRoleAssistantTestCaseSchema() {
+  if (roleAssistantTestCaseValidator) {
+    return roleAssistantTestCaseValidator;
+  }
+
+  const schemaPath = path.join(__dirname, '..', 'schema', 'role-assistant-test-case.schema.json');
+  let schema;
+  try {
+    schema = JSON.parse(fsRealSync.readFileSync(schemaPath, 'utf8'));
+  } catch (error) {
+    try {
+      schema = require('../schema/role-assistant-test-case.schema.json');
+    } catch {
+      if (error && error.code === 'ENOENT') {
+        throw new Error(`Role assistant test-case schema not found: ${schemaPath}`);
+      }
+      throw new Error(`Invalid JSON in role-assistant-test-case.schema.json: ${error.message}`);
+    }
+  }
+
+  const ajv = new Ajv({ allErrors: true, verbose: true, strict: false, strictSchema: false });
+  addFormats(ajv);
+  roleAssistantTestCaseValidator = ajv.compile(schema);
+  return roleAssistantTestCaseValidator;
+}
+
 /**
  * Detect schema type from $id field
  * @param {Object} parsed - Parsed JSON object
@@ -194,6 +227,9 @@ function detectFromId(parsed) {
   if (parsed.$id.includes('role-assistant-settings')) {
     return 'role-assistant-settings';
   }
+  if (parsed.$id.includes('role-assistant-test-case')) {
+    return 'role-assistant-test-case';
+  }
 
   return null;
 }
@@ -388,6 +424,7 @@ module.exports = {
   loadExternalSystemSchema,
   loadExternalDataSourceSchema,
   loadRoleAssistantSettingsSchema,
+  loadRoleAssistantTestCaseSchema,
   registerExternalDatasourceAjvDependencies,
   detectSchemaType,
   detectSchemaTypeFromParsed,

package/lib/validation/validate-external-file.js

@@ -13,7 +13,8 @@ const yaml = require('js-yaml');
 const {
   loadExternalSystemSchema,
   loadExternalDataSourceSchema,
-  loadRoleAssistantSettingsSchema
+  loadRoleAssistantSettingsSchema,
+  loadRoleAssistantTestCaseSchema
 } = require('../utils/schema-loader');
 const { formatValidationErrors } = require('../utils/error-formatter');
 const { validateFieldReferences } = require('../datasource/field-reference-validator');
@@ -60,6 +61,9 @@ function getValidatorForType(normalizedType) {
   if (normalizedType === 'role-assistant-settings') {
     return loadRoleAssistantSettingsSchema();
   }
+  if (normalizedType === 'role-assistant-test-case') {
+    return loadRoleAssistantTestCaseSchema();
+  }
   throw new Error(`Unknown file type: ${normalizedType}`);
 }
 

package/lib/validation/validate.js

@@ -27,6 +27,7 @@ const {
   isRoleAssistantWorkspace,
   isEnterpriseKnowledgeWorkspace
 } = require('../utils/platform-shell-package');
+const { validateRoleAssistantPackage } = require('../role-assistant/package-validate');
 
 /**
  * Validates a file path (detects type and validates)
@@ -335,7 +336,7 @@ function skippedComponentsStep() {
   return { valid: true, errors: [], warnings: [], files: [], skipped: true };
 }
 
-async function validatePlatformShellPackage(appName, baseDir, appPath, options) {
+async function validatePlatformShellPackage(_appName, baseDir, appPath, _options) {
   if (isEnterpriseKnowledgeWorkspace(baseDir)) {
     return aggregateExternalValidationSteps({
       application: skippedValidationStep(),
@@ -348,7 +349,7 @@ async function validatePlatformShellPackage(appName, baseDir, appPath, options)
   }
   return aggregateExternalValidationSteps({
     application: skippedValidationStep(),
-    components: await validateComponentsStep(appName, options),
+    components: await validateRoleAssistantPackage(appPath),
     manifest: skippedValidationStep()
   }, appPath);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aifabrix/builder",
-  "version": "2.54.1",
+  "version": "2.55.0",
   "description": "AI Fabrix Builder — CLI and developer scripts (pnpm + af)",
   "main": "lib/index.js",
   "bin": {

package/templates/agent-kit/adapters/claude/nested.CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/templates/agent-kit/adapters/claude/root.CLAUDE.md

@@ -0,0 +1,5 @@
+@AGENTS.md
+
+Delivery skills: `/aifabrix-plan`, `/aifabrix-connected-system`, `/aifabrix-role-assistant`, `/aifabrix-prove`.
+The skill body lives under `.agents/skills/`. Do not invent a parallel workflow.
+Local vs SSH (tmux, Remote Control): `.agents/skills/shared/hosts.md`.

package/templates/agent-kit/adapters/cursor/commands/cust-0-plan.md

@@ -0,0 +1,5 @@
+# cust-0-plan
+
+Compatibility alias for skill **aifabrix-plan**. Optional system key.
+
+Contains no business rules. Prefer `/aifabrix-plan` on fresh installs.

package/templates/agent-kit/adapters/cursor/commands/cust-1-validate.md

@@ -0,0 +1,5 @@
+# cust-1-validate
+
+Compatibility alias for skill **aifabrix-connected-system** phase `validate`.
+
+Contains no business rules. Prefer `/aifabrix-connected-system`.

package/templates/agent-kit/adapters/cursor/commands/cust-2-build.md

@@ -0,0 +1,5 @@
+# cust-2-build
+
+Compatibility alias for skill **aifabrix-connected-system** phase `build`.
+
+Contains no business rules. Prefer `/aifabrix-connected-system`.

package/templates/agent-kit/adapters/cursor/commands/cust-3-push.md

@@ -0,0 +1,5 @@
+# cust-3-push
+
+Compatibility alias for skill **aifabrix-connected-system** phase `publish`.
+
+Contains no business rules. Prefer `/aifabrix-connected-system`.

package/templates/agent-kit/adapters/cursor/commands/cust-biz-1-validate.md

@@ -0,0 +1,5 @@
+# cust-biz-1-validate
+
+Compatibility alias for skill **aifabrix-prove** phase `validate`.
+
+Contains no business rules. Prefer `/aifabrix-prove`.

package/templates/agent-kit/adapters/cursor/commands/cust-biz-2-build.md

@@ -0,0 +1,5 @@
+# cust-biz-2-build
+
+Compatibility alias for skill **aifabrix-prove** phase `build`.
+
+Contains no business rules. Prefer `/aifabrix-prove`.

package/templates/agent-kit/adapters/cursor/commands/cust-biz-3-prove.md

@@ -0,0 +1,5 @@
+# cust-biz-3-prove
+
+Compatibility alias for skill **aifabrix-prove** phase `prove`.
+
+Contains no business rules. Prefer `/aifabrix-prove`.

package/templates/agent-kit/agent-kit.yaml

@@ -0,0 +1,45 @@
+schemaVersion: "1"
+kitVersion: "1.1.1"
+minimumBuilderVersion: "2.54.2"
+skills:
+  - aifabrix-plan
+  - aifabrix-connected-system
+  - aifabrix-role-assistant
+  - aifabrix-prove
+managed:
+  - source: skills
+    target: .agents/skills
+    mode: tree
+  - source: instructions/root.AGENTS.md
+    target: AGENTS.md
+    mode: managed-section
+  - source: instructions/integration.AGENTS.md
+    target: integration/AGENTS.md
+    mode: managed-section
+  - source: instructions/role-assistant.AGENTS.md
+    target: role-assistant/AGENTS.md
+    mode: managed-section
+  - source: instructions/AGENTKIT.md
+    target: AGENTKIT.md
+    mode: file
+    render: hosts
+  - source: workspace/README.md
+    target: README.md
+    mode: if-missing
+optional:
+  - source: adapters/cursor/commands
+    target: .cursor/commands
+    mode: tree
+    when: v1-migration
+  - source: adapters/claude/root.CLAUDE.md
+    target: CLAUDE.md
+    mode: managed-section
+    when: host-claude
+  - source: adapters/claude/nested.CLAUDE.md
+    target: integration/CLAUDE.md
+    mode: managed-section
+    when: host-claude
+  - source: adapters/claude/nested.CLAUDE.md
+    target: role-assistant/CLAUDE.md
+    mode: managed-section
+    when: host-claude

package/templates/agent-kit/instructions/AGENTKIT.md

@@ -0,0 +1,83 @@
+# Agent Kit
+
+Builder-owned. `aifabrix agent-kit update` refreshes this file. If workspace `README.md` is missing, install/update creates it. An existing README is never overwritten.
+
+## Install
+
+From this git repository (Builder CLI on PATH):
+
+```bash
+aifabrix agent-kit install --host {{hostFlag}}{{#if autoApprove}} --approve-all --yes{{/if}}
+aifabrix agent-kit status
+```
+
+`--host` may be `all`, `cursor`, `codex`, or `claude`. Shared skills always land in `.agents/skills/`.
+{{#if claude}}
+`claude` also writes `CLAUDE.md` and thin `.claude/skills` pointers.
+{{/if}}
+
+## Update
+
+When this CLI is newer than the workspace kit, or you add or switch coding hosts:
+
+```bash
+aifabrix agent-kit update --host {{hostFlag}}{{#if autoApprove}} --approve-all --yes{{/if}}
+aifabrix agent-kit validate
+```
+
+Omit `--host` to keep the hosts already recorded. Pass `--host` when the developer changes Cursor / Claude Code / Codex.
+
+New workspace instead of an existing repo: `aifabrix agent-kit init <workspaceName> --host {{hostFlag}}`.
+
+## Activate hosts
+
+Install the coding app, then sign in. How to **run** it locally or over SSH is in `.agents/skills/shared/hosts.md` (linked from every Agent Kit skill).
+{{#if autoApprove}}
+
+On TTY, install **asks** to auto-approve tool permissions **in this workspace**. Claude Code also allows `Bash(aifabrix *)` (delivery CLI) and `Read(~/**)` (home Read). Silent (`--yes` / non-TTY) writes them; `--skip-approve-all` skips.
+{{#if claude}}
+- Claude Code writes `.claude/settings.local.json` (gitignored).
+{{/if}}
+{{#if codex}}
+- Codex writes `.codex/config.toml` (gitignored).
+{{/if}}
+{{/if}}
+{{#if cursor}}
+
+### Cursor
+
+Open this folder in Cursor (this machine, or Cursor Remote SSH). Skills: `/aifabrix-plan`, `/aifabrix-connected-system`, `/aifabrix-role-assistant`, `/aifabrix-prove`.
+{{/if}}
+{{#if claude}}
+
+### Claude Code
+
+```bash
+curl -fsSL https://claude.ai/install.sh | bash
+claude auth login
+```
+
+Skills: same `/aifabrix-*` names. First `claude` must run inside this workspace, not your home directory.
+{{/if}}
+{{#if codex}}
+
+### Codex
+
+Install the Codex CLI, then sign in with your Codex account. Skills: `$aifabrix-plan` (and the other `$aifabrix-*` names). Codex reads `AGENTS.md`.
+{{/if}}
+
+## Auth for delivery CLI
+
+```bash
+aifabrix auth status
+```
+
+If still unauthenticated, run `aifabrix login` (the agent cannot log in for you).
+
+## How to start
+
+After this folder is open in the coding host, follow **How to start** in the workspace `README.md` (how to use prompts, then plan → validate/build → publish, then Role Assistant).
+
+## Docs
+
+Agents load the public index from `AGENTS.md`. Humans: the workspace `README.md` Docs section.

package/templates/agent-kit/instructions/integration.AGENTS.md

@@ -0,0 +1,25 @@
+# Connected System laws
+
+Load when working under `integration/`. Follow skill `aifabrix-connected-system` and its references.
+
+## Builder-first packages
+
+Generate EDS with BID apply, wizard, repair, or `aifabrix json`. Do not hand-seed greenfield `*-system.json` / `*-datasource-*.json` / `application.*`. Manual deltas need `INTEGRATION_CHANGELOG.md`.
+
+## Contract
+
+- `exposed` needs `filterable`, real `profiles`, and `schema`. Schema-only is not BUILT.
+- Every `exposed.filterable` field has `metadataSchema.properties.<field>.filter: true`.
+- Foreign keys sit on the child (`from`) only; `targetFields: ["externalId"]`. No reverse parent FKs. Empty FK on business storage is not READY/BUILT unless config, logs, documented root, or self-tree (field only).
+- Partitioned and current-state views need FK + dimensions (`type: fk`) + usually `accessControl.abac.applicability: required`.
+- `roles[].value` must be a COM catalog key from `aifabrix role list`. Never invent `*-reader`.
+
+## Publish
+
+`aifabrix upload` is a draft application. `aifabrix deploy` publishes. Dataplane `show --online` status **published** is truth. Ignore upload banners that say Published.
+
+## Safety
+
+One designated mutation subject from the integration README. Credential-deferred live E2E may skip honestly; failed sync with a secret present is FAIL. See `production-safety.md` in the connected-system skill.
+
+Do not bulk-sync views as storage. Do not invent a Connected System key starting with `ra-` or `ek-`.

package/templates/agent-kit/instructions/role-assistant.AGENTS.md

@@ -0,0 +1,22 @@
+# Role Assistant laws
+
+Load when working under `role-assistant/`. Follow skill `aifabrix-role-assistant`.
+
+## Packages are separate
+
+Connected Systems live under `integration/<systemKey>/`.
+Role Assistants live under `role-assistant/ra-<catalogRole>/`.
+Do not keep CS manifests inside an RA folder. Do not run `aifabrix convert` on RA packages.
+
+## Authority
+
+The catalog Business Role must exist (`aifabrix role list`). Package key is `ra-<catalogRole>`.
+Download an existing assistant before editing generated yaml.
+Candidate Evidence is not certified Evidence.
+Missing CS capability is fixed on the Connected System, then re-subscribed — never as an RA-local operation.
+
+## Publish and prove
+
+CS must be dataplane **published** (deploy, not upload-only) before subscription-driven capabilities exist.
+Do not upload or deploy an RA unless the user explicitly asks in this turn.
+Agent prompts never supply the actor. Verified backend identity is authoritative.

package/templates/agent-kit/instructions/root.AGENTS.md

@@ -0,0 +1,37 @@
+# AI Fabrix customer workspace
+
+This repository delivers Connected Systems and Role Assistants with the Builder CLI.
+Do not edit platform product source (`aifabrix-dataplane`, `aifabrix-miso`, `aifabrix-builder`) from this workspace.
+
+## Ownership
+
+| Owner | Holds |
+| --- | --- |
+| This repository | Customer facts, specifications, plans, fixtures, tests, learning |
+| Agent Kit | Reusable delivery behavior (installed skills and these managed sections) |
+| Builder CLI | Commands, package validation, install/update of this kit |
+| Dataplane / controller | Auth, RBAC, ABAC, Protection, publication, Runtime execution |
+
+Vendor limits, tenant ids, credentials, PII stance, partitions, and the designated mutation subject live only in `integration/<systemKey>/README.md`.
+
+## Secrets
+
+Use `kv://` and `aifabrix secret`. Never store, print, ask for, or commit secret values.
+Missing vendor secret: upload a draft, print the Authentication tab link, stop. Do not collect credentials in chat.
+
+## Verdicts
+
+`PLAN_READY` · `READY` · `BUILT` · `PASS` · `PASS_WITH_SKIPS` · `NEEDS_DECISIONS` · `NEEDS_FIXES` · `BLOCKED` · `ABORTED`
+
+Do not collapse these into a generic success boolean. Do not start the next lifecycle phase unless the user selects it.
+
+## Coding hosts
+
+Cursor, Claude Code, and Codex — local machine or SSH (tmux, Claude Remote Control): `.agents/skills/shared/hosts.md`.
+Install and sign-in: `AGENTKIT.md`.
+
+## Docs
+
+Integrator hub: https://docs.aifabrix.ai/docs/build-ai-ready-systems
+CLI workflow: https://docs.aifabrix.ai/docs/build-ai-ready-systems-validate-test-cli-workflow
+Index: https://docs.aifabrix.ai/llms.txt