@aifabrix/builder 2.46.0 → 2.47.1

package/lib/commands/identity-user-cli.js

@@ -6,9 +6,8 @@
 
 'use strict';
 
-const chalk = require('chalk');
 const logger = require('../utils/logger');
-const { formatBlockingError, formatSuccessLine, headerKeyValue } = require('../utils/cli-layout-chalk');
+const { formatBlockingError, formatSuccessLine } = require('../utils/cli-layout-chalk');
 const {
   resolveControllerAndAuth,
   requireNonEmpty,
@@ -21,11 +20,27 @@ const {
   createUser,
   listUserGroups
 } = require('../api/users.api');
+const {
+  extractPaginatedList,
+  printIdentityEmpty,
+  printIdentityListHeader,
+  printIdentityNotFound,
+  printIdentityTable,
+  printListPaginationFooter,
+  printUserGroupsTable,
+  printUserRecord,
+  USER_LIST_COLUMNS
+} = require('../identity/identity-display');
+const { resolveIdentityUsername } = require('../identity/username-default');
 
 function printJson(data) {
   logger.log(JSON.stringify(data, null, 2));
 }
 
+function userNotFoundHints() {
+  return ['af identity user list --search <text>', 'Check email, username, or id spelling'];
+}
+
 function registerUserCreate(userCmd) {
   userCmd
     .command('create')
@@ -38,12 +53,13 @@ function registerUserCreate(userCmd) {
     .action(async(options) => {
       try {
         const { controllerUrl, authConfig } = await resolveControllerAndAuth();
+        const email = requireNonEmpty(options.email, 'email');
         const res = await createUser(controllerUrl, authConfig, {
-          email: requireNonEmpty(options.email, 'email'),
+          email,
           firstName: options.firstName,
           lastName: options.lastName,
           displayName: options.displayName,
-          username: options.username,
+          username: resolveIdentityUsername({ username: options.username, email }),
           status: 'active'
         });
         throwIfApiFailed(res);
@@ -62,26 +78,41 @@ function registerUserList(userCmd) {
     .description('List users')
     .option('--page <n>', 'Page', (v) => parseInt(v, 10))
     .option('--page-size <n>', 'Page size', (v) => parseInt(v, 10))
-    .option('--search <text>', 'Search users')
+    .option('--search <text>', 'Search users (email, username, name)')
+    .option('--email <email>', 'Exact email filter')
     .option('--json', 'JSON output')
     .action(async(options) => {
       try {
         const { controllerUrl, authConfig } = await resolveControllerAndAuth();
-        const res = await listUsers(controllerUrl, authConfig, {
+        const params = {
           page: options.page,
           pageSize: options.pageSize,
           search: options.search
-        });
+        };
+        if (options.email) {
+          params.filter = `email:eq:${options.email}`;
+          delete params.search;
+        }
+        const res = await listUsers(controllerUrl, authConfig, params);
         throwIfApiFailed(res);
-        const data = unwrapControllerData(res);
         if (options.json) {
-          printJson(data);
+          printJson(res.data ?? res);
           return;
         }
-        const items = Array.isArray(data) ? data : data?.data || [];
-        logger.log(chalk.bold(`\nUsers (${items.length} shown):\n`));
-        items.forEach((u) => logger.log(`  ${u.id}  ${u.email}`));
-        logger.log('');
+        const { items, meta } = extractPaginatedList(res);
+        printIdentityListHeader({
+          emoji: '👤',
+          title: 'Users',
+          context: controllerUrl,
+          shown: items.length,
+          total: meta?.totalItems ?? items.length
+        });
+        if (items.length === 0) {
+          printIdentityEmpty('No users found.', ['Try --search or --email']);
+          return;
+        }
+        printIdentityTable(USER_LIST_COLUMNS, items);
+        printListPaginationFooter(meta);
       } catch (e) {
         logger.error(formatBlockingError(e.message));
         process.exit(1);
@@ -91,22 +122,28 @@ function registerUserList(userCmd) {
 
 function registerUserGet(userCmd) {
   userCmd
-    .command('get <idOrEmail>')
-    .description('Get user by id or email')
+    .command('get <userIdOrEmail>')
+    .description('Get user by id, email, or username')
     .option('--json', 'JSON output')
-    .action(async(idOrEmail, options) => {
+    .action(async(userIdOrEmail, options) => {
       try {
         const { controllerUrl, authConfig } = await resolveControllerAndAuth();
-        const res = await getUser(controllerUrl, authConfig, requireNonEmpty(idOrEmail, 'idOrEmail'));
-        throwIfApiFailed(res);
+        const value = requireNonEmpty(userIdOrEmail, 'userIdOrEmail');
+        const res = await getUser(controllerUrl, authConfig, value);
+        if (!res || res.success === false) {
+          printIdentityNotFound('User', value, userNotFoundHints());
+          process.exit(1);
+        }
         const row = unwrapControllerData(res);
+        if (!row?.id) {
+          printIdentityNotFound('User', value, userNotFoundHints());
+          process.exit(1);
+        }
         if (options.json) {
           printJson(row);
           return;
         }
-        logger.log(headerKeyValue('Id:', row.id));
-        logger.log(headerKeyValue('Email:', row.email));
-        logger.log('');
+        printUserRecord(row);
       } catch (e) {
         logger.error(formatBlockingError(e.message));
         process.exit(1);
@@ -116,26 +153,35 @@ function registerUserGet(userCmd) {
 
 function registerUserGroups(userCmd) {
   userCmd
-    .command('groups <idOrEmail>')
-    .description('List groups for a user')
+    .command('groups <userIdOrEmail>')
+    .description('List groups for a user (by id, email, or username)')
     .option('--json', 'JSON output')
-    .action(async(idOrEmail, options) => {
+    .action(async(userIdOrEmail, options) => {
       try {
         const { controllerUrl, authConfig } = await resolveControllerAndAuth();
-        const res = await listUserGroups(
-          controllerUrl,
-          authConfig,
-          requireNonEmpty(idOrEmail, 'idOrEmail')
-        );
-        throwIfApiFailed(res);
+        const value = requireNonEmpty(userIdOrEmail, 'userIdOrEmail');
+        const res = await listUserGroups(controllerUrl, authConfig, value);
+        if (!res || res.success === false) {
+          printIdentityNotFound('User', value, userNotFoundHints());
+          process.exit(1);
+        }
         const data = unwrapControllerData(res);
+        const items = Array.isArray(data) ? data : data?.data || [];
         if (options.json) {
-          printJson(data);
+          printJson(items);
           return;
         }
-        const items = Array.isArray(data) ? data : data?.data || [];
-        items.forEach((g) => logger.log(`  ${g.id || g.groupId}  ${g.name || ''}`));
-        logger.log('');
+        printIdentityListHeader({
+          emoji: '👥',
+          title: `Groups for ${value}`,
+          shown: items.length,
+          total: items.length
+        });
+        if (items.length === 0) {
+          printIdentityEmpty('No group memberships found.');
+          return;
+        }
+        printUserGroupsTable(items);
       } catch (e) {
         logger.error(formatBlockingError(e.message));
         process.exit(1);

package/lib/commands/login-device.js

@@ -81,8 +81,11 @@ async function saveDeviceLoginConfig(controllerUrl, token, refreshToken, expires
  * @returns {Promise<void>}
  */
 async function saveTokenAndDisplaySuccess(controllerUrl, token, refreshToken, expiresAt, envKey, opts = {}) {
-  await saveDeviceLoginConfig(controllerUrl, token, refreshToken, expiresAt);
-  await setControllerUrl(controllerUrl);
+  const storageUrl = opts.tokenControllerUrl
+    ? String(opts.tokenControllerUrl).trim().replace(/\/+$/, '')
+    : controllerUrl;
+  await saveDeviceLoginConfig(storageUrl, token, refreshToken, expiresAt);
+  await setControllerUrl(storageUrl);
   if (envKey) {
     await setCurrentEnvironment(envKey);
   }
@@ -219,6 +222,8 @@ function convertDeviceCodeResponse(apiResponse) {
     device_code: deviceCodeData.deviceCode || deviceCodeData.device_code,
     user_code: deviceCodeData.userCode || deviceCodeData.user_code,
     verification_uri: deviceCodeData.verificationUri || deviceCodeData.verification_uri,
+    verification_uri_complete:
+      deviceCodeData.verificationUriComplete || deviceCodeData.verification_uri_complete,
     expires_in: deviceCodeData.expiresIn || deviceCodeData.expires_in || 600,
     interval: deviceCodeData.interval || 5
   };
@@ -246,8 +251,11 @@ function logDeviceFlowError(deviceError, opts) {
 }
 
 function printCompactDeviceUrl(deviceCodeResponse) {
+  const visitUrl =
+    deviceCodeResponse.verification_uri_complete ||
+    `${deviceCodeResponse.verification_uri}?user_code=${deviceCodeResponse.user_code}`;
   logger.log('\nOpen browser to authenticate:');
-  logger.log(chalk.yellow(`${deviceCodeResponse.verification_uri}?user_code=${deviceCodeResponse.user_code}\n`));
+  logger.log(chalk.yellow(`${visitUrl}\n`));
 }
 
 /**

package/lib/commands/login.js

@@ -86,8 +86,12 @@ async function normalizeControllerUrl(options) {
     controllerUrl = await resolveControllerUrl();
   }
   controllerUrl = String(controllerUrl).trim().replace(/\/+$/, '');
-  // Save controller URL to config
-  await setControllerUrl(controllerUrl);
+  if (!options.skipControllerUrlPersist) {
+    const persistUrl = options.tokenControllerUrl
+      ? String(options.tokenControllerUrl).trim().replace(/\/+$/, '')
+      : controllerUrl;
+    await setControllerUrl(persistUrl);
+  }
   if (!options.compact) {
     logger.log(chalk.gray(`Controller URL: ${controllerUrl}`));
   }
@@ -158,7 +162,8 @@ async function handleCredentialsLoginFlow(controllerUrl, environment, options) {
 async function handleDeviceCodeLoginFlow(controllerUrl, environment, options) {
   return await handleDeviceCodeLogin(controllerUrl, environment, options.online, options.scope, {
     compact: Boolean(options.compact),
-    exitOnFailure: options.exitOnFailure !== false
+    exitOnFailure: options.exitOnFailure !== false,
+    tokenControllerUrl: options.tokenControllerUrl
   });
 }
 

package/lib/commands/npm-config.js

@@ -0,0 +1,103 @@
+/**
+ * aifabrix npm config — apply user-global npm auth from BASH_NPM_TOKEN.
+ *
+ * @fileoverview npm config command handler
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { execFile } = require('child_process');
+const { promisify } = require('util');
+const chalk = require('chalk');
+const { formatSuccessLine } = require('../utils/cli-test-layout-chalk');
+const logger = require('../utils/logger');
+const secretsLoad = require('../core/secrets-load');
+const { collectBashPrefixedEnv } = require('../utils/bash-secret-env');
+const {
+  REGISTRY_URL,
+  getUserNpmrcPath,
+  writeUserNpmrcFromToken
+} = require('../utils/npm-user-config');
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Resolve npm token from merged secrets or --from-env.
+ *
+ * @param {{ fromEnv?: boolean }} options
+ * @returns {Promise<string>}
+ */
+async function resolveNpmToken(options = {}) {
+  if (options.fromEnv) {
+    const fromProcess = (process.env.NPM_TOKEN || '').trim();
+    if (!fromProcess) {
+      throw new Error('NPM_TOKEN is not set in the environment (--from-env)');
+    }
+    return fromProcess;
+  }
+  const secrets = await secretsLoad.loadSecrets();
+  const bashEnv = collectBashPrefixedEnv(secrets);
+  const token = bashEnv.NPM_TOKEN;
+  if (!token) {
+    throw new Error(
+      'BASH_NPM_TOKEN is not set in merged secrets. Run: aifabrix secret set BASH_NPM_TOKEN "<token>" --shared'
+    );
+  }
+  return token;
+}
+
+/**
+ * Run npm whoami against registry.npmjs.org using the given token.
+ *
+ * @param {string} token
+ * @returns {Promise<string>} username
+ */
+async function npmWhoamiWithToken(token) {
+  const { stdout } = await execFileAsync(
+    'npm',
+    ['whoami', `--registry=${REGISTRY_URL}`, `--//registry.npmjs.org/:_authToken=${token}`],
+    { env: { ...process.env }, timeout: 30000 }
+  );
+  return String(stdout).trim();
+}
+
+/**
+ * @param {{ dryRun?: boolean, check?: boolean, fromEnv?: boolean }} options
+ * @returns {Promise<{ ok: boolean, npmrcPath?: string, username?: string, dryRun?: boolean }>}
+ */
+async function handleNpmConfig(options = {}) {
+  const dryRun = Boolean(options.dryRun);
+  const checkOnly = Boolean(options.check);
+  const token = await resolveNpmToken({ fromEnv: Boolean(options.fromEnv) });
+  const npmrcPath = getUserNpmrcPath();
+
+  if (checkOnly) {
+    const username = await npmWhoamiWithToken(token);
+    return { ok: true, npmrcPath, username };
+  }
+
+  const result = writeUserNpmrcFromToken(token, { dryRun, npmrcPath });
+
+  if (dryRun) {
+    logger.log(chalk.blue('Dry run — would update user npm config:'));
+    logger.log(`  path: ${npmrcPath}`);
+    for (const key of result.managedKeys) {
+      const suffix = key.includes('_authToken') ? '=<redacted>' : '';
+      logger.log(`  ${key}${suffix}`);
+    }
+    return { ok: true, npmrcPath, dryRun: true };
+  }
+
+  const username = await npmWhoamiWithToken(token);
+  logger.log(formatSuccessLine(`Updated user npm config: ${npmrcPath}`));
+  logger.log(chalk.gray(`npm whoami: ${username}`));
+  return { ok: true, npmrcPath, username };
+}
+
+module.exports = {
+  resolveNpmToken,
+  npmWhoamiWithToken,
+  handleNpmConfig
+};

package/lib/commands/repair-auth-apply.js

@@ -10,7 +10,11 @@
 
 'use strict';
 
-const { buildAuthenticationFromMethod } = require('../external-system/generator');
+const {
+  buildAuthenticationFromMethod,
+  getAuthCredentialTemplate,
+  migrateAuthenticationToNestedSchema
+} = require('../utils/authentication-shape');
 
 /** Repair CLI --auth values (normalized lowercase). */
 const ALLOWED_REPAIR_AUTH = [
@@ -95,9 +99,10 @@ const MISSING_TEST_ENDPOINT_WARNING =
  * @param {string[]} warnings - Mutable warnings list
  */
 function appendTestEndpointWarningIfMissing(authentication, warnings) {
-  const method = String(authentication?.method || '').toLowerCase();
+  const credential = getAuthCredentialTemplate(authentication);
+  const method = String(credential?.method || authentication?.method || '').toLowerCase();
   if (method !== 'apikey' && method !== 'bearertoken') return;
-  const testEndpoint = String(authentication?.variables?.testEndpoint || '').trim();
+  const testEndpoint = String(credential?.variables?.testEndpoint || authentication?.variables?.testEndpoint || '').trim();
   if (testEndpoint) return;
   if (warnings.includes(MISSING_TEST_ENDPOINT_WARNING)) return;
   warnings.push(MISSING_TEST_ENDPOINT_WARNING);
@@ -114,6 +119,25 @@ function auditRepairAuthenticationWarnings(systemParsed, warnings) {
   appendTestEndpointWarningIfMissing(authentication, warnings);
 }
 
+/**
+ * Ensures system file authentication matches nested schema (authType + credential).
+ * @param {Object} systemParsed - Parsed system config (mutated)
+ * @param {string} systemKey
+ * @param {string[]} changes
+ * @returns {boolean}
+ */
+function normalizeAuthenticationSchemaShape(systemParsed, systemKey, changes) {
+  const current = systemParsed.authentication || systemParsed.auth;
+  const { authentication, changed } = migrateAuthenticationToNestedSchema(current, systemKey);
+  if (!changed) {
+    return false;
+  }
+  systemParsed.authentication = authentication;
+  delete systemParsed.auth;
+  changes.push('Normalized authentication to authType + credential (schema 2.4.x)');
+  return true;
+}
+
 module.exports = {
   ALLOWED_REPAIR_AUTH,
   MISSING_TEST_ENDPOINT_WARNING,
@@ -123,5 +147,7 @@ module.exports = {
   mergePreservedAuthVariables,
   repairAuthChangeLabel,
   appendTestEndpointWarningIfMissing,
-  auditRepairAuthenticationWarnings
+  auditRepairAuthenticationWarnings,
+  normalizeAuthenticationSchemaShape,
+  getAuthCredentialTemplate
 };

package/lib/commands/repair-auth-config.js

@@ -8,17 +8,7 @@
 'use strict';
 
 const { systemKeyToKvPrefix, securityKeyToVar, kvEnvKeyToPath } = require('../utils/credential-secrets-env');
-
-/**
- * Returns true if a kv value looks like legacy format (KeyVault suffix or no path segments).
- * @param {string} val - Value from authentication.security or configuration
- * @returns {boolean}
- */
-function isLegacyKvValue(val) {
-  if (typeof val !== 'string' || !val.trim().toLowerCase().startsWith('kv://')) return false;
-  const after = val.trim().slice(5); // after 'kv://'
-  return after.includes('KeyVault') || !after.includes('/');
-}
+const { isLegacyKvValue } = require('../utils/platform-kv-ref');
 
 /**
  * Normalizes authentication.security keyvault entries to path-style kv:// values (kv://systemKey/variable).
@@ -87,7 +77,9 @@ function normalizeConfigurationSection(config, prefix, systemKey, changes) {
 function normalizeSystemFileAuthAndConfig(systemParsed, systemKey, changes) {
   const prefix = systemKeyToKvPrefix(systemKey);
   if (!prefix) return false;
-  const security = systemParsed.authentication?.security;
+  const { getAuthCredentialTemplate } = require('../utils/authentication-shape');
+  const credential = getAuthCredentialTemplate(systemParsed.authentication);
+  const security = credential?.security ?? systemParsed.authentication?.security;
   let updated = (security && typeof security === 'object' && normalizeSecuritySection(security, prefix, systemKey, changes));
   const config = systemParsed.configuration;
   if (Array.isArray(config)) {
@@ -96,4 +88,7 @@ function normalizeSystemFileAuthAndConfig(systemParsed, systemKey, changes) {
   return updated;
 }
 
-module.exports = { normalizeSystemFileAuthAndConfig, isLegacyKvValue };
+module.exports = {
+  normalizeSystemFileAuthAndConfig,
+  isLegacyKvValue
+};

package/lib/commands/repair-datasource-com-v2.js

@@ -0,0 +1,15 @@
+/**
+ * COM v2 datasource manifest repair (capabilities objects, strip context).
+ *
+ * @fileoverview repair-datasource-com-v2
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { repairComV2Manifest } = require('../datasource/capability/capability-manifest');
+
+module.exports = {
+  repairComV2Manifest
+};

package/lib/commands/repair-datasource-service-contract.js

@@ -0,0 +1,206 @@
+/**
+ * serviceContract repair helpers — migrate deprecated none+llm manifests (439.1).
+ *
+ * @fileoverview repair-datasource-service-contract
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const LLM_CANONICAL_METADATA_SCHEMA = {
+  type: 'object',
+  properties: {
+    successContent: { type: 'string', nullable: true },
+    successEmbedding: {
+      type: 'array',
+      items: { type: 'number' },
+      nullable: true
+    },
+    successRole: { type: 'string', nullable: true },
+    successModel: { type: 'string', nullable: true },
+    successFinishReason: { type: 'string', nullable: true },
+    errorCode: { type: 'string', nullable: true },
+    errorMessage: { type: 'string', nullable: true },
+    errorType: { type: 'string', nullable: true },
+    usagePromptTokens: { type: 'integer', nullable: true },
+    usageCompletionTokens: { type: 'integer', nullable: true },
+    usageTotalTokens: { type: 'integer', nullable: true },
+    metadataProvider: { type: 'string', nullable: true },
+    metadataOperation: { type: 'string', nullable: true }
+  }
+};
+
+const LLM_CANONICAL_EXPOSED_SCHEMA = {
+  success: {
+    content: 'metadata.successContent',
+    embedding: 'metadata.successEmbedding',
+    role: 'metadata.successRole',
+    model: 'metadata.successModel',
+    finishReason: 'metadata.successFinishReason'
+  },
+  error: {
+    code: 'metadata.errorCode',
+    message: 'metadata.errorMessage',
+    type: 'metadata.errorType'
+  },
+  usage: {
+    promptTokens: 'metadata.usagePromptTokens',
+    completionTokens: 'metadata.usageCompletionTokens',
+    totalTokens: 'metadata.usageTotalTokens'
+  },
+  metadata: {
+    provider: 'metadata.metadataProvider',
+    operation: 'metadata.metadataOperation'
+  }
+};
+
+const LLM_STUB_FIELD_MAPPINGS = {
+  successContent: { expression: '{{raw}}' },
+  metadataProvider: { expression: '{{inline.metadataProvider}}' },
+  metadataOperation: { expression: '{{inline.metadataOperation}}' }
+};
+
+/**
+ * @param {Object} parsed - Parsed datasource manifest
+ * @returns {boolean}
+ */
+function isDeprecatedNoneLlmManifest(parsed) {
+  return parsed?.entityType === 'none' && parsed?.resourceType === 'llm';
+}
+
+/**
+ * @param {Object} parsed
+ * @param {string[]} changes
+ * @returns {boolean}
+ */
+function stripStorageKeysForServiceContract(parsed, changes) {
+  let updated = false;
+  for (const key of ['primaryKey', 'labelKey', 'sync']) {
+    if (parsed[key] !== undefined) {
+      delete parsed[key];
+      changes.push(`Removed ${key} (not allowed on serviceContract)`);
+      updated = true;
+    }
+  }
+  return updated;
+}
+
+/**
+ * @param {Object} parsed
+ * @param {string} systemKey
+ * @param {string[]} changes
+ * @returns {boolean}
+ */
+function ensureLlmCipMapSteps(parsed, systemKey, changes) {
+  const operations = parsed?.execution?.cip?.operations;
+  if (!operations || typeof operations !== 'object') return false;
+  let updated = false;
+  for (const opKey of ['call', 'embed']) {
+    const op = operations[opKey];
+    if (!op || !Array.isArray(op.steps)) continue;
+    if (op.steps.some((step) => step && step.map)) continue;
+    const fetchIdx = op.steps.findIndex((step) => step && step.fetch);
+    if (fetchIdx < 0) continue;
+    const mapStep = {
+      map: {
+        useFieldMappings: true,
+        inputPath: '$',
+        inline: {
+          metadataProvider: systemKey || parsed.systemKey || 'provider',
+          metadataOperation: opKey
+        }
+      }
+    };
+    op.steps.splice(fetchIdx + 1, 0, mapStep);
+    if (!op.steps.some((step) => step && step.output)) {
+      op.steps.push({ output: { mode: 'records' } });
+    }
+    changes.push(`Inserted map+output steps for CIP operation "${opKey}"`);
+    updated = true;
+  }
+  return updated;
+}
+
+/**
+ * @param {Object} parsed
+ * @param {string[]} changes
+ * @returns {boolean}
+ */
+function stripDeprecatedServiceCategory(parsed, changes) {
+  if (parsed?.serviceCategory === undefined) return false;
+  delete parsed.serviceCategory;
+  changes.push('Removed deprecated serviceCategory (use resourceType for classification)');
+  return true;
+}
+
+/**
+ * @param {*} value
+ * @returns {*}
+ */
+function deepClone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+/**
+ * @param {Object} parsed
+ * @param {string[]} changes
+ * @returns {boolean}
+ */
+function applyCanonicalLlmSchemaStubs(parsed, changes) {
+  parsed.entityType = 'serviceContract';
+  changes.push('Migrated entityType none → serviceContract');
+
+  parsed.metadataSchema = deepClone(LLM_CANONICAL_METADATA_SCHEMA);
+  changes.push('Set canonical LLM metadataSchema stub');
+
+  if (!parsed.exposed) parsed.exposed = {};
+  parsed.exposed.schema = deepClone(LLM_CANONICAL_EXPOSED_SCHEMA);
+  if (parsed.exposed.attributes !== undefined) {
+    delete parsed.exposed.attributes;
+  }
+  changes.push('Set canonical LLM exposed.schema envelope');
+  return true;
+}
+
+/**
+ * @param {Object} parsed
+ * @param {string[]} changes
+ * @returns {boolean}
+ */
+function applyStubFieldMappingsIfMissing(parsed, changes) {
+  const attrs = parsed.fieldMappings?.attributes;
+  if (attrs && typeof attrs === 'object' && Object.keys(attrs).length > 0) {
+    return false;
+  }
+  if (!parsed.fieldMappings) parsed.fieldMappings = {};
+  parsed.fieldMappings.attributes = deepClone(LLM_STUB_FIELD_MAPPINGS);
+  changes.push(
+    'Added stub fieldMappings.attributes — customize provider raw.* expressions'
+  );
+  return true;
+}
+
+/**
+ * Migrate deprecated none+llm manifest to serviceContract canonical stub.
+ *
+ * @param {Object} parsed - Parsed datasource (mutated)
+ * @param {string[]} changes - Change log
+ * @returns {boolean}
+ */
+function repairNoneLlmToServiceContract(parsed, changes) {
+  if (!isDeprecatedNoneLlmManifest(parsed)) return false;
+  let updated = applyCanonicalLlmSchemaStubs(parsed, changes);
+  updated = applyStubFieldMappingsIfMissing(parsed, changes) || updated;
+  updated = stripStorageKeysForServiceContract(parsed, changes) || updated;
+  updated = ensureLlmCipMapSteps(parsed, parsed.systemKey, changes) || updated;
+  return updated;
+}
+
+module.exports = {
+  LLM_CANONICAL_METADATA_SCHEMA,
+  LLM_CANONICAL_EXPOSED_SCHEMA,
+  isDeprecatedNoneLlmManifest,
+  stripDeprecatedServiceCategory,
+  repairNoneLlmToServiceContract
+};