@aifabrix/builder 2.60.0 → 2.61.2

package/docs/builder-help/resource-type-catalog.json

@@ -0,0 +1,402 @@
+{
+  "schemaVersion": "1.0.0",
+  "source": "baseline-resourcetypes.json",
+  "lastSynced": "2026-08-22",
+  "minimumSystemKeys": [
+    "customer",
+    "contact",
+    "employee",
+    "project",
+    "task",
+    "meeting",
+    "document",
+    "approval",
+    "contract",
+    "invoice",
+    "deal",
+    "ticket",
+    "message",
+    "channel",
+    "workspace",
+    "knowledge",
+    "event"
+  ],
+  "resourceTypes": [
+    {
+      "key": "approval",
+      "displayName": "Approval",
+      "description": "Approval request, decision, review process, or authorization workflow item.",
+      "category": "governance",
+      "defaultRiskLevel": "high",
+      "status": "active"
+    },
+    {
+      "key": "asset",
+      "displayName": "Asset",
+      "description": "Managed physical, digital, financial, or operational business asset.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "attachment",
+      "displayName": "Attachment",
+      "description": "File attachment, uploaded content, supporting artifact, or binary business asset.",
+      "category": "content",
+      "defaultRiskLevel": "low",
+      "status": "active"
+    },
+    {
+      "key": "balance",
+      "displayName": "Balance",
+      "description": "Leave, absence, or accrued time-off balance for a person.",
+      "category": "people",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "budget",
+      "displayName": "Budget",
+      "description": "Budget allocation, financial plan, spending target, or funding record.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "case",
+      "displayName": "Case",
+      "description": "Support request, incident, issue, service ticket, or customer problem record.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "channel",
+      "displayName": "Channel",
+      "description": "Collaboration channel, team space, or communication group.",
+      "category": "collaboration",
+      "defaultRiskLevel": "low",
+      "status": "active"
+    },
+    {
+      "key": "contact",
+      "displayName": "Contact",
+      "description": "Individual person associated with a customer, supplier, partner, or other business entity.",
+      "category": "people",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "contract",
+      "displayName": "Contract",
+      "description": "Formal agreement, legal commitment, or business contract between parties.",
+      "category": "governance",
+      "defaultRiskLevel": "high",
+      "status": "active"
+    },
+    {
+      "key": "customer",
+      "displayName": "Customer",
+      "description": "Organization, account, client, or business entity that purchases, receives, or is associated with products or services.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "deal",
+      "displayName": "Deal",
+      "description": "Commercial deal, sales opportunity, or revenue pursuit in the sales pipeline.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "decision",
+      "displayName": "Decision",
+      "description": "Business decision, resolution, approved action, or governance outcome.",
+      "category": "governance",
+      "defaultRiskLevel": "high",
+      "status": "active"
+    },
+    {
+      "key": "department",
+      "displayName": "Department",
+      "description": "Organizational unit, business function, or department.",
+      "category": "people",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "document",
+      "displayName": "Document",
+      "description": "Business document, file, presentation, contract, or knowledge artifact.",
+      "category": "content",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "folder",
+      "displayName": "Folder",
+      "description": "Container or directory for documents and files.",
+      "category": "content",
+      "defaultRiskLevel": "low",
+      "status": "active"
+    },
+    {
+      "key": "hr-report",
+      "displayName": "HR Report",
+      "description": "People and HR report, workforce analytics rollup, or period summary. Distinct from Document.",
+      "category": "people",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "email",
+      "displayName": "Email",
+      "description": "Email message, conversation, or business communication record.",
+      "category": "communication",
+      "defaultRiskLevel": "low",
+      "status": "active"
+    },
+    {
+      "key": "employee",
+      "displayName": "Employee",
+      "description": "Internal worker, staff member, contractor, or workforce resource.",
+      "category": "people",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "event",
+      "displayName": "Event",
+      "description": "Business event, calendar event, milestone, or scheduled activity.",
+      "category": "communication",
+      "defaultRiskLevel": "low",
+      "status": "active"
+    },
+    {
+      "key": "expense",
+      "displayName": "Expense",
+      "description": "Expense claim, cost record, reimbursement, or financial expenditure.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "finance-report",
+      "displayName": "Finance Report",
+      "description": "Financial report, analytics rollup, or period summary over finance records. Distinct from Document.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "invoice",
+      "displayName": "Invoice",
+      "description": "Billing document, payment request, or financial charge record.",
+      "category": "business",
+      "defaultRiskLevel": "high",
+      "status": "active"
+    },
+    {
+      "key": "knowledge",
+      "displayName": "Knowledge",
+      "description": "Knowledge article, FAQ, guidance, procedure, or reference content.",
+      "category": "content",
+      "defaultRiskLevel": "low",
+      "status": "active"
+    },
+    {
+      "key": "llm",
+      "displayName": "LLM",
+      "description": "Large language model provider capability surface for chat completion and embedding operations.",
+      "category": "content",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "meeting",
+      "displayName": "Meeting",
+      "description": "Scheduled interaction, discussion, workshop, or business event involving participants.",
+      "category": "collaboration",
+      "defaultRiskLevel": "low",
+      "status": "active"
+    },
+    {
+      "key": "message",
+      "displayName": "Message",
+      "description": "Chat, Teams message, discussion, or conversational communication record.",
+      "category": "communication",
+      "defaultRiskLevel": "low",
+      "status": "active"
+    },
+    {
+      "key": "note",
+      "displayName": "Note",
+      "description": "Business note, comment, activity note, CRM note, or user-generated contextual information.",
+      "category": "content",
+      "defaultRiskLevel": "low",
+      "status": "active"
+    },
+    {
+      "key": "objective",
+      "displayName": "Objective",
+      "description": "Strategic goal, business objective, target outcome, or organizational priority.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "opportunity",
+      "displayName": "Opportunity",
+      "description": "Potential sales, revenue, business development, or commercial opportunity.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "operations-report",
+      "displayName": "Operations Report",
+      "description": "Operations report, operational analytics rollup, or period summary. Distinct from Document.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "order",
+      "displayName": "Order",
+      "description": "Customer order, purchase request, sales order, or transaction record.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "organization",
+      "displayName": "Organization",
+      "description": "Internal organizational entity, subsidiary, legal entity, or business unit.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "owner",
+      "displayName": "Owner",
+      "description": "Individual user or account responsible for ownership, stewardship, or accountability of a record or business object.",
+      "category": "people",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "partner",
+      "displayName": "Partner",
+      "description": "External organization participating in business collaboration, delivery, sales, or strategic activities.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "payment",
+      "displayName": "Payment",
+      "description": "Payment transaction, settlement, receipt, or financial payment record.",
+      "category": "business",
+      "defaultRiskLevel": "high",
+      "status": "active"
+    },
+    {
+      "key": "policy",
+      "displayName": "Policy",
+      "description": "Policy, guideline, compliance rule, or governance document.",
+      "category": "governance",
+      "defaultRiskLevel": "high",
+      "status": "active"
+    },
+    {
+      "key": "position",
+      "displayName": "Position",
+      "description": "Job role, position, title, or workforce assignment.",
+      "category": "people",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "product",
+      "displayName": "Product",
+      "description": "Product, service offering, subscription, or item available for sale or delivery.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "project",
+      "displayName": "Project",
+      "description": "Temporary initiative or work effort with defined objectives, timelines, resources, and deliverables.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "repository",
+      "displayName": "Repository",
+      "description": "Version-controlled source repository for integration manifests, CIP pipelines, and workspace sync.",
+      "category": "content",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "risk",
+      "displayName": "Risk",
+      "description": "Potential business, operational, compliance, security, or financial risk.",
+      "category": "governance",
+      "defaultRiskLevel": "high",
+      "status": "active"
+    },
+    {
+      "key": "sales-report",
+      "displayName": "Sales Report",
+      "description": "Sales report, pipeline analytics rollup, or commercial period summary. Distinct from Document.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "supplier",
+      "displayName": "Supplier",
+      "description": "Organization providing products, services, materials, or external resources.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "task",
+      "displayName": "Task",
+      "description": "Work item, action, assignment, or activity that can be completed by an individual or team.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "template",
+      "displayName": "Template",
+      "description": "Integration workspace template used to materialize local Builder workspaces.",
+      "category": "content",
+      "defaultRiskLevel": "low",
+      "status": "active"
+    },
+    {
+      "key": "ticket",
+      "displayName": "Ticket",
+      "description": "Support ticket, service request, incident, or customer issue record.",
+      "category": "business",
+      "defaultRiskLevel": "medium",
+      "status": "active"
+    },
+    {
+      "key": "workspace",
+      "displayName": "Workspace",
+      "description": "Shared workspace, site, or collaboration area for teams and content.",
+      "category": "collaboration",
+      "defaultRiskLevel": "low",
+      "status": "active"
+    }
+  ]
+}

package/lib/api/configuration.api.js

@@ -0,0 +1,131 @@
+/**
+ * Parameter-backed installation configuration API.
+ *
+ * @fileoverview Read safe configuration metadata from Miso Controller
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { ApiClient } = require('./index');
+
+const PAGE_SIZE = 100;
+
+/**
+ * @param {string} envKey - Environment key
+ * @returns {string} Configuration collection endpoint
+ */
+function configurationEndpoint(envKey) {
+  return `/api/v1/environments/${encodeURIComponent(envKey)}/configuration`;
+}
+
+/**
+ * @param {Object} meta - Pagination metadata
+ * @param {number} requestedPage - Requested one-based page
+ * @param {boolean} hasRows - Whether the page contains rows
+ * @returns {number} Validated total page count
+ */
+function validatePageMeta(meta, requestedPage, hasRows) {
+  const currentPage = Number(meta && meta.currentPage);
+  const totalPages = Number(meta && meta.totalPages);
+  if (!Number.isInteger(currentPage) || currentPage !== requestedPage) {
+    throw new Error('Configuration list response has invalid pagination metadata');
+  }
+  if (!Number.isInteger(totalPages) || totalPages < 0 || (hasRows && totalPages === 0)) {
+    throw new Error('Configuration list response has invalid pagination metadata');
+  }
+  return totalPages;
+}
+
+/**
+ * @param {Object} response - API response
+ * @param {number} requestedPage - Requested one-based page
+ * @returns {{ rows: Object[], totalPages: number }} Validated page
+ */
+function readConfigurationPage(response, requestedPage) {
+  if (response && response.success === false) {
+    throw new Error(response.formattedError || response.error || 'Configuration list request failed');
+  }
+  const body = response && response.data !== undefined ? response.data : response;
+  if (!body || !Array.isArray(body.data) || !body.meta) {
+    throw new Error('Configuration list response is not a paginated result');
+  }
+  const totalPages = validatePageMeta(body.meta, requestedPage, body.data.length > 0);
+  return { rows: body.data, totalPages };
+}
+
+/**
+ * List configuration declarations, optionally for one exact owner.
+ *
+ * GET /api/v1/environments/{envKey}/configuration
+ * @requiresPermission {Controller} controller:monitor or admin:read
+ * @async
+ * @function listEnvironmentConfiguration
+ * @param {string} controllerUrl - Controller base URL
+ * @param {Object} authConfig - Authentication configuration
+ * @param {string} envKey - Environment key
+ * @param {string} [application] - Exact owning application key
+ * @param {Object} [options] - Optional safe search
+ * @param {string} [options.search] - Partial key/name search
+ * @returns {Promise<Object[]>} Safe configuration metadata rows
+ */
+async function listEnvironmentConfiguration(controllerUrl, authConfig, envKey, application, options = {}) {
+  if (!controllerUrl || typeof controllerUrl !== 'string') {
+    throw new Error('controllerUrl is required and must be a string');
+  }
+  const environment = typeof envKey === 'string' ? envKey.trim() : '';
+  const owner = typeof application === 'string' ? application.trim() : '';
+  if (!environment) {
+    throw new Error('envKey is required and must be a string');
+  }
+  const client = new ApiClient(controllerUrl, authConfig);
+  const common = {
+    pageSize: PAGE_SIZE,
+    sort: owner ? 'key' : 'application'
+  };
+  if (owner) common.application = owner;
+  if (options.search) common.search = String(options.search).trim();
+  const rows = [];
+  for (let page = 1;; page += 1) {
+    const response = await client.get(configurationEndpoint(environment), {
+      params: { ...common, page }
+    });
+    const result = readConfigurationPage(response, page);
+    rows.push(...result.rows);
+    if (page >= result.totalPages) return rows;
+  }
+}
+
+/**
+ * Update one authoritatively non-sensitive configuration declaration.
+ * @param {string} controllerUrl - Controller base URL
+ * @param {Object} authConfig - Authentication configuration
+ * @param {string} envKey - Environment key
+ * @param {string} application - Exact application owner
+ * @param {string} key - Configuration declaration key
+ * @param {Object} update - Value and concurrency revision
+ * @param {string} update.value - Non-sensitive value
+ * @param {string} update.revision - Opaque revision from the configuration list
+ * @returns {Promise<Object>} Safe updated metadata
+ */
+async function putEnvironmentConfiguration(
+  controllerUrl, authConfig, envKey, application, key, update
+) {
+  const value = update && update.value;
+  const revision = update && update.revision;
+  const required = { controllerUrl, envKey, application, key, revision };
+  for (const [name, input] of Object.entries(required)) {
+    if (!input || typeof input !== 'string') throw new Error(`${name} is required`);
+  }
+  if (typeof value !== 'string') throw new Error('value must be a string');
+  const client = new ApiClient(controllerUrl, authConfig);
+  const endpoint = `${configurationEndpoint(envKey)}/${encodeURIComponent(application)}/` +
+    encodeURIComponent(key);
+  return await client.put(endpoint, { body: { value }, headers: { 'If-Match': revision } });
+}
+
+module.exports = {
+  listEnvironmentConfiguration,
+  putEnvironmentConfiguration
+};

package/lib/api/system-secrets.api.js

@@ -0,0 +1,72 @@
+/**
+ * System secrets API (Miso Controller).
+ *
+ * Deliberately narrow: a value can be written and never read back, and only against a
+ * catalog key the installation already defines. There is no create endpoint, so this module
+ * must not grow one — a key that does not exist is a catalog change in aifabrix-miso, not
+ * something the CLI can fix.
+ *
+ * The PUT request body marks `value` as writeOnly. Nothing here returns a value, and no
+ * caller should construct a response shape that could carry one.
+ *
+ * @fileoverview System secrets API functions (put-only over catalog keys)
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { ApiClient } = require('./index');
+
+/**
+ * @param {string} envKey - Environment key
+ * @returns {string} Collection endpoint for that environment
+ */
+function systemSecretsEndpoint(envKey) {
+  return `/api/v1/environments/${encodeURIComponent(envKey)}/system-secrets`;
+}
+
+/**
+ * Set one system secret value. The value is write-only: it cannot be read back, and this
+ * function returns the server response unchanged without echoing what was sent.
+ *
+ * PUT /api/v1/environments/{envKey}/system-secrets/{catalogKey}
+ * @requiresPermission {Miso} controller:admin
+ * @async
+ * @function putSystemSecret
+ * @param {string} controllerUrl - Controller base URL
+ * @param {Object} authConfig - Authentication configuration
+ * @param {string} envKey - Environment key
+ * @param {string} catalogKey - Catalog key the installation already defines
+ * @param {string} value - Secret value, read from a file by the caller
+ * @param {string} revision - Opaque revision returned by the configuration list
+ * @returns {Promise<Object>} Server response; carries no value
+ * @throws {Error} If the request fails. The message must never include the value
+ */
+async function putSystemSecret(controllerUrl, authConfig, envKey, catalogKey, value, revision) {
+  if (!controllerUrl || typeof controllerUrl !== 'string') {
+    throw new Error('controllerUrl is required and must be a string');
+  }
+  if (!envKey || typeof envKey !== 'string') {
+    throw new Error('envKey is required and must be a string');
+  }
+  if (!catalogKey || typeof catalogKey !== 'string') {
+    throw new Error('catalogKey is required and must be a string');
+  }
+  if (typeof value !== 'string' || value.length === 0) {
+    // Names the key, never the value, because this message reaches the terminal.
+    throw new Error(`No value supplied for ${catalogKey}`);
+  }
+  if (!revision || typeof revision !== 'string') {
+    throw new Error(`No configuration revision supplied for ${catalogKey}`);
+  }
+  const client = new ApiClient(controllerUrl, authConfig);
+  return await client.put(`${systemSecretsEndpoint(envKey)}/${encodeURIComponent(catalogKey)}`, {
+    body: { value },
+    headers: { 'If-Match': revision }
+  });
+}
+
+module.exports = {
+  putSystemSecret
+};

package/lib/app/run-docker-fallback.js

@@ -8,6 +8,8 @@
 'use strict';
 
 const chalk = require('chalk');
+const { prepareLocalDataMount } = require('../utils/prepare-local-data-mount');
+const { resolveLocalDataMountPathForCompose } = require('../utils/compose-generate-docker-compose');
 const logger = require('../utils/logger');
 const { execWithDockerEnv } = require('../utils/docker-exec');
 const { getContainerPort } = require('../utils/port-resolver');
@@ -87,7 +89,10 @@ async function executeDockerRunUp(o) {
   ];
 
   if (needsStorage) {
-    parts.push(`-v ${shellSingleQuote(storageVolumeName(appName, appConfig.developerId))}:/mnt/data`);
+    const localPath = resolveLocalDataMountPathForCompose({ appName, appConfig });
+    if (localPath) prepareLocalDataMount(localPath, runEnvPath);
+    const source = localPath || storageVolumeName(appName, appConfig.developerId);
+    parts.push(`-v ${shellSingleQuote(source)}:/mnt/data`);
   }
   if (runEnvPath && typeof runEnvPath === 'string') {
     parts.push(`--env-file ${shellSingleQuote(runEnvPath)}`);

package/lib/app/run-helpers.js

@@ -368,6 +368,8 @@ async function prepareEnvironment(appName, appConfig, options) {
     developerId,
     { runEnvKey, effectiveEnvironmentScopedResources }
   );
+  const { hydrateMissingLocalParameters } = require('./run-parameter-sync');
+  await hydrateMissingLocalParameters(appName, runEnvPath);
 
   const composeOptions = {
     ...options,
@@ -438,4 +440,3 @@ module.exports = {
   displayRunStatus,
   cleanApplicationsDir: runEnvCompose.cleanApplicationsDir
 };
-