@aifabrix/builder 2.42.1 → 2.44.0

package/scripts/check-datasource-test-run-schema-sync.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/**
+ * CI helper: fail when Builder lib/schema/datasource-test-run.schema.json drifts from Dataplane copy.
+ * @fileoverview Schema sync gate (plan §8.1)
+ */
+/* eslint-disable no-console -- CLI script */
+
+const path = require('path');
+const { assertDatasourceTestRunSchemasInSync } = require('../lib/utils/datasource-test-run-schema-sync');
+
+const root = path.join(__dirname, '..');
+const builderSchema = path.join(root, 'lib/schema/datasource-test-run.schema.json');
+const dpRoot = process.env.AIFABRIX_DATAPLANE_ROOT || path.join(root, '..', 'aifabrix-dataplane');
+const dataplaneSchema = path.join(dpRoot, 'app/schemas/json/datasource-test-run.schema.json');
+
+const strict = process.env.AIFABRIX_SCHEMA_SYNC_STRICT === '1';
+
+try {
+  const result = assertDatasourceTestRunSchemasInSync(builderSchema, dataplaneSchema);
+  if (result.skipped) {
+    const msg = result.reason || 'Dataplane schema path missing';
+    if (strict) {
+      console.error(`Schema sync failed (strict): ${msg}`);
+      process.exit(1);
+    }
+    console.warn(`Schema sync skipped: ${msg}`);
+    process.exit(0);
+  }
+  console.log(`DatasourceTestRun schema OK (sha256 ${result.builderSha})`);
+  process.exit(0);
+} catch (e) {
+  console.error(e.message || String(e));
+  process.exit(1);
+}

package/scripts/diagnose-cli.js

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+
+/**
+ * List every PATH hit for aifabrix / af and each --version (find duplicate installs).
+ *
+ * @fileoverview CLI path diagnostic for @aifabrix/builder
+ */
+
+const { execFileSync, execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Reads package.json `bin` field.
+ * @returns {Record<string, string>|string} Bin map or single path string
+ */
+function readBins() {
+  const pkgPath = path.join(__dirname, '..', 'package.json');
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+  return pkg.bin || { aifabrix: 'bin/aifabrix.js' };
+}
+
+/**
+ * Resolves every PATH directory that exposes an executable named `binName`.
+ * @param {string} binName - CLI name (e.g. aifabrix)
+ * @returns {Array<{ path: string, real: string }>} Deduped hits with real paths
+ */
+function locationsOnPath(binName) {
+  if (process.platform === 'win32') {
+    try {
+      const out = execSync(`where ${binName}`, {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore']
+      }).trim();
+      return out.split(/\r?\n/).filter(Boolean).map((p) => ({ path: p, real: p }));
+    } catch {
+      return [];
+    }
+  }
+
+  const dirs = (process.env.PATH || '').split(path.delimiter).filter(Boolean);
+  const out = [];
+  const seenReal = new Set();
+  for (const dir of dirs) {
+    const candidate = path.join(dir, binName);
+    try {
+      const st = fs.lstatSync(candidate);
+      if (!st.isFile() && !st.isSymbolicLink()) continue;
+      fs.accessSync(candidate, fs.constants.X_OK);
+      const real = fs.realpathSync(candidate);
+      if (seenReal.has(real)) continue;
+      seenReal.add(real);
+      out.push({ path: candidate, real });
+    } catch {
+      // not found or not executable
+    }
+  }
+  return out;
+}
+
+/**
+ * Runs `executablePath --version` and returns stdout or null on failure.
+ * @param {string} executablePath - Absolute path to the binary
+ * @returns {string|null} Trimmed version output
+ */
+function versionAt(executablePath) {
+  try {
+    return execFileSync(executablePath, ['--version'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore']
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Prints PNPM_HOME and npm prefix for debugging PATH issues.
+ * @returns {void}
+ */
+function printEnvironment() {
+  console.log('Environment (relevant to global CLIs)\n');
+  console.log(`  PNPM_HOME     ${process.env.PNPM_HOME || '(not set)'}`);
+  try {
+    const prefix = execSync('npm config get prefix', {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore']
+    }).trim();
+    console.log(`  npm prefix    ${prefix}`);
+  } catch {
+    console.log('  npm prefix    (could not read)');
+  }
+  console.log('');
+}
+
+/**
+ * @param {string[]} names - Bin names from package.json
+ * @returns {void}
+ */
+function printBinReports(names) {
+  for (const name of names) {
+    console.log(`── ${name} ──`);
+    const hits = locationsOnPath(name);
+    if (!hits.length) {
+      console.log('  (not found on PATH)\n');
+      continue;
+    }
+    hits.forEach((h, i) => {
+      const ver = versionAt(h.path);
+      const marker = i === 0 ? '  ← first on PATH (what your shell runs)' : '';
+      console.log(`  [${i + 1}] ${h.path}`);
+      if (h.real !== h.path) console.log(`      → ${h.real}`);
+      console.log(`      --version: ${ver ?? '(failed to run)'}${marker}`);
+    });
+    console.log('');
+  }
+}
+
+/**
+ * @param {string[]} names - Bin names from package.json
+ * @returns {void}
+ */
+function warnIfMultipleVersions(names) {
+  const uniqVersions = new Set();
+  for (const name of names) {
+    for (const h of locationsOnPath(name)) {
+      const v = versionAt(h.path);
+      if (v) uniqVersions.add(v);
+    }
+  }
+  if (uniqVersions.size > 1) {
+    console.log('⚠  Multiple distinct --version values above: remove or reorder PATH so only one install remains.');
+    console.log('   Often: npm uninstall -g @aifabrix/builder, then ensure PNPM_HOME is before /usr/local/bin in PATH.\n');
+  }
+}
+
+/**
+ * Entry: list PATH hits and versions for each package bin.
+ * @returns {void}
+ */
+function main() {
+  const binField = readBins();
+  const names = typeof binField === 'string' ? ['aifabrix'] : Object.keys(binField);
+  printEnvironment();
+  printBinReports(names);
+  warnIfMultipleVersions(names);
+}
+
+main();

package/scripts/install-local.js

@@ -10,38 +10,157 @@
  * @version 2.0.0
  */
 
-const { execSync } = require('child_process');
+const { execSync, execFileSync } = require('child_process');
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
 
+const PACKAGE_NAME = '@aifabrix/builder';
+/** Primary CLI name used for “current version” before link */
+const PRIMARY_BIN = 'aifabrix';
+
+/**
+ * Default PNPM_HOME when not set in the environment (matches `pnpm setup` on Linux/macOS; Windows uses LOCALAPPDATA).
+ * @returns {string} Resolved PNPM global bin home directory
+ */
+function defaultPnpmHome() {
+  if (process.env.PNPM_HOME) {
+    return process.env.PNPM_HOME;
+  }
+  if (process.platform === 'win32' && process.env.LOCALAPPDATA) {
+    return path.join(process.env.LOCALAPPDATA, 'pnpm');
+  }
+  return path.join(os.homedir(), '.local', 'share', 'pnpm');
+}
+
+/**
+ * Environment with PNPM_HOME and PATH set so `pnpm link --global` can find the global bin dir
+ * (same idea as aifabrix-setup/scripts/install-local.js).
+ * @returns {NodeJS.ProcessEnv} Copy of process.env with pnpm paths prepended
+ */
+function pnpmEnv() {
+  const env = { ...process.env };
+  const pnpmHome = defaultPnpmHome();
+  env.PNPM_HOME = pnpmHome;
+  env.PATH = [pnpmHome, env.PATH].filter(Boolean).join(path.delimiter);
+  return env;
+}
+
 /**
  * Detect which package manager is being used (pnpm or npm)
  * @returns {string} 'pnpm' or 'npm'
  */
 function detectPackageManager() {
   try {
-    // Check if pnpm is available
     execSync('which pnpm', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
     return 'pnpm';
   } catch {
-    // Fall back to npm
     return 'npm';
   }
 }
 
 /**
- * Get currently installed version of aifabrix CLI
- * @returns {string|null} Version string or null if not installed
+ * Reads package.json `bin` keys (or default primary bin).
+ * @returns {string[]} CLI executable names published by this package
+ */
+function listCliBinNames() {
+  try {
+    const packageJsonPath = path.join(__dirname, '..', 'package.json');
+    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+    const bin = packageJson.bin;
+    if (!bin) return [PRIMARY_BIN];
+    if (typeof bin === 'string') return [PRIMARY_BIN];
+    return Object.keys(bin);
+  } catch {
+    return [PRIMARY_BIN];
+  }
+}
+
+/**
+ * @param {string} binName - CLI name on PATH
+ * @param {NodeJS.ProcessEnv} [env] - Optional env (e.g. pnpm-adjusted PATH)
+ * @returns {string|null} Trimmed `--version` output or null if command fails
+ */
+function getBinVersion(binName, env) {
+  try {
+    return execSync(`${binName} --version`, {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      env: env || process.env
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {string} binName - CLI name on PATH
+ * @param {NodeJS.ProcessEnv} [env] - Optional env for `which`
+ * @returns {string|null} First resolved path or null
+ */
+function getBinPath(binName, env) {
+  try {
+    const which = execSync(`which ${binName}`, {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      env: env || process.env
+    }).trim();
+    return which || null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * First executable `binName` on PATH (same resolution order as a POSIX shell).
+ * @param {string} binName - CLI name
+ * @param {string} pathString - PATH value (e.g. process.env.PATH)
+ * @returns {{ candidate: string, real: string }|null} First hit or null
+ */
+function firstExecutableOnPath(binName, pathString) {
+  if (process.platform === 'win32') {
+    return null;
+  }
+  const dirs = (pathString || '').split(path.delimiter).filter(Boolean);
+  for (const dir of dirs) {
+    const candidate = path.join(dir, binName);
+    try {
+      const st = fs.lstatSync(candidate);
+      if (!st.isFile() && !st.isSymbolicLink()) continue;
+      fs.accessSync(candidate, fs.constants.X_OK);
+      const real = fs.realpathSync(candidate);
+      return { candidate, real };
+    } catch {
+      // continue
+    }
+  }
+  return null;
+}
+
+/**
+ * @param {string} executablePath - Absolute path to CLI
+ * @returns {string|null} Trimmed --version or null
  */
-function getCurrentVersion() {
+function versionAtExecutablePath(executablePath) {
   try {
-    const version = execSync('aifabrix --version', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
-    return version;
+    return execFileSync(executablePath, ['--version'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore']
+    }).trim();
   } catch {
     return null;
   }
 }
 
+/**
+ * Get currently installed version of primary CLI (aifabrix)
+ * @param {NodeJS.ProcessEnv} [env] - Optional env for the version probe
+ * @returns {string|null} Trimmed version or null if not on PATH
+ */
+function getCurrentVersion(env) {
+  return getBinVersion(PRIMARY_BIN, env);
+}
+
 /**
  * Get version from local package.json
  * @returns {string|null} Version string or null if not found
@@ -81,53 +200,192 @@ function displayVersionInfo(currentVersion, packageVersion) {
   }
 }
 
+/**
+ * @typedef {{ name: string, path: string|null, real: string|null, version: string|null }} PathBinRow
+ */
+
+/**
+ * @param {string[]} binNames - CLI names from package.json
+ * @returns {PathBinRow[]} Resolution rows for current PATH
+ */
+function collectPathResolutionRows(binNames) {
+  const rows = [];
+  if (process.platform === 'win32') {
+    for (const name of binNames) {
+      const p = getBinPath(name, process.env);
+      const version = p
+        ? versionAtExecutablePath(p) || getBinVersion(name, process.env)
+        : getBinVersion(name, process.env);
+      rows.push({ name, path: p, real: p, version });
+    }
+    return rows;
+  }
+  for (const name of binNames) {
+    const hit = firstExecutableOnPath(name, process.env.PATH);
+    if (!hit) {
+      rows.push({ name, path: null, real: null, version: null });
+      continue;
+    }
+    const version =
+      versionAtExecutablePath(hit.candidate) || getBinVersion(name, process.env);
+    rows.push({ name, path: hit.candidate, real: hit.real, version });
+  }
+  return rows;
+}
+
+/**
+ * @param {PathBinRow[]} rows - Rows from collectPathResolutionRows
+ * @param {boolean} multipleBins - Whether package exposes more than one CLI name
+ * @returns {void}
+ */
+function printPathResolutionTable(rows, multipleBins) {
+  const label = multipleBins
+    ? 'First match on your PATH for each command (what new programs see):'
+    : 'First match on your PATH (what new programs see):';
+  console.log(`\n${label}`);
+  for (const r of rows) {
+    if (!r.path) {
+      console.log(`   ${r.name}: (not found on PATH)`);
+      continue;
+    }
+    const ver = r.version !== null && r.version !== undefined ? r.version : '(could not run --version)';
+    const arrow = r.real !== r.path ? ` → ${r.real}` : '';
+    console.log(`   ${r.name}: ${r.path}${arrow}  →  ${ver}`);
+  }
+}
+
+/**
+ * @param {PathBinRow[]} rows - Rows from collectPathResolutionRows
+ * @param {string|null} expectedVersion - Linked package version
+ * @param {string[]} binNames - Bin names (length for multi-alias tip)
+ * @returns {void}
+ */
+function printPathResolutionWarnings(rows, expectedVersion, binNames) {
+  const versions = rows
+    .map((r) => r.version)
+    .filter((v) => v !== null && v !== undefined && v !== '(could not run --version)');
+  const uniq = [...new Set(versions)];
+  const mismatchAliases = uniq.length > 1;
+  const hasStaleVers =
+    Boolean(expectedVersion) &&
+    rows.some(
+      (r) => r.version !== null && r.version !== undefined && r.version !== expectedVersion
+    );
+
+  if (hasStaleVers) {
+    console.log(`\n⚠️  At least one command above is not ${expectedVersion} (linked package version).`);
+    console.log('   Another install is winning on PATH for that name — often an old npm global copy.');
+    console.log('   Try:  pnpm run diagnose:cli');
+    console.log(`   Then: npm uninstall -g ${PACKAGE_NAME}`);
+    console.log('   Put PNPM_HOME (or ~/.local/share/pnpm) before other global bin dirs in PATH if needed.');
+  }
+
+  if (mismatchAliases) {
+    console.log('\n⚠️  `af` and `aifabrix` resolve to different installs on PATH.');
+    console.log('   Fix PATH as above, or if PATH looks correct, your shell may be using a stale location for one of them.');
+    console.log('   Bash: hash -r    Zsh: rehash    Then run both with --version again.');
+  } else if (binNames.length > 1 && expectedVersion && uniq.length === 1 && uniq[0] === expectedVersion) {
+    console.log('\nTip: Bash caches `af` and `aifabrix` separately. If your terminal shows a wrong version for only one, run: hash -r');
+  }
+}
+
+/**
+ * Report first PATH hit per bin (matches new subprocesses). Warn on mismatch vs link or between aliases.
+ * Bash/zsh cache each command name separately — `af` can stay stale while `aifabrix` updates; suggest hash -r.
+ * @param {string|null} expectedVersion - Version from the linked package (pnpm env probe)
+ * @param {string[]} binNames - All bin entries from package.json
+ * @returns {void}
+ */
+function reportCliAliasesOnPath(expectedVersion, binNames) {
+  if (!binNames.length) return;
+  const rows = collectPathResolutionRows(binNames);
+  printPathResolutionTable(rows, binNames.length > 1);
+  printPathResolutionWarnings(rows, expectedVersion, binNames);
+}
+
+/**
+ * Prints pnpm-specific hints when shell PATH still resolves an old binary.
+ * @param {boolean} usedPnpm - Whether link used pnpm
+ * @param {string|null} newVersion - Version after link
+ * @param {Object} [pathInfo] - Shell vs linked path probe
+ * @param {string|null} [pathInfo.versionInShell] - Version from default shell env
+ * @param {string|null} [pathInfo.linkedPath] - Path under pnpm env
+ * @returns {void}
+ */
+function printPnpmPathHints(usedPnpm, newVersion, pathInfo) {
+  if (!usedPnpm) return;
+  const shellVersion = pathInfo && pathInfo.versionInShell;
+  const linkedPath = pathInfo && pathInfo.linkedPath;
+  if (newVersion && shellVersion !== newVersion) {
+    console.log(`\n⚠️  Your shell is still running an older ${PRIMARY_BIN} (${shellVersion || 'unknown'}).`);
+    console.log(`   The linked binary is at: ${linkedPath || 'unknown'}`);
+    console.log('   Fix: run  source ~/.bashrc  (or open a new terminal).');
+    console.log('   If it still shows the old version, put pnpm\'s global bin first in PATH, or run:');
+    console.log(`   npm uninstall -g ${PACKAGE_NAME}`);
+  } else {
+    console.log('If you still see an old version, run: source ~/.bashrc  (or open a new terminal)');
+  }
+}
+
 /**
  * Display success message with version information
  * @param {string|null} currentVersion - Version before linking
  * @param {string|null} newVersion - Version after linking
+ * @param {boolean} [usedPnpm] - Link used pnpm
+ * @param {Object} [pathInfo] - Optional shell vs linked path info
+ * @param {string|null} [pathInfo.versionInShell] - Version from default shell env
+ * @param {string|null} [pathInfo.linkedPath] - Path under pnpm env
+ * @param {string[]} [binNames] - Bin names from package.json
  * @returns {void}
  */
-function displaySuccessMessage(currentVersion, newVersion) {
-  console.log('\n✅ Successfully linked!');
+function displaySuccessMessage(currentVersion, newVersion, usedPnpm, pathInfo, binNames) {
+  const bins = binNames && binNames.length ? binNames : [PRIMARY_BIN];
+  console.log('\n✔ Successfully linked!');
   if (currentVersion && newVersion && currentVersion !== newVersion) {
     console.log(`📊 Version updated: ${currentVersion} → ${newVersion}`);
   } else if (newVersion) {
     console.log(`📊 Installed version: ${newVersion}`);
   }
-  console.log('Run "aifabrix --version" to verify.');
+  const verifyHint =
+    bins.length > 1
+      ? bins.map((b) => `${b} --version`).join('" or "')
+      : `${bins[0]} --version`;
+  console.log(`Run "${verifyHint}" to verify.`);
+  if (bins.length > 1) {
+    console.log(
+      'If only one alias shows the wrong version in your terminal, clear the shell command cache (bash: hash -r, zsh: rehash).'
+    );
+  }
+
+  printPnpmPathHints(usedPnpm, newVersion, pathInfo);
+  reportCliAliasesOnPath(newVersion, bins);
 }
 
 /**
- * Run pnpm link --global and npm link from project root (handles pnpm global bin not set).
- * @param {string} projectRoot - Path to project root
+ * Runs global link and reports success (throws on failure).
+ * @param {string} pm - 'pnpm' or 'npm'
+ * @param {string|null} currentVersion - Version before link
+ * @param {string[]} binNames - CLI bin names
  * @returns {void}
- * @throws {Error} If linking fails when pnpm global bin is not configured
  */
-function runPnpmLink(projectRoot) {
-  let pnpmLinked = false;
-  try {
-    execSync('pnpm link --global', { stdio: 'inherit', cwd: projectRoot });
-    pnpmLinked = true;
-  } catch (pnpmErr) {
-    const msg = (pnpmErr.message || String(pnpmErr));
-    if (msg.includes('global bin directory') || msg.includes('ERR_PNPM_NO_GLOBAL_BIN_DIR')) {
-      console.log(
-        '⚠️  pnpm global bin is not set up. Run "pnpm setup" and add PNPM_HOME to PATH, or we will use npm link.\n'
-      );
-    } else {
-      throw pnpmErr;
-    }
-  }
-  try {
+function runGlobalLink(pm, currentVersion, binNames) {
+  const projectRoot = path.join(__dirname, '..');
+  const env = pm === 'pnpm' ? pnpmEnv() : undefined;
+  if (pm === 'pnpm') {
+    execSync('pnpm link --global', { stdio: 'inherit', cwd: projectRoot, env });
+  } else {
     execSync('npm link', { stdio: 'inherit', cwd: projectRoot });
-  } catch {
-    if (!pnpmLinked) {
-      console.error(
-        '\n💡 To fix: run "pnpm setup" and add the suggested line to your shell config, then run install:local again.'
-      );
-      throw new Error('Linking failed. pnpm global bin not configured and npm link failed.');
-    }
   }
+
+  const newVersion = getCurrentVersion(env);
+  let pathInfo;
+  if (pm === 'pnpm') {
+    pathInfo = {
+      versionInShell: getCurrentVersion(),
+      linkedPath: getBinPath(PRIMARY_BIN, env)
+    };
+  }
+  displaySuccessMessage(currentVersion, newVersion, pm === 'pnpm', pathInfo, binNames);
 }
 
 /**
@@ -137,23 +395,17 @@ function runPnpmLink(projectRoot) {
 function installLocal() {
   const pm = detectPackageManager();
   const packageVersion = getPackageVersion();
+  const binNames = listCliBinNames();
   const currentVersion = getCurrentVersion();
 
   console.log(`Detected package manager: ${pm}\n`);
   displayVersionInfo(currentVersion, packageVersion);
-  console.log('Linking @aifabrix/builder globally...\n');
+  console.log(`Linking ${PACKAGE_NAME} globally...\n`);
 
   try {
-    const projectRoot = path.join(__dirname, '..');
-    if (pm === 'pnpm') {
-      runPnpmLink(projectRoot);
-    } else {
-      execSync('npm link', { stdio: 'inherit', cwd: projectRoot });
-    }
-    const newVersion = getCurrentVersion();
-    displaySuccessMessage(currentVersion, newVersion);
+    runGlobalLink(pm, currentVersion, binNames);
   } catch (error) {
-    console.error('\n❌ Failed to link package:', error.message);
+    console.error('\n✖ Failed to link package:', error.message);
     process.exit(1);
   }
 }
@@ -192,7 +444,7 @@ function displayUninstallVersionInfo(currentVersion, packageVersion) {
  * @returns {void}
  */
 function displayUninstallSuccess(pm, currentVersion) {
-  console.log(`\n✅ Successfully unlinked with ${pm}!`);
+  console.log(`\n✔ Successfully unlinked with ${pm}!`);
   if (currentVersion) {
     console.log(`📊 Uninstalled version: ${currentVersion}`);
   }
@@ -208,22 +460,19 @@ function uninstallLocal() {
   const packageVersion = getPackageVersion();
 
   console.log(`Detected package manager: ${pm}\n`);
-
-  // Show version information before unlinking
   displayUninstallVersionInfo(currentVersion, packageVersion);
-
-  console.log('Unlinking @aifabrix/builder globally...\n');
+  console.log(`Unlinking ${PACKAGE_NAME} globally...\n`);
 
   try {
     if (pm === 'pnpm') {
-      execSync('pnpm unlink --global @aifabrix/builder', { stdio: 'inherit' });
+      execSync(`pnpm unlink --global ${PACKAGE_NAME}`, { stdio: 'inherit', env: pnpmEnv() });
       displayUninstallSuccess(pm, currentVersion);
     } else {
-      execSync('npm unlink -g @aifabrix/builder', { stdio: 'inherit' });
+      execSync(`npm unlink -g ${PACKAGE_NAME}`, { stdio: 'inherit' });
       displayUninstallSuccess(pm, currentVersion);
     }
   } catch (error) {
-    console.error('\n❌ Failed to unlink package:', error.message);
+    console.error('\n✖ Failed to unlink package:', error.message);
     process.exit(1);
   }
 }

package/templates/README.md

@@ -8,7 +8,7 @@ The templates directory is organized as follows:
 
 ### Application Templates (for `--template` flag)
 
-Application templates are folder-based and located under `templates/applications/`. When you use `--template <name>`, the tool looks for `templates/applications/<name>/` and copies all files from that folder to `builder/<app>/`.
+Application templates are folder-based and located under `templates/applications/`. When you use `--template <name>`, the tool looks for `templates/applications/<name>/` and copies all files from that folder to `builder/<appKey>/`.
 
 **Example:**
 - `templates/applications/miso-controller/` - Miso Controller application template
@@ -18,7 +18,7 @@ Application templates are folder-based and located under `templates/applications
 - Template folder must exist in `templates/applications/<name>/`
 - Template folder must contain at least one file
 - Hidden files (starting with `.`) are skipped
-- If a template includes a `Dockerfile`, it will be copied to `builder/<app>/Dockerfile` along with other files
+- If a template includes a `Dockerfile`, it will be copied to `builder/<appKey>/Dockerfile` along with other files
 
 ### Language Templates
 
@@ -63,6 +63,19 @@ Extra workflow steps are located in `templates/github/steps/`. When you use `--g
 ### Health Check Configuration
 - `{{healthCheck.path}}` - Health check endpoint path (e.g., "/health")
 - `{{healthCheck.interval}}` - Health check interval in seconds
+- `{{healthCheck.bashProbe}}` - When true, generated Docker Compose uses a bash TCP probe (no `curl` dependency) instead of `curl -f`.
+
+**Why `bashProbe` exists**
+
+Some application images intentionally do not ship with `curl` (for smaller images or stricter runtime environments). If Compose uses a `curl`-based healthcheck in those images, Docker will mark the container as **unhealthy** even when the app is actually serving traffic.
+
+Set `healthCheck.bashProbe: true` to make Compose healthchecks work without `curl` by performing a minimal HTTP request over `/dev/tcp`.
+
+### Traefik (Docker Compose labels)
+
+Generated compose includes `traefik.http.routers.<app>.service=<app>` so Traefik’s Docker provider always binds the router to the in-compose service (required for HTTP-only routers when TLS terminates at nginx).
+
+Infra Traefik is started with `--providers.docker.allowEmptyServices=true` so routes are published while a container is still in Docker’s `starting` / `unhealthy` health state (common during slow boots or when a health probe differs from real readiness).
 
 ### Service Requirements
 - `{{requiresDatabase}}` - Database requirement flag (conditional db-init service)