@aifabrix/builder 2.49.1 → 2.50.0

package/.cursor/process/README.md

@@ -0,0 +1,9 @@
+# Process documentation
+
+Canonical process descriptions for aifabrix-builder automation and release workflows.
+
+| Process | Description |
+| ------- | ----------- |
+| [deployment.md](./deployment.md) | NPM release: preflight, release branch CI, PR to `main`, publish and GitHub release |
+
+Command specs (agent-executable) live under [`.cursor/commands/`](../commands/).

package/.cursor/rules/deploy-rules/docker-image-ip-policy.mdc

@@ -0,0 +1,49 @@
+---
+description: Builder-api and platform app Docker image IP policy — staging, explicit COPY, content gate
+globs:
+  - builder/builder-api/Dockerfile
+  - templates/applications/builder-api/Dockerfile
+  - .dockerignore
+  - scripts/stage_builder_api_for_docker.js
+  - scripts/docker_image_content_gate.js
+  - lib/build/builder-api-docker-staging.js
+alwaysApply: false
+---
+
+# Docker image IP policy (builder-api)
+
+Customer-pullable **builder-api** images must contain **runtime orchestration only**, not the full Builder CLI monorepo.
+
+## Required pattern (builder-api)
+
+1. **Deny by default** — repo-root `.dockerignore` excludes dev trees from build context.
+2. **Stage on host** — `node scripts/stage_builder_api_for_docker.js` (also via `aifabrix build builder-api`) writes `docker-builder-api-staging/`.
+3. **Explicit COPY** — `builder/builder-api/Dockerfile` copies staging output only; never `COPY lib ./lib` or `COPY . .`.
+4. **Prove it** — `node scripts/docker_image_content_gate.js <image> builder-api` must pass before ACR push.
+5. **Non-root** — container runs as `appuser` (or documented service user).
+6. **No agent ACR build** — see `acr-build-restrictions.mdc` in miso builder rules; user runs registry build/push.
+
+## SSOT files
+
+| File | Role |
+| ---- | ---- |
+| `builder/builder-api/Dockerfile` | Canonical image definition |
+| `templates/applications/builder-api/Dockerfile` | Published via `npm run sync-json` only |
+| `scripts/stage_builder_api_for_docker.js` | Runtime allowlist + manifest |
+| `scripts/docker_image_content_gate.js` | Post-build forbidden-path gate |
+| `.dockerignore` | Build context hardening |
+
+## Forbidden in builder-api images
+
+- `/app/.cursor`, `/app/builder`, `/app/integration`, `/app/tests`, `/app/docs`, `/app/scripts`, `/app/packages`
+- `/app/bin/aifabrix.js` (full CLI entry)
+- `/app/templates/*` except `templates/openapi/` and `templates/external-system/` (runtime wizard/ReDoc only)
+- `*.md` under `/app/lib/`
+
+## Dev-reload
+
+`aifabrix run builder-api --reload` bind-mounts source for local dev. Image hardening applies to **production/ACR** builds only.
+
+## When changing runtime imports
+
+If `lib/programmatic/` or its transitive requires change, re-run staging manifest tests (`tests/scripts/stage_builder_api_for_docker.test.js`) and rebuild the image gate.

package/.cursor/rules/plan-rules/application-lifecycle.mdc

@@ -0,0 +1,30 @@
+---
+description: Mandatory application development lifecycle — semantic checklist before validate-plan and at close-out
+alwaysApply: true
+---
+
+# Application development lifecycle (mandatory)
+
+Every AI Fabrix product change must follow the full application development lifecycle before it is considered complete. This is law, not guidance.
+
+**Skill (SSOT):** `.cursor/skills/aifabrix-application-lifecycle/SKILL.md`
+
+Load `references/` files only when change class or repo requires them — do not inline repo overlays in chat unless applying them.
+
+## When agents must run it
+
+| Moment | Action |
+| --- | --- |
+| `/validate-plan` | Produce `## Application Development Lifecycle Coverage` under `## Plan Validation Report` |
+| `/validate-implementation` | Upgrade `planned` → `covered`; no `missing` on required areas; **implementation code validation law** on plan-touched paths (Pyright/IDE, 600/50 Python, 500/50 TS) — see skill `references/implementation-code-validation-law.md` |
+| Ad-hoc implementation (no plan) | Run abbreviated checklist per change-class matrix in the skill |
+
+## Integration with mechanical gates
+
+This rule does **not** replace `plan-validation-gate.mdc`, `plan-validate.js`, or repo `*-plan-validate` skills. It adds the **semantic coverage table** and **lifecycle decision** those gates do not emit today.
+
+Do not stamp `planValidatedStatus: validated` when lifecycle decision is `blocked` or `needs-human-answer`.
+
+## Repo plan-validate skills
+
+Each repo's `*-plan-validate` skill must invoke `aifabrix-application-lifecycle` as its **first semantic step** before architecture/reuse/testing gates.

package/.cursor/rules/plan-rules/plan-frontmatter.mdc

@@ -0,0 +1,35 @@
+---
+description: YAML frontmatter for .cursor/plans/*.plan.md
+globs: .cursor/plans/**/*
+alwaysApply: false
+---
+
+# Plan frontmatter (builder)
+
+## Required (new plans)
+
+| Field | Rules |
+| --- | --- |
+| `name` | Matches basename stem |
+| `overview` | Non-empty summary |
+| `status` | `draft` \| `review` \| `approved` \| `in_progress` \| `completed` \| `archived` |
+| `todos` | Non-empty; `id`, `content`, `status` |
+| `createdBy` | Display name on create |
+| `planType` | `code` \| `docs` \| `meta` |
+
+## Validation stamp (set by agent via plan-validate.js only)
+
+| Field | Values |
+| --- | --- |
+| `planValidatedStatus` | `validated` \| `needs-updates` \| `incomplete` |
+| `lastValidatedBy` | Display name |
+| `lastValidatedAt` | `YYYY-MM-DD` |
+
+## Approval (set by plan-approve.js only)
+
+| Field | Set when |
+| --- | --- |
+| `approvedBy` | User `approve-yes` on validate-plan |
+| `approvedAt` | Same run |
+
+Actor file: `~/.aifabrix/plan-actor.yaml`

package/.cursor/rules/plan-rules/plan-lifecycle.mdc

@@ -0,0 +1,31 @@
+---
+description: Cursor plan lifecycle phases and validation gate
+globs: .cursor/plans/**/*
+alwaysApply: false
+---
+
+# Plan lifecycle (builder)
+
+## Phases
+
+1. **Plan** — draft under `.cursor/plans/`
+2. **Validate** — `/validate-plan`, `builder-validate-plan` skill; semantic checklist: `aifabrix-application-lifecycle`
+3. **Approve** — `approve-plan` AskQuestion → `node scripts/plan-approve.js`
+4. **Implement** — edit `lib/`, templates, schemas (generators first)
+5. **Test** — `npm run build` → lint → test
+6. **Close** — `/validate-implementation`
+
+## Hard gate
+
+Do **not** implement until `planValidatedStatus: validated`. See `plan-validation-gate.mdc`.
+
+## CLI
+
+```bash
+node scripts/plan-set-actor.js "Name"
+node scripts/plan-validate.js <plan-id>
+node scripts/plan-approve.js <plan-id>
+node scripts/plan-run.js <plan-id>
+```
+
+Reports: `temp/plan-prevalidation/LATEST.md`, `temp/plan-validation/LATEST.md`

package/.cursor/rules/plan-rules/plan-validation-gate.mdc

@@ -0,0 +1,34 @@
+---
+description: Hard stop — no plan implementation until /validate-plan passes
+alwaysApply: true
+---
+
+# Plan validation gate (non-overrideable)
+
+Agents **must not** start implementation for a Cursor plan until pre-implementation validation is complete.
+
+## Blocked actions (until validated + approved for code plans)
+
+- Editing product code scoped to the plan (`lib/`, `bin/`, `templates/`, etc.)
+- Marking implementation todos `in_progress`
+- Running implementation without validated plan
+
+## Required before implementation
+
+1. **`/validate-plan`** completed with `## Plan Validation Report` status **`✅ VALIDATED`**
+2. Frontmatter **`planValidatedStatus: validated`** (set only by agent via `node scripts/plan-validate.js`)
+3. **`lastValidatedBy`** and **`lastValidatedAt`** set (same run)
+4. **`planType: code`** — user **`approve-yes`** on `approve-plan` AskQuestion → agent runs `node scripts/plan-approve.js`
+
+## Stale validation
+
+If the plan file changed after **`lastValidatedAt`**, re-run **`/validate-plan`** before implementation.
+
+## User override requests
+
+If the user asks to skip validation and implement directly → **refuse** and offer **`/validate-plan`**.
+
+## Commands
+
+- Pre-implementation: **`/validate-plan`** — see `.cursor/commands/validate-plan.md`
+- Post-implementation: **`/validate-implementation`**

package/.cursor/skills/README.md

@@ -2,6 +2,7 @@
 
 | Skill | Command | Purpose |
 | ----- | ------- | ------- |
+| [**aifabrix-application-lifecycle**](aifabrix-application-lifecycle/SKILL.md) | (all plan commands) | **Mandatory semantic lifecycle checklist** |
 | [builder-push-github](builder-push-github/SKILL.md) | `/push-github` | Release branch CI + optional NPM deploy PR |
 | [builder-repair-release](builder-repair-release/SKILL.md) | `/repair-release` | Version bump + CHANGELOG |
 | [builder-validate-tests](builder-validate-tests/SKILL.md) | `/validate-tests` | Lint + Jest fix loop |

package/.dockerignore

@@ -0,0 +1,52 @@
+# Builder API Docker build context (plan 154.3)
+# Deny-by-default: Dockerfile COPY uses docker-builder-api-staging/ only (host script).
+# Never ship .cursor/, integration labs, tests, full templates/, or CLI entry aifabrix.js.
+
+# Git and IDE
+.git/
+.gitignore
+.github/
+.cursor/
+.aifabrix/
+.vscode/
+.idea/
+*.swp
+*~
+.DS_Store
+
+# Dev / CI trees (not runtime)
+tests/
+docs/
+integration/
+packages/
+builder/
+scripts/
+temp/
+.temp/
+coverage/
+.nyc_output/
+eslint-report.json
+
+# Full source trees replaced by docker-builder-api-staging/
+lib/
+bin/
+templates/
+
+# Staged runtime output (must remain in context)
+!docker-builder-api-staging/
+
+# Node dev artifacts (package manifests whitelisted below)
+node_modules/
+npm-debug.log*
+
+# Env and secrets
+.env
+.env.*
+
+# Misc root clutter
+*.md
+!docker-builder-api-staging/**
+
+# Keep npm install inputs
+!package.json
+!package-lock.json

package/.eslintignore

@@ -0,0 +1,22 @@
+# Dependencies and coverage
+node_modules/
+coverage/
+.nyc_output/
+
+# Build and staging artifacts
+dist/
+build/
+out/
+docker-builder-api-staging/
+packages/builder-api/dist/
+
+# Temporary and local-only paths (see .gitignore)
+.temp/
+.temp/**
+temp/
+tmp-imgver*/
+mount/
+
+# Generated integration deploy scripts and local lab fixtures
+integration/**/deploy.js
+integration/**/backup/

package/README.md

@@ -7,6 +7,8 @@ Open developer runtime for AI Fabrix ecosystem. Install the AI Fabrix platform a
 
 ← **Full documentation:** [docs/README.md](docs/README.md) (table of contents for all guides)
 
+**Contributor quick start (miso ↔ dataplane ↔ builder):** [QUICK-START.md](QUICK-START.md)
+
 ---
 
 ## Why AI Fabrix Builder?

package/bin/builder-api-cleanup.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+/**
+ * Purge expired builder-api workspaces (cron / scheduled job entry).
+ */
+
+'use strict';
+
+const { purgeExpiredWorkspaces } = require('../lib/programmatic/workspace-cleanup');
+
+const dryRun = process.argv.includes('--dry-run');
+
+const result = purgeExpiredWorkspaces({ dryRun });
+
+// eslint-disable-next-line no-console
+console.log(
+  dryRun
+    ? `Would purge ${result.count} workspace(s)`
+    : `Purged ${result.count} workspace(s)`
+);
+
+if (result.count > 0) {
+  for (const row of result.purged) {
+    // eslint-disable-next-line no-console
+    console.log(`  ${row.userId}/integration/${row.systemKey}`);
+  }
+}

package/bin/builder-api-nest.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * Start builder-api via NestJS bootstrap (plan 154.0 monorepo scaffold).
+ */
+
+'use strict';
+
+require('reflect-metadata');
+require('ts-node/register/transpile-only');
+require('../packages/builder-api/src/main.ts');

package/bin/builder-api-spike.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * Start builder-api HTTP server (plan 154.0 spike / pre-Nest).
+ */
+
+'use strict';
+
+const { createBuilderApiServer, BASE } = require('../lib/programmatic/builder-api-server');
+const { ensureBuilderApiRuntimeConfigDir } = require('../lib/programmatic/builder-api-runtime-config');
+
+ensureBuilderApiRuntimeConfigDir();
+
+const port = Number(process.env.PORT || 3005);
+const server = createBuilderApiServer(port);
+
+server.on('listening', () => {
+  // eslint-disable-next-line no-console
+  console.log(`builder-api listening on http://localhost:${port}${BASE}/health`);
+});

package/enterprise-knowledge/README.md

@@ -0,0 +1,50 @@
+# Enterprise Knowledge anchors (aifabrix-builder SSOT)
+
+Authoring workspace for **Enterprise Knowledge** external systems (`systemKind: enterpriseKnowledge`).
+
+Connected Systems (vendor integrations) stay under `integration/`. Enterprise Knowledge anchors live here.
+
+## Layout
+
+```text
+enterprise-knowledge/<anchorKey>/
+  application.json
+  <anchorKey>-system.json
+  <anchorKey>-deploy.json
+  env.template
+  deploy.js
+```
+
+## CLI
+
+Commands resolve this tree automatically when `*-system.json` has `systemKind: enterpriseKnowledge`:
+
+```bash
+aifabrix validate enterprise-integration-lifecycle
+aifabrix upload enterprise-integration-lifecycle
+aifabrix deploy enterprise-integration-lifecycle
+```
+
+Optional override:
+
+```bash
+aifabrix upload <anchor>
+```
+
+Generate a full manifest preview (human review before upload/deploy):
+
+```bash
+aifabrix enterprise-knowledge generate-manifest --domain sales --source-system hubspot-e2e
+```
+
+Preview JSON is written under `enterprise-knowledge/<anchor>/generated-service-contracts/` unless `--output` or `--json` is used.
+
+User-facing CLI copy uses **Enterprise Knowledge** (not internal abbreviations).
+
+## Platform anchor
+
+| Anchor | Purpose |
+| --- | --- |
+| `enterprise-integration-lifecycle/` | Platform COM lifecycle subscriptions (repository.\*, template.\*) |
+
+See repo-root `integration/README.md` for the three-layer platform model and Connected Systems workflows.

package/enterprise-knowledge/enterprise-integration-lifecycle/README.md

@@ -0,0 +1,22 @@
+# Enterprise MCP — Integration lifecycle (Layer 2)
+
+Platform **enterpriseKnowledge** anchor for normalized **repository.*** and **template.*** Enterprise MCP tools.
+
+| Generated datasource | Trigger |
+| --- | --- |
+| `enterprise-repository` | Published datasource with `resourceType: repository` (e.g. `github-repository`) |
+| `enterprise-template` | Published datasource with `resourceType: template` |
+
+**Builder-api** calls this system via `ENTERPRISE_MCP_SYSTEM_KEY=enterprise-integration-lifecycle` (see `builder/builder-api/env.template`).
+
+## Bootstrap
+
+```bash
+aifabrix validate enterprise-integration-lifecycle
+aifabrix json enterprise-integration-lifecycle
+aifabrix upload enterprise-integration-lifecycle --probe
+```
+
+Publish **before** uploading repository provider integrations (`github`).
+
+See `tests/manual/com/integration_lifecycle_golden_path.md` in aifabrix-dataplane (manual proof).

package/enterprise-knowledge/enterprise-integration-lifecycle/application.json

@@ -0,0 +1,15 @@
+{
+  "app": {
+    "key": "enterprise-integration-lifecycle",
+    "displayName": "Enterprise MCP — Integration lifecycle",
+    "description": "Platform anchor for unified Enterprise MCP repository and template capabilities (154.1 Layer 2).",
+    "type": "external"
+  },
+  "externalIntegration": {
+    "version": "1.0.0",
+    "autopublish": false,
+    "schemaBasePath": "./",
+    "systems": ["enterprise-integration-lifecycle-system.json"],
+    "dataSources": []
+  }
+}

package/enterprise-knowledge/enterprise-integration-lifecycle/deploy.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+/**
+ * Deploy enterprise-integration-lifecycle external system and datasources using aifabrix CLI.
+ * Run: node deploy.js
+ * Flow: check auth → login if needed → deploy → run integration tests.
+ */
+
+const { execSync } = require('child_process');
+const path = require('path');
+
+const scriptDir = __dirname;
+// Project root (repo containing integration/ and builder/) so deploy/test-integration resolve app paths correctly
+const projectRoot = path.join(scriptDir, '..', '..');
+const appKey = 'enterprise-integration-lifecycle';
+const env = process.env.ENVIRONMENT || 'dev';
+// Controller URL: from config (aifabrix auth config) or set CONTROLLER env before running
+
+/**
+ * Run a shell command with optional options.
+ * @param {string} cmd - Command to run
+ * @param {Object} [options={}] - Options (cwd, stdio, ignoreExit)
+ * @returns {boolean} True if command succeeded
+ */
+function run(cmd, options = {}) {
+  const opts = { cwd: scriptDir, stdio: 'inherit', ...options };
+  try {
+    execSync(cmd, opts);
+    return true;
+  } catch (err) {
+    if (options.ignoreExit) return false;
+    process.exit(err.status ?? 1);
+  }
+}
+
+/**
+ * Check if aifabrix auth is logged in.
+ * @returns {boolean} True if logged in
+ */
+function isLoggedIn() {
+  try {
+    execSync('aifabrix auth status', { cwd: scriptDir, stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+console.log('🔍 Checking authentication...');
+if (!isLoggedIn()) {
+  console.log('⚠  Not logged in. Run login (e.g. aifabrix login --controller <url> --method device --environment ' + env + ').');
+  run('aifabrix login --environment ' + env);
+}
+
+console.log('🔍 Validating configuration...');
+run('aifabrix validate "' + path.join(scriptDir, 'enterprise-integration-lifecycle-system.json') + '"');
+console.log('✔ Validation passed');
+
+console.log('🚀 Deploying ' + appKey + '...');
+run('aifabrix deploy ' + appKey, { cwd: projectRoot });
+console.log('✔ Deployment complete');
+
+if (process.env.RUN_TESTS !== 'false') {
+  console.log('🧪 Running integration tests...');
+  run('aifabrix test-integration ' + appKey, { cwd: projectRoot });
+  console.log('✔ Tests passed');
+}
+
+console.log('✔ Done.');

package/enterprise-knowledge/enterprise-integration-lifecycle/enterprise-integration-lifecycle-deploy.json

@@ -0,0 +1,52 @@
+{
+  "key": "enterprise-integration-lifecycle",
+  "displayName": "Enterprise MCP — Integration lifecycle",
+  "description": "Platform anchor for unified Enterprise MCP repository and template capabilities (154.1 Layer 2).",
+  "type": "external",
+  "version": "1.0.0",
+  "externalIntegration": {
+    "schemaBasePath": "./",
+    "systems": [
+      "enterprise-integration-lifecycle-system.json"
+    ],
+    "dataSources": [],
+    "autopublish": false,
+    "version": "1.0.0"
+  },
+  "system": {
+    "key": "enterprise-integration-lifecycle",
+    "displayName": "Enterprise MCP — Integration lifecycle",
+    "description": "Platform anchor for Builder workspace lifecycle. Generates enterprise-repository and enterprise-template MCP datasources when repository or template provider datasources publish. Referenced by builder-api ENTERPRISE_MCP_SYSTEM_KEY.",
+    "type": "custom",
+    "enabled": true,
+    "systemKind": "enterpriseKnowledge",
+    "authentication": {
+      "authType": "none"
+    },
+    "configuration": [],
+    "dataSources": [],
+    "subscriptions": [
+      {
+        "key": "enterprise-integration-lifecycle-generator",
+        "displayName": "Enterprise integration lifecycle generator",
+        "description": "Regenerate enterprise repository and template MCP datasources when provider datasources publish.",
+        "event": "platform.datasource.published",
+        "filter": {
+          "resourceTypes": [
+            "repository",
+            "template"
+          ]
+        },
+        "task": {
+          "type": "generateEnterpriseDatasources",
+          "version": 1
+        },
+        "runOnCreate": true
+      }
+    ]
+  },
+  "dataSources": [],
+  "requiresDatabase": false,
+  "requiresRedis": false,
+  "requiresStorage": false
+}

package/enterprise-knowledge/enterprise-integration-lifecycle/enterprise-integration-lifecycle-system.json

@@ -0,0 +1,29 @@
+{
+  "key": "enterprise-integration-lifecycle",
+  "displayName": "Enterprise MCP — Integration lifecycle",
+  "description": "Platform anchor for Builder workspace lifecycle. Generates enterprise-repository and enterprise-template MCP datasources when repository or template provider datasources publish. Referenced by builder-api ENTERPRISE_MCP_SYSTEM_KEY.",
+  "type": "custom",
+  "enabled": true,
+  "systemKind": "enterpriseKnowledge",
+  "authentication": {
+    "authType": "none"
+  },
+  "configuration": [],
+  "dataSources": [],
+  "subscriptions": [
+    {
+      "key": "enterprise-integration-lifecycle-generator",
+      "displayName": "Enterprise integration lifecycle generator",
+      "description": "Regenerate enterprise repository and template MCP datasources when provider datasources publish.",
+      "event": "platform.datasource.published",
+      "filter": {
+        "resourceTypes": ["repository", "template"]
+      },
+      "task": {
+        "type": "generateEnterpriseDatasources",
+        "version": 1
+      },
+      "runOnCreate": true
+    }
+  ]
+}

package/enterprise-knowledge/enterprise-integration-lifecycle/env.template

@@ -0,0 +1,2 @@
+# Enterprise MCP integration lifecycle anchor — no secrets required.
+# Publish once per environment before repository/template provider datasources.