@aifabrix/builder 2.49.2 → 2.50.0

package/lib/utils/paths-reload-source.js

@@ -0,0 +1,148 @@
+/**
+ * Resolve product-repo source roots for platform app --reload bind mounts.
+ *
+ * @fileoverview When builder manifests live under aifabrix-work/builder/<app>, build.context
+ *   ../.. may point at the work root instead of the product repo; reload mounts must target
+ *   the repo that contains app/ or packages/.
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const path = require('path');
+const { isSystemBuilderAppName } = require('./paths-system-builder-keys');
+
+const nodeFs = () => require('../internal/fs-real-sync');
+
+/** @type {Readonly<Record<string, string[]>>} */
+const SYSTEM_APP_SOURCE_REPO_DIR_NAMES = Object.freeze({
+  dataplane: ['aifabrix-dataplane'],
+  'miso-controller': ['aifabrix-miso'],
+  'builder-api': ['aifabrix-builder']
+});
+
+/** @type {Readonly<Record<string, string[]>>} */
+const SYSTEM_APP_RELOAD_MARKERS = Object.freeze({
+  dataplane: ['app/main.py'],
+  'miso-controller': ['packages/miso-controller/package.json'],
+  'builder-api': ['lib/cli.js', 'bin/aifabrix.js']
+});
+
+/**
+ * @param {string} appName
+ * @param {string} rootPath
+ * @returns {boolean}
+ */
+function isValidReloadSourceRoot(appName, rootPath) {
+  if (!rootPath || typeof rootPath !== 'string') {
+    return false;
+  }
+  const markers = SYSTEM_APP_RELOAD_MARKERS[appName];
+  if (!markers || markers.length === 0) {
+    return nodeFs().existsSync(rootPath);
+  }
+  return markers.some((rel) => nodeFs().existsSync(path.join(rootPath, rel)));
+}
+
+/**
+ * @param {string} builderPath
+ * @param {string} [buildContext]
+ * @returns {string}
+ */
+function resolveBuildContextFromBuilder(builderPath, buildContext = '../..') {
+  const ctx = buildContext && typeof buildContext === 'string' ? buildContext : '.';
+  return path.resolve(builderPath, ctx);
+}
+
+/**
+ * @param {{ getAifabrixWork?: () => (string|null), getCwdBuilderAppPath?: (string) => (string|null) }} deps
+ * @returns {{ getWork: () => (string|null), getCwdBuilder: (string) => (string|null) }}
+ */
+function resolveReloadDeps(deps) {
+  return {
+    getWork: deps.getAifabrixWork || (() => require('./paths').getAifabrixWork()),
+    getCwdBuilder: deps.getCwdBuilderAppPath || ((name) => require('./paths').getCwdBuilderAppPath(name))
+  };
+}
+
+/**
+ * @param {string} appName
+ * @param {string} builderPath
+ * @param {string} buildContext
+ * @param {{ getAifabrixWork?: () => (string|null), getCwdBuilderAppPath?: (string) => (string|null) }} deps
+ * @returns {string[]}
+ */
+function collectReloadSourceCandidates(appName, builderPath, buildContext, deps) {
+  const { getWork, getCwdBuilder } = resolveReloadDeps(deps);
+  const candidates = [];
+  const cwdHit = getCwdBuilder(appName);
+  if (cwdHit) {
+    candidates.push(resolveBuildContextFromBuilder(cwdHit, buildContext));
+  }
+
+  const work = getWork();
+  if (!work) {
+    return candidates;
+  }
+
+  const repoNames = SYSTEM_APP_SOURCE_REPO_DIR_NAMES[appName] || [];
+  for (const repoName of repoNames) {
+    candidates.push(path.join(work, repoName));
+  }
+  try {
+    for (const entry of nodeFs().readdirSync(work)) {
+      if (!entry || entry.startsWith('.')) continue;
+      const builderSub = path.join(work, entry, 'builder', appName);
+      if (nodeFs().existsSync(builderSub)) {
+        candidates.push(resolveBuildContextFromBuilder(builderSub, buildContext));
+      }
+    }
+  } catch {
+    // ignore unreadable work root
+  }
+  return candidates;
+}
+
+/**
+ * @param {string} appName
+ * @param {string[]} candidates
+ * @param {string} fallback
+ * @returns {string}
+ */
+function pickFirstValidReloadRoot(appName, candidates, fallback) {
+  for (const candidate of candidates) {
+    if (isValidReloadSourceRoot(appName, candidate)) {
+      return candidate;
+    }
+  }
+  return fallback;
+}
+
+/**
+ * Resolve bind-mount source for `--reload` on platform system apps.
+ *
+ * @param {string} appName
+ * @param {string} builderPath - builder/<app> directory used for run
+ * @param {string} [buildContext='../..'] - build.context from application.yaml
+ * @param {{ getAifabrixWork?: () => (string|null), getCwdBuilderAppPath?: (string) => (string|null) }} [deps]
+ * @returns {string}
+ */
+function resolveSystemAppReloadSourceRoot(appName, builderPath, buildContext = '../..', deps = {}) {
+  const direct = resolveBuildContextFromBuilder(builderPath, buildContext);
+  if (!isSystemBuilderAppName(appName)) {
+    return direct;
+  }
+  if (isValidReloadSourceRoot(appName, direct)) {
+    return direct;
+  }
+  const candidates = collectReloadSourceCandidates(appName, builderPath, buildContext, deps);
+  return pickFirstValidReloadRoot(appName, candidates, direct);
+}
+
+module.exports = {
+  SYSTEM_APP_SOURCE_REPO_DIR_NAMES,
+  SYSTEM_APP_RELOAD_MARKERS,
+  isValidReloadSourceRoot,
+  resolveSystemAppReloadSourceRoot
+};

package/lib/utils/paths-system-builder-keys.js

@@ -0,0 +1,25 @@
+/**
+ * Platform system builder app keys (shared to avoid circular requires in paths.js).
+ *
+ * @fileoverview SYSTEM_BUILDER_APP_KEYS for dataplane, miso-controller, etc.
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const SYSTEM_BUILDER_APP_KEYS = Object.freeze(['keycloak', 'miso-controller', 'dataplane', 'builder-api']);
+
+/**
+ * @param {string} appName
+ * @returns {boolean}
+ */
+function isSystemBuilderAppName(appName) {
+  if (!appName || typeof appName !== 'string') return false;
+  return SYSTEM_BUILDER_APP_KEYS.includes(appName);
+}
+
+module.exports = {
+  SYSTEM_BUILDER_APP_KEYS,
+  isSystemBuilderAppName
+};

package/lib/utils/paths.js

@@ -447,7 +447,7 @@ function getBuilderRoot() {
  * {@link getSystemBuilderRoot} (= {@link getAppsMaterializationParent}`/builder`), never the global CLI package tree.
  * @readonly
  */
-const SYSTEM_BUILDER_APP_KEYS = Object.freeze(['keycloak', 'miso-controller', 'dataplane']);
+const SYSTEM_BUILDER_APP_KEYS = Object.freeze(['keycloak', 'miso-controller', 'dataplane', 'builder-api']);
 
 /**
  * @param {string} appName
@@ -611,6 +611,15 @@ function getIntegrationPath(appName) {
   if (!appName || typeof appName !== 'string') {
     throw new Error('App name is required and must be a string');
   }
+  try {
+    const { getIntegrationPathScope } = require('../programmatic/integration-path-scope');
+    const scope = getIntegrationPathScope();
+    if (scope && typeof scope.resolveIntegrationPath === 'function') {
+      return scope.resolveIntegrationPath(appName);
+    }
+  } catch {
+    // programmatic module optional for CLI-only usage
+  }
   const cwdInt = path.join(path.resolve(process.cwd()), 'integration', appName);
   try {
     if (nodeFs().existsSync(cwdInt)) {
@@ -727,25 +736,81 @@ function isExternalAppType(variables) {
  * @param {string} appName - Application name
  * @returns {Object|null} App type info or null if no config found
  */
-function checkIntegrationFolder(appName) {
-  const integrationPath = getIntegrationPath(appName);
-  let variables;
+function isScopedIntegrationPathActive() {
   try {
-    const configPath = resolveApplicationConfigPath(integrationPath);
-    variables = loadConfigFile(configPath);
+    const { getIntegrationPathScope } = require('../programmatic/integration-path-scope');
+    const scope = getIntegrationPathScope();
+    return Boolean(scope && typeof scope.resolveIntegrationPath === 'function');
   } catch {
+    return false;
+  }
+}
+
+function externalIntegrationFolderResult(appPath, baseDir = 'integration') {
+  return {
+    isExternal: true,
+    appPath,
+    appType: 'external',
+    baseDir
+  };
+}
+
+function isExistingAppDirectory(dirPath) {
+  try {
+    return fs.existsSync(dirPath) && fs.statSync(dirPath).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function resolveExistingWorkspacePath(appName, options) {
+  const { resolveAppWorkspace } = require('./app-path-resolve');
+  const { appPath, baseDir } = resolveAppWorkspace(appName, options);
+  if (isExistingAppDirectory(appPath)) {
+    return { appPath, baseDir };
+  }
+  const altWorkspace =
+    baseDir === 'enterprise-knowledge' ? 'integration' : 'enterprise-knowledge';
+  const alt = resolveAppWorkspace(appName, { ...options, workspace: altWorkspace });
+  if (!isExistingAppDirectory(alt.appPath)) {
     return null;
   }
-  if (variables) {
+  return { appPath: alt.appPath, baseDir: alt.baseDir };
+}
+
+function externalWorkspaceFolderFromConfig(appPath, baseDir, scopedWorkspace) {
+  try {
+    const configPath = resolveApplicationConfigPath(appPath);
+    const variables = loadConfigFile(configPath);
+    if (!variables) {
+      return null;
+    }
     const isExternal = isExternalAppType(variables);
     return {
       isExternal,
-      appPath: integrationPath,
+      appPath,
       appType: isExternal ? 'external' : 'regular',
-      baseDir: 'integration'
+      baseDir
     };
+  } catch {
+    if (scopedWorkspace && isExistingAppDirectory(appPath)) {
+      return externalIntegrationFolderResult(appPath, baseDir);
+    }
+    return null;
   }
-  return null;
+}
+
+function checkExternalWorkspaceFolder(appName, options = {}) {
+  const located = resolveExistingWorkspacePath(appName, options);
+  if (!located) {
+    return null;
+  }
+  const { appPath, baseDir } = located;
+  const scopedWorkspace = isScopedIntegrationPathActive();
+  if (scopedWorkspace && !isExistingAppDirectory(appPath)) {
+    return null;
+  }
+  return externalWorkspaceFolderFromConfig(appPath, baseDir, scopedWorkspace);
 }
 
 /**
@@ -776,6 +841,41 @@ function checkBuilderFolder(appName) {
   }
   return null;
 }
+
+/**
+ * When {@link getBuilderPath} has no application config but the CLI ships
+ * `templates/applications/<appName>/`, materialize `builder/<appName>/` (same as
+ * `ensureAppFromTemplate` for platform apps on `up-miso` / `up-dataplane`).
+ *
+ * @param {string} appName
+ * @returns {Promise<boolean>} True when template was copied
+ */
+async function ensureShippedBuilderAppTemplate(appName) {
+  if (!appName || typeof appName !== 'string') {
+    return false;
+  }
+  if (isSystemBuilderAppName(appName)) {
+    return false;
+  }
+  const projectRoot = getProjectRoot();
+  const templateDir = path.join(projectRoot, 'templates', 'applications', appName);
+  if (!fs.existsSync(templateDir) || !fs.statSync(templateDir).isDirectory()) {
+    return false;
+  }
+  const builderPath = getBuilderPath(appName);
+  try {
+    resolveApplicationConfigPath(builderPath);
+    return false;
+  } catch {
+    // No application config under builder/<appName>; copy shipped template.
+  }
+  const { copyTemplateFiles } = require('../validation/template');
+  const { ensureReadmeForAppPath } = require('../app/readme');
+  await copyTemplateFiles(appName, builderPath);
+  await ensureReadmeForAppPath(builderPath, appName);
+  return true;
+}
+
 /**
  * Detects if an app is external type by checking application config.
  * Resolution order: integration/ first, then builder/; if neither exists, throws.
@@ -786,15 +886,20 @@ function checkBuilderFolder(appName) {
  * @returns {Promise<{isExternal: boolean, appPath: string, appType: string, baseDir?: string}>}
  * @throws {Error} When app not found in integration/ or builder/
  */
-async function detectAppType(appName, _options = {}) {
+async function detectAppType(appName, options = {}) {
   if (!appName || typeof appName !== 'string') {
     throw new Error('App name is required and must be a string');
   }
-  const integrationResult = checkIntegrationFolder(appName);
-  if (integrationResult) return integrationResult;
+  const externalResult = checkExternalWorkspaceFolder(appName, options);
+  if (externalResult) return externalResult;
   const builderResult = checkBuilderFolder(appName);
   if (builderResult) return builderResult;
-  throw new Error(`App '${appName}' not found in integration/${appName} or builder/${appName}`);
+  await ensureShippedBuilderAppTemplate(appName);
+  const builderAfterTemplate = checkBuilderFolder(appName);
+  if (builderAfterTemplate) return builderAfterTemplate;
+  throw new Error(
+    `App '${appName}' not found in integration/${appName}, enterprise-knowledge/${appName}, or builder/${appName}`
+  );
 }
 
 /**
@@ -808,19 +913,32 @@ async function detectAppType(appName, _options = {}) {
  * @returns {Promise<{appPath: string, envOnly: boolean}>} appPath and envOnly (true when only env.template is used)
  * @throws {Error} When app not found in integration or builder
  */
-async function getResolveAppPath(appName) {
+function tryResolveEnvOnlyPath(dirPath) {
+  const envTemplatePath = path.join(dirPath, 'env.template');
+  if (!fs.existsSync(dirPath) || !fs.existsSync(envTemplatePath)) {
+    return null;
+  }
+  try {
+    resolveApplicationConfigPath(dirPath);
+    return { appPath: dirPath, envOnly: false };
+  } catch {
+    return { appPath: dirPath, envOnly: true };
+  }
+}
+
+async function getResolveAppPath(appName, options = {}) {
   if (!appName || typeof appName !== 'string') {
     throw new Error('App name is required and must be a string');
   }
-  const integrationPath = getIntegrationPath(appName);
-  const envTemplatePath = path.join(integrationPath, 'env.template');
-  if (fs.existsSync(integrationPath) && fs.existsSync(envTemplatePath)) {
-    try {
-      resolveApplicationConfigPath(integrationPath);
-      return { appPath: integrationPath, envOnly: false };
-    } catch {
-      return { appPath: integrationPath, envOnly: true };
-    }
+  const { resolveAppWorkspace } = require('./app-path-resolve');
+  const { appPath: workspacePath } = resolveAppWorkspace(appName, options);
+  const workspaceHit = tryResolveEnvOnlyPath(workspacePath);
+  if (workspaceHit) {
+    return workspaceHit;
+  }
+  const integrationHit = tryResolveEnvOnlyPath(getIntegrationPath(appName));
+  if (integrationHit) {
+    return integrationHit;
   }
   const { resolveApplicationManifestPathSync } = require('./manifest-location');
   const manifestHit = resolveApplicationManifestPathSync({
@@ -831,7 +949,7 @@ async function getResolveAppPath(appName) {
   if (manifestHit) {
     return { appPath: manifestHit.absolutePath, envOnly: false };
   }
-  const result = await detectAppType(appName);
+  const result = await detectAppType(appName, options);
   return { appPath: result.appPath, envOnly: false };
 }
 
@@ -918,9 +1036,16 @@ module.exports = {
   getDeployJsonPath,
   resolveApplicationConfigPath,
   resolveRbacPath,
+  ensureShippedBuilderAppTemplate,
   detectAppType,
   getResolveAppPath,
   resolveIntegrationAppKeyFromCwd,
-  clearProjectRootCache
+  clearProjectRootCache,
+  resolveSystemAppReloadSourceRoot: require('./paths-reload-source').resolveSystemAppReloadSourceRoot,
+  getEnterpriseKnowledgePath: require('./enterprise-knowledge-paths').getEnterpriseKnowledgePath,
+  getEnterpriseKnowledgeRoot: require('./enterprise-knowledge-paths').getEnterpriseKnowledgeRoot,
+  listEnterpriseKnowledgeAnchors: require('./enterprise-knowledge-paths').listEnterpriseKnowledgeAnchors,
+  resolveAppWorkspace: require('./app-path-resolve').resolveAppWorkspace,
+  resolveExternalSystemPath: require('./app-path-resolve').resolveExternalSystemPath
 };
 

package/lib/utils/runtime-configuration-values.js

@@ -44,6 +44,65 @@ function collectSystemVariablePutRequests(systemConfiguration, envMap) {
   return requests;
 }
 
+/** OpenAPI path param names resolved from env.template (not valid configuration[] names). */
+const OPENAPI_PATH_PARAM_ENV_KEYS = ['systemKey', 'pillar'];
+
+const PATH_PARAM_FALLBACK_ENV_KEYS = {
+  systemKey: 'E2E_SYSTEM_KEY',
+  pillar: 'E2E_CERTIFY_PILLAR'
+};
+
+/**
+ * @param {unknown} raw
+ * @param {{ allowKv?: boolean }} [options]
+ * @returns {string|null}
+ */
+function resolvedEnvLiteral(raw, options = {}) {
+  if (raw === undefined || raw === null) {
+    return null;
+  }
+  const value = String(raw).trim();
+  if (!value || value.includes('{{')) {
+    return null;
+  }
+  if (!options.allowKv && value.startsWith('kv://')) {
+    return null;
+  }
+  return value;
+}
+
+function resolvePathParamValue(envMap, name) {
+  const direct = resolvedEnvLiteral(envMap[name]);
+  if (direct) {
+    return direct;
+  }
+  const fallbackKey = PATH_PARAM_FALLBACK_ENV_KEYS[name];
+  if (!fallbackKey) {
+    return null;
+  }
+  return resolvedEnvLiteral(envMap[fallbackKey], { allowKv: true });
+}
+
+/**
+ * @param {Object.<string, string>} envMap
+ * @param {Set<string>} [alreadyPushed]
+ * @returns {Array<{ name: string, value: string }>}
+ */
+function collectOpenApiPathParamAliasPutRequests(envMap, alreadyPushed = new Set()) {
+  const requests = [];
+  for (const name of OPENAPI_PATH_PARAM_ENV_KEYS) {
+    if (alreadyPushed.has(name)) {
+      continue;
+    }
+    const value = resolvePathParamValue(envMap, name);
+    if (!value) {
+      continue;
+    }
+    requests.push({ name, value });
+  }
+  return requests;
+}
+
 /**
  * Datasource overrides are name+value only; values may already be resolved in upload payload.
  *
@@ -83,7 +142,7 @@ function collectDatasourceOverridePutRequests(datasourceConfiguration) {
  * @returns {Promise<{ pushed: number, names: string[] }>}
  */
 async function pushRuntimeConfigurationValues(dataplaneUrl, authConfig, systemKey, payload) {
-  const { envMap } = await buildResolvedEnvMapForIntegration(systemKey);
+  const { envMap } = await buildResolvedEnvMapForIntegration(systemKey, { dataplaneRuntime: true });
   const names = [];
   let pushed = 0;
 
@@ -91,7 +150,9 @@ async function pushRuntimeConfigurationValues(dataplaneUrl, authConfig, systemKe
     payload?.application?.configuration,
     envMap
   );
-  for (const body of systemRequests) {
+  const pushedNames = new Set(systemRequests.map((r) => r.name));
+  const aliasRequests = collectOpenApiPathParamAliasPutRequests(envMap, pushedNames);
+  for (const body of [...systemRequests, ...aliasRequests]) {
     await putExternalSystemConfiguration(dataplaneUrl, systemKey, authConfig, body);
     names.push(body.name);
     pushed += 1;
@@ -114,6 +175,7 @@ async function pushRuntimeConfigurationValues(dataplaneUrl, authConfig, systemKe
 
 module.exports = {
   collectSystemVariablePutRequests,
+  collectOpenApiPathParamAliasPutRequests,
   collectDatasourceOverridePutRequests,
   pushRuntimeConfigurationValues
 };

package/lib/utils/secrets-helpers.js

@@ -226,7 +226,11 @@ function replaceKvInContent(content, secrets, envVars, scopedKv = null) {
           return envVars[envVar] || m;
         });
       }
-      return value !== null && value !== undefined ? String(value) : match;
+      if (value !== null && value !== undefined) {
+        const { formatDotenvSubstitutionValue } = require('./env-dotenv-format');
+        return formatDotenvSubstitutionValue(String(value));
+      }
+      return match;
     });
     return replaced + suffix;
   });

package/lib/utils/ssh-known-hosts.js

@@ -0,0 +1,130 @@
+/**
+ * Remove stale OpenSSH known_hosts entries after server reprovision or Host alias rename.
+ *
+ * @fileoverview ssh-keygen -R helpers for dev init / refresh
+ * @author AI Fabrix Team
+ * @version 1.0.0
+ */
+
+'use strict';
+
+const { execFile } = require('child_process');
+const { promisify } = require('util');
+const path = require('path');
+const { getDefaultSshDir } = require('./ssh-key-helper');
+const { getDevSshHostAlias, resolveDevSshHostAlias } = require('./dev-ssh-config-helper');
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * @param {string} baseUrl
+ * @returns {string|null}
+ */
+function hostnameFromBaseUrl(baseUrl) {
+  if (!baseUrl || typeof baseUrl !== 'string') return null;
+  const s = baseUrl.trim().replace(/\/+$/, '');
+  const withProtocol = /^https?:\/\//i.test(s) ? s : `https://${s}`;
+  try {
+    return new URL(withProtocol).hostname || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string} hostname
+ * @param {string} knownHostsPath
+ * @returns {Promise<{ hostname: string, ok: boolean, error?: string }>}
+ */
+async function removeKnownHostEntry(hostname, knownHostsPath) {
+  const host = String(hostname || '').trim();
+  if (!host) {
+    return { hostname: host, ok: false, error: 'empty hostname' };
+  }
+  try {
+    await execFileAsync('ssh-keygen', ['-R', host, '-f', knownHostsPath], {
+      encoding: 'utf8'
+    });
+    return { hostname: host, ok: true };
+  } catch (err) {
+    if (err && err.code === 'ENOENT') {
+      return { hostname: host, ok: false, error: 'ssh-keygen not found' };
+    }
+    return { hostname: host, ok: false, error: err.message || String(err) };
+  }
+}
+
+/**
+ * Hostnames that may appear in known_hosts for a Builder dev SSH connection.
+ * Includes current Host alias, HostName (sync-ssh-host), remote-server host, and legacy Host aliases.
+ *
+ * @param {Object} p
+ * @param {string} p.syncHost - sync-ssh-host / HostName
+ * @param {string} p.syncUser - sync-ssh-user
+ * @param {string} [p.hostAlias] - Preferred ssh config Host alias
+ * @param {string} [p.baseUrl] - remote-server URL
+ * @param {string} [p.developerId]
+ * @param {string} [p.developerRootDomain]
+ * @param {string[]} [p.legacyHostAliases] - Previous Host keywords from ~/.ssh/config
+ * @returns {string[]}
+ */
+function collectDevSshKnownHostCandidates(p) {
+  const syncHost = String(p.syncHost || '').trim();
+  const syncUser = String(p.syncUser || '').trim();
+  const candidates = new Set();
+  if (syncHost) {
+    candidates.add(syncHost);
+  }
+  if (p.hostAlias) {
+    candidates.add(String(p.hostAlias).trim());
+  }
+  const preferred = resolveDevSshHostAlias({
+    syncUser,
+    syncHost,
+    developerId: p.developerId,
+    developerRootDomain: p.developerRootDomain
+  });
+  if (preferred) {
+    candidates.add(preferred);
+  }
+  if (syncUser && syncHost) {
+    candidates.add(getDevSshHostAlias(syncUser, syncHost));
+  }
+  const fromUrl = hostnameFromBaseUrl(p.baseUrl);
+  if (fromUrl) {
+    candidates.add(fromUrl);
+  }
+  for (const alias of p.legacyHostAliases || []) {
+    const trimmed = String(alias || '').trim();
+    if (trimmed) {
+      candidates.add(trimmed);
+    }
+  }
+  return [...candidates].filter(Boolean);
+}
+
+/**
+ * @param {string[]} hostnames
+ * @param {string} [sshDir]
+ * @returns {Promise<{ cleared: string[], failed: Array<{ hostname: string, error: string }> }>}
+ */
+async function refreshDevSshKnownHosts(hostnames, sshDir) {
+  const knownHostsPath = path.join(sshDir || getDefaultSshDir(), 'known_hosts');
+  const cleared = [];
+  const failed = [];
+  for (const hostname of hostnames) {
+    const result = await removeKnownHostEntry(hostname, knownHostsPath);
+    if (result.ok) {
+      cleared.push(result.hostname);
+    } else if (result.error && result.error !== 'empty hostname') {
+      failed.push({ hostname: result.hostname, error: result.error });
+    }
+  }
+  return { cleared, failed };
+}
+
+module.exports = {
+  collectDevSshKnownHostCandidates,
+  removeKnownHostEntry,
+  refreshDevSshKnownHosts
+};