@vrdmr/fnx-test 0.3.0 → 0.4.1

package/lib/azurite-manager.js

@@ -11,6 +11,7 @@ const TABLE_PORT = 10002;
 const AZURITE_INSTALL_DIR = join(homedir(), '.fnx', 'tools', 'azurite');
 
 let azuriteProcess = null;
+let weStartedAzurite = false;
 
 /**
  * Determine whether Azurite is needed based on AzureWebJobsStorage value.
@@ -160,6 +161,7 @@ export async function ensureAzurite(mergedValues, opts = {}) {
   azuriteProcess = spawn(azuriteBin, azuriteArgs, {
     stdio: 'ignore',
   });
+  weStartedAzurite = true;
 
   azuriteProcess.on('error', (err) => {
     console.error(errorColor(`[fnx] Azurite failed to start: ${err.message}`));
@@ -188,11 +190,12 @@ export async function ensureAzurite(mergedValues, opts = {}) {
 }
 
 /**
- * Stop the managed Azurite process.
+ * Stop the managed Azurite process (only if fnx started it).
  */
 export function stopAzurite() {
-  if (azuriteProcess) {
+  if (azuriteProcess && weStartedAzurite) {
     try { azuriteProcess.kill(); } catch { /* already dead */ }
     azuriteProcess = null;
+    weStartedAzurite = false;
   }
 }

package/lib/cli.js

@@ -10,7 +10,9 @@ import { launchHost, createHostState } from './host-launcher.js';
 import { startLiveMcpServer } from './live-mcp-server.js';
 import { detectDotnetModel, printInProcessError } from './dotnet-detector.js';
 import { detectRuntimeFromConfig, packFunctionApp } from './pack.js';
+import { loadConfig, migrateConfig, validateConfig, showResolvedConfig } from './config.js';
 import { title, info, funcName, url as urlColor, success, error as errorColor, warning, dim, bold, highlightUrls } from './colors.js';
+import { renderAsciiFooter } from './help-art.js';
 
 const FNX_HOME = join(homedir(), '.fnx');
 const VERSION_CHECK_FILE = join(FNX_HOME, 'version-check.json');
@@ -42,12 +44,16 @@ function hasHelp(args) {
  * 2. Otherwise check cwd for host.json.
  * 3. Fall back to cwd/src if it contains host.json.
  * 4. Error with actionable message if nothing found.
+ *
+ * opts.requireHostJson (default: true) — set to false for commands that
+ * work on config files only (e.g. fnx config migrate).
  */
-function resolveAppPath(args) {
+function resolveAppPath(args, opts = {}) {
+  const requireHostJson = opts.requireHostJson !== false;
   const explicit = getFlag(args, '--app-path');
   if (explicit) {
     const resolved = resolvePath(explicit);
-    if (!existsSync(join(resolved, 'host.json'))) {
+    if (requireHostJson && !existsSync(join(resolved, 'host.json'))) {
       console.error(errorColor(`Error: No host.json found in ${resolved}`));
       console.error(`  The --app-path must point to a directory containing host.json.`);
       console.error(dim(`  Example: fnx start --app-path ./my-function-app`));
@@ -67,6 +73,11 @@ function resolveAppPath(args) {
     return srcDir;
   }
 
+  // For config-only commands, fall back to cwd even without host.json
+  if (!requireHostJson) {
+    return cwd;
+  }
+
   console.error(errorColor(`Error: No function app found.`));
   console.error(`  Could not find host.json in the current directory or ./src.`);
   console.error(dim(`  Use --app-path <dir> to specify the function app location.`));
@@ -77,7 +88,8 @@ export async function main(args) {
   const cmd = args[0];
 
   if (cmd === '-h' || cmd === '--help' || cmd === 'help' || !cmd) {
-    await printHelpWithVersionInfo();
+    const showAscii = args.includes('--ascii');
+    await printHelpWithVersionInfo(showAscii);
     process.exit(cmd ? 0 : 1);
   }
 
@@ -100,6 +112,33 @@ export async function main(args) {
     return;
   }
 
+  if (cmd === 'doctor') {
+    if (hasHelp(args.slice(1))) { printDoctorHelp(); return; }
+    const { runDoctor } = await import('./doctor.js');
+    const appPath = resolveAppPath(args, { requireHostJson: false });
+    const exitCode = await runDoctor(appPath);
+    process.exit(exitCode);
+  }
+
+  if (cmd === 'config') {
+    if (hasHelp(args.slice(1))) { printConfigHelp(); return; }
+    const subCmd = args[1];
+    const appPath = resolveAppPath(args, { requireHostJson: false });
+    if (subCmd === 'migrate') {
+      await migrateConfig(appPath);
+    } else if (subCmd === 'validate') {
+      const result = await validateConfig(appPath);
+      if (result.warnings.length) result.warnings.forEach(w => console.log(warning(`  ⚠ ${w}`)));
+      if (result.secrets.length) result.secrets.forEach(s => console.log(errorColor(`  ✗ ${s.path}: ${s.reason}`)));
+      if (result.errors.length) result.errors.forEach(e => console.log(errorColor(`  ✗ ${e}`)));
+      if (result.valid) console.log(success('  ✓ app-config.yaml is valid.'));
+      else process.exit(1);
+    } else {
+      await showResolvedConfig(appPath);
+    }
+    return;
+  }
+
   if (cmd === 'sync') {
     if (hasHelp(args.slice(1))) { printSyncHelp(); return; }
     await runSync(args.slice(1));
@@ -124,6 +163,12 @@ export async function main(args) {
 
   if (hasHelp(args.slice(1))) { printStartHelp(); return; }
 
+  // Handle --sku list early (no config needed)
+  if (getFlag(args, '--sku') === 'list') {
+    await listProfiles();
+    return;
+  }
+
   await maybeWarnForCliUpgrade();
 
   const scriptRoot = resolveAppPath(args);
@@ -143,21 +188,22 @@ export async function main(args) {
     setProfilesSource(profilesSource);
   }
 
-  // Read config files early (needed for SKU resolution and env vars)
-  const appConfig = await readJsonFile(resolvePath(scriptRoot, 'app.config.json'));
-  const localSettings = await readJsonFile(resolvePath(scriptRoot, 'local.settings.json'));
+  // Load and validate app configuration (app-config.yaml + local.settings.json)
+  const appCfg = await loadConfig(scriptRoot);
+  const { mergedValues, workerRuntime } = appCfg;
 
-  // Resolve SKU: CLI flag > app.config.json > local.settings.json > default "flex"
+  if (!workerRuntime) {
+    console.error(errorColor('Error: runtime.name not set in app-config.yaml and FUNCTIONS_WORKER_RUNTIME not in local.settings.json'));
+    process.exit(1);
+  }
+
+  // Resolve SKU: CLI flag > app-config.yaml > default "flex"
   let sku = getFlag(args, '--sku');
   let skuSource = 'CLI flag';
 
-  if (!sku && appConfig?.TargetSku) {
-    sku = appConfig.TargetSku;
-    skuSource = 'app.config.json';
-  }
-  if (!sku && localSettings?.TargetSku) {
-    sku = localSettings.TargetSku;
-    skuSource = 'local.settings.json';
+  if (!sku && appCfg.sku) {
+    sku = appCfg.sku;
+    skuSource = appCfg.skuSource;
   }
   if (!sku) {
     sku = 'flex';
@@ -166,11 +212,6 @@ export async function main(args) {
     console.log(dim(`Tip: Use --sku <name> to target a specific SKU. Run --sku list to see options.\n`));
   }
 
-  if (sku === 'list') {
-    await listProfiles();
-    return;
-  }
-
   // 1. Resolve profile
   if (skuSource !== 'default') {
     console.log(title(`Resolving SKU profile: ${sku} (from ${skuSource})...`));
@@ -195,19 +236,6 @@ export async function main(args) {
   console.log(`  ${dim('Profile Source:')}    ${info(source)}`);
   console.log();
 
-  // Early validation: merge config and check runtime before downloading anything
-  const mergedValues = {
-    ...(appConfig?.Values || {}),
-    ...(localSettings?.Values || {}),
-  };
-
-  const workerRuntime = mergedValues.FUNCTIONS_WORKER_RUNTIME;
-
-  if (!workerRuntime) {
-    console.error(errorColor('Error: FUNCTIONS_WORKER_RUNTIME not set in app.config.json or local.settings.json'));
-    process.exit(1);
-  }
-
   // F9: .NET isolated worker only — block in-process projects with guidance
   const dotnetRuntimes = ['dotnet', 'dotnet-isolated'];
   if (dotnetRuntimes.includes(workerRuntime)) {
@@ -392,7 +420,7 @@ export async function readJsonFile(filePath) {
   }
 }
 
-async function printHelpWithVersionInfo() {
+async function printHelpWithVersionInfo(showAscii = false) {
   const pkg = await getFnxPackage();
   const cachedHosts = getCachedHostVersions().sort(compareVersions);
   const cachedBundles = getCachedBundleVersions().sort(compareVersions);
@@ -431,6 +459,10 @@ ${dim('fnx Version:')}        ${title(pkg.version)}`);
 
   console.log();
   printHelp();
+
+  if (showAscii) {
+    console.log('\n' + renderAsciiFooter());
+  }
 }
 
 function printHelp() {
@@ -438,8 +470,10 @@ function printHelp() {
 
 ${title('Commands:')}
   ${funcName('start')}            Launch the Azure Functions host runtime for a specific SKU.
+  ${funcName('doctor')}           Validate project setup and diagnose common issues.
   ${funcName('sync')}             Sync cached host/extensions with current catalog profile.
   ${funcName('pack')}             Package a Functions app into a deployment zip.
+  ${funcName('config')}           Show, validate, or migrate app configuration.
   ${funcName('warmup')}           Pre-download host binaries and extension bundles.
   ${funcName('templates-mcp')}    Start the Azure Functions templates MCP server (stdio).
 
@@ -451,6 +485,7 @@ ${title('Common Options:')}
   ${success('--verbose')}        Show all host output (unfiltered).
   ${success('-v')}, ${success('--version')}    Display the version of fnx.
   ${success('-h')}, ${success('--help')}       Display this help information.
+  ${success('--ascii')}          Show ASCII art + QR code (use with -h).
 
 ${title('Start Options:')}      ${dim('(fnx start)')}
   ${success('--app-path')} <dir>  Path to the function app directory (default: cwd).
@@ -480,6 +515,7 @@ ${title('Examples:')}
   fnx start                              Start with default SKU (flex)
   fnx start --sku windows-consumption    Emulate Windows Consumption
   fnx start --sku flex --port 8080       Custom port
+  fnx doctor                             Validate project setup
   fnx pack --app-path ./my-app         Package function app as zip
   fnx sync host --force                  Force re-download host binary
   fnx warmup --all                       Pre-download all SKUs
@@ -604,3 +640,61 @@ ${title('VS Code Configuration:')}
     }
   }`.trim());
 }
+
+function printConfigHelp() {
+  console.log(`
+${bold(title('fnx config'))} — Show, validate, or migrate app configuration.
+
+${title('Usage:')} fnx config [subcommand] [options]
+
+${title('Subcommands:')}
+  ${funcName('(none)')}           Show resolved config with provenance (which file each value comes from).
+  ${funcName('migrate')}          Create app-config.yaml from local.settings.json (extract non-secrets).
+  ${funcName('validate')}         Validate app-config.yaml (schema, secrets, allowlist) without starting.
+
+${title('Options:')}
+  ${success('--app-path')} <dir>  Path to the function app directory (default: cwd).
+  ${success('-h')}, ${success('--help')}         Show this help message.
+
+${title('Configuration Files:')}
+  ${funcName('app-config.yaml')}       Non-secret behavioral config (committed to source control).
+                          Contains runtime, SKU target, scale settings, and app settings.
+  ${funcName('local.settings.json')}   Secrets and connection strings (git-ignored).
+                          Values here override app-config.yaml values.
+
+${title('Precedence:')} CLI flags > local.settings.json > app-config.yaml > defaults
+
+${title('Examples:')}
+  fnx config                               Show resolved config
+  fnx config migrate                       Create app-config.yaml from local.settings.json
+  fnx config validate                      Check app-config.yaml for errors
+  fnx config validate --app-path ./my-app  Validate a specific app`.trim());
+}
+
+function printDoctorHelp() {
+  console.log(`
+${bold(title('fnx doctor'))} — Validate project setup and diagnose common issues.
+
+${title('Usage:')} fnx doctor [options]
+
+${title('Checks:')}
+  • host.json             Present and valid (version 2.0)
+  • app-config.yaml       Schema valid, no secrets, runtime configured
+  • local.settings.json   Present and valid JSON
+  • Worker runtime        Detected from config files
+  • Host cache            Cached host binaries in ~/.fnx/hosts/
+  • Default ports         7071 (HTTP) and 7072 (MCP) availability
+  • Azurite               Storage emulator status
+
+${title('Options:')}
+  ${success('--app-path')} <dir>  Path to the function app directory (default: cwd).
+  ${success('-h')}, ${success('--help')}         Show this help message.
+
+${title('Exit Codes:')}
+  ${success('0')}   All checks passed (or warnings only)
+  ${errorColor('1')}   One or more checks failed
+
+${title('Examples:')}
+  fnx doctor                             Check current directory
+  fnx doctor --app-path ./my-app         Check a specific app`.trim());
+}

package/lib/config-schema.js

@@ -0,0 +1,167 @@
+// config-schema.js — Canonical mapping: app-config.yaml paths → host environment variables
+//
+// This is the single source of truth for the config format. fnx is the first consumer,
+// but workers, deployment tools, and other components can adopt the same schema.
+
+// ── Structured field mappings (YAML path → env var) ──
+
+export const STRUCTURED_FIELDS = {
+  'runtime.name': {
+    envVar: 'FUNCTIONS_WORKER_RUNTIME',
+    required: true,
+    allowed: ['python', 'node', 'dotnet-isolated', 'dotnet', 'java', 'powershell', 'custom'],
+    description: 'Language runtime for the function app',
+  },
+  'runtime.version': {
+    envVar: 'FUNCTIONS_WORKER_RUNTIME_VERSION',
+    required: false,
+    description: 'Language runtime version (e.g. "3.11" for Python)',
+  },
+  'scaleAndConcurrency.maximumInstanceCount': {
+    envVar: 'WEBSITE_MAX_DYNAMIC_APPLICATION_SCALE_OUT',
+    required: false,
+    type: 'number',
+    description: 'Maximum number of instances for scale-out',
+  },
+  'scaleAndConcurrency.instanceMemoryMB': {
+    envVar: 'WEBSITE_INSTANCE_MEMORY_MB',
+    required: false,
+    type: 'number',
+    description: 'Memory allocation per instance in MB',
+  },
+};
+
+// ── Allowlisted configuration keys (non-secret app settings) ──
+// These are the only keys permitted in the `configurations:` section.
+// Reference: https://learn.microsoft.com/en-us/azure/azure-functions/functions-app-settings
+
+export const ALLOWED_CONFIGURATIONS = new Set([
+  // Core runtime
+  'AzureWebJobsFeatureFlags',
+  'AZURE_FUNCTIONS_ENVIRONMENT',
+  'FUNCTIONS_WORKER_PROCESS_COUNT',
+  'FUNCTIONS_WORKER_SHARED_MEMORY_DATA_TRANSFER_ENABLED',
+
+  // Python worker
+  'PYTHON_ISOLATE_WORKER_DEPENDENCIES',
+  'PYTHON_ENABLE_WORKER_EXTENSIONS',
+  'PYTHON_THREADPOOL_THREAD_COUNT',
+  'PYTHON_ENABLE_DEBUG_LOGGING',
+
+  // Node worker
+  'languageWorkers__node__arguments',
+
+  // Java worker
+  'JAVA_OPTS',
+  'FUNCTIONS_WORKER_JAVA_LOAD_APP_LIBS',
+
+  // .NET (isolated)
+  'FUNCTIONS_WORKER_DOTNET_RELEASE_COMPILATION',
+
+  // Host behavior
+  'AzureWebJobsDisableHomepage',
+  'FUNCTIONS_REQUEST_BODY_SIZE_LIMIT',
+  'PythonPath',
+
+  // Extension bundle overrides
+  'AzureFunctionsJobHost__extensionBundle__id',
+  'AzureFunctionsJobHost__extensionBundle__version',
+
+  // Scale controller
+  'WEBSITE_MAX_DYNAMIC_APPLICATION_SCALE_OUT',
+
+  // Misc non-secret behavioral
+  'FUNCTIONS_V2_COMPATIBILITY_MODE',
+  'AzureWebJobsDotNetReleaseCompilation',
+]);
+
+// ── Top-level YAML sections ──
+
+export const VALID_TOP_LEVEL_KEYS = new Set([
+  'local',
+  'runtime',
+  'scaleAndConcurrency',
+  'configurations',
+  // Reserved for future use
+  // 'deployment',
+]);
+
+// ── Local section keys (fnx-specific) ──
+
+export const VALID_LOCAL_KEYS = new Set([
+  'targetSku',
+  'port',
+  'mcpPort',
+]);
+
+// ── Resolve structured YAML config → flat env var map ──
+
+export function resolveEnvVars(config) {
+  const envVars = {};
+  const errors = [];
+
+  // Map structured fields
+  for (const [yamlPath, spec] of Object.entries(STRUCTURED_FIELDS)) {
+    const value = getNestedValue(config, yamlPath);
+    if (value !== undefined && value !== null) {
+      if (spec.allowed && !spec.allowed.includes(value)) {
+        errors.push(`${yamlPath}: "${value}" is not allowed. Valid: ${spec.allowed.join(', ')}`);
+        continue;
+      }
+      if (spec.type === 'number' && typeof value !== 'number') {
+        errors.push(`${yamlPath}: expected number, got ${typeof value}`);
+        continue;
+      }
+      envVars[spec.envVar] = String(value);
+    } else if (spec.required) {
+      errors.push(`${yamlPath} is required (maps to ${spec.envVar})`);
+    }
+  }
+
+  // Pass through configurations.* as env vars
+  if (config.configurations && typeof config.configurations === 'object') {
+    for (const [key, value] of Object.entries(config.configurations)) {
+      if (!ALLOWED_CONFIGURATIONS.has(key)) {
+        errors.push(`configurations.${key}: not in the allowlist. Move to local.settings.json if needed.`);
+        continue;
+      }
+      envVars[key] = String(value);
+    }
+  }
+
+  return { envVars, errors };
+}
+
+// ── Validate top-level structure ──
+
+export function validateStructure(config) {
+  const warnings = [];
+  if (!config || typeof config !== 'object') {
+    return { warnings: ['app-config.yaml is empty or not a valid YAML object'] };
+  }
+  for (const key of Object.keys(config)) {
+    if (!VALID_TOP_LEVEL_KEYS.has(key)) {
+      warnings.push(`Unknown top-level key "${key}". Valid keys: ${[...VALID_TOP_LEVEL_KEYS].join(', ')}`);
+    }
+  }
+  if (config.local && typeof config.local === 'object') {
+    for (const key of Object.keys(config.local)) {
+      if (!VALID_LOCAL_KEYS.has(key)) {
+        warnings.push(`Unknown key "local.${key}". Valid keys: ${[...VALID_LOCAL_KEYS].join(', ')}`);
+      }
+    }
+  }
+  return { warnings };
+}
+
+// ── Helper: get nested value by dot path ──
+
+function getNestedValue(obj, path) {
+  const parts = path.split('.');
+  let current = obj;
+  for (const part of parts) {
+    if (current == null || typeof current !== 'object') return undefined;
+    current = current[part];
+  }
+  return current;
+}