windmill-cli 1.532.0 → 1.532.1

package/esm/src/commands/sync/sync.js

@@ -8,7 +8,9 @@ import { downloadZip } from "./pull.js";
 import { exts, findContentFile, findGlobalDeps, findResourceFile, handleScriptMetadata, removeExtensionToPath, } from "../script/script.js";
 import { handleFile } from "../script/script.js";
 import { deepEqual, isFileResource } from "../../utils/utils.js";
-import { readConfigFile, getEffectiveSettings, validateBranchConfiguration, } from "../../core/conf.js";
+import { getEffectiveSettings, validateBranchConfiguration, mergeConfigWithConfigFile, } from "../../core/conf.js";
+import { getSpecificItemsForCurrentBranch, isSpecificItem, getBranchSpecificPath, fromBranchSpecificPath, isCurrentBranchFile, isBranchSpecificFile, } from "../../core/specific_items.js";
+import { getCurrentGitBranch } from "../../utils/git.js";
 import { removePathPrefix } from "../../types.js";
 import { listSyncCodebases } from "../../utils/codebase.js";
 import { generateFlowLockInternal, generateScriptMetadataInternal, readLockfile, } from "../../utils/metadata.js";
@@ -21,8 +23,7 @@ function mergeCliWithEffectiveOptions(cliOpts, effectiveOpts) {
     return Object.assign({}, effectiveOpts, cliOpts);
 }
 // Resolve effective sync options using branch-based configuration
-async function resolveEffectiveSyncOptions(workspace, promotion) {
-    const localConfig = await readConfigFile();
+async function resolveEffectiveSyncOptions(workspace, localConfig, promotion) {
     return await getEffectiveSettings(localConfig, promotion);
 }
 export function findCodebase(path, codebases) {
@@ -505,8 +506,30 @@ export async function* readDirRecursiveWithIgnore(ignore, root) {
         }
     }
 }
-export async function elementsToMap(els, ignore, json, skips) {
+export async function elementsToMap(els, ignore, json, skips, specificItems) {
     const map = {};
+    const processedBasePaths = new Set();
+    // First pass: collect all file paths to identify branch-specific files
+    const allPaths = [];
+    for await (const entry of readDirRecursiveWithIgnore(ignore, els)) {
+        if (!entry.isDirectory && !entry.ignored) {
+            allPaths.push(entry.path);
+        }
+    }
+    const branchSpecificExists = new Set();
+    if (specificItems) {
+        const currentBranch = getCurrentGitBranch();
+        if (currentBranch) {
+            for (const path of allPaths) {
+                if (isCurrentBranchFile(path)) {
+                    const basePath = fromBranchSpecificPath(path, currentBranch);
+                    if (isSpecificItem(basePath, specificItems)) {
+                        branchSpecificExists.add(basePath);
+                    }
+                }
+            }
+        }
+    }
     for await (const entry of readDirRecursiveWithIgnore(ignore, els)) {
         if (entry.isDirectory || entry.ignored)
             continue;
@@ -578,10 +601,18 @@ export async function elementsToMap(els, ignore, json, skips) {
             "nu",
             "java",
             "rb",
-            // for related places search: ADD_NEW_LANG 
+            // for related places search: ADD_NEW_LANG
         ].includes(path.split(".").pop() ?? "") &&
             !isFileResource(path))
             continue;
+        // Handle branch-specific files - skip files for other branches
+        if (specificItems && isBranchSpecificFile(path)) {
+            const currentBranch = getCurrentGitBranch();
+            if (!currentBranch || !isCurrentBranchFile(path)) {
+                // Skip branch-specific files for other branches
+                continue;
+            }
+        }
         const content = await entry.getContentText();
         if (skips.skipSecrets && path.endsWith(".variable" + ext)) {
             try {
@@ -612,17 +643,45 @@ export async function elementsToMap(els, ignore, json, skips) {
                 log.warn(`Error reading variable ${path} to check for secrets`);
             }
         }
-        map[entry.path] = content;
+        // Handle branch-specific path mapping after all filtering
+        if (specificItems) {
+            const currentBranch = getCurrentGitBranch();
+            if (currentBranch && isCurrentBranchFile(path)) {
+                // This is a branch-specific file for current branch
+                const basePath = fromBranchSpecificPath(path, currentBranch);
+                if (isSpecificItem(basePath, specificItems)) {
+                    // Map to base path for push operations
+                    map[basePath] = content;
+                    processedBasePaths.add(basePath);
+                }
+                else {
+                    // Branch-specific file doesn't match pattern, skip it
+                    continue;
+                }
+            }
+            else if (!isBranchSpecificFile(path)) {
+                // This is a regular base file, check if we should skip it
+                if (processedBasePaths.has(path)) {
+                    // Skip base file, we already processed branch-specific version
+                    continue;
+                }
+                map[path] = content;
+            }
+        }
+        else {
+            // No specific items configuration, use regular path
+            map[entry.path] = content;
+        }
     }
     return map;
 }
-async function compareDynFSElement(els1, els2, ignore, json, skips, ignoreMetadataDeletion, codebases, ignoreCodebaseChanges) {
+async function compareDynFSElement(els1, els2, ignore, json, skips, ignoreMetadataDeletion, codebases, ignoreCodebaseChanges, specificItems) {
     const [m1, m2] = els2
         ? await Promise.all([
-            elementsToMap(els1, ignore, json, skips),
-            elementsToMap(els2, ignore, json, skips),
+            elementsToMap(els1, ignore, json, skips, specificItems),
+            elementsToMap(els2, ignore, json, skips, specificItems),
         ])
-        : [await elementsToMap(els1, ignore, json, skips), {}];
+        : [await elementsToMap(els1, ignore, json, skips, specificItems), {}];
     const changes = [];
     function parseYaml(k, v) {
         if (k.endsWith(".script.yaml")) {
@@ -985,6 +1044,8 @@ async function buildTracker(changes) {
     return tracker;
 }
 export async function pull(opts) {
+    const originalCliOpts = { ...opts };
+    opts = await mergeConfigWithConfigFile(opts);
     // Validate branch configuration early
     try {
         await validateBranchConfiguration(false, opts.yes);
@@ -1002,9 +1063,11 @@ export async function pull(opts) {
     const workspace = await resolveWorkspace(opts);
     await requireLogin(opts);
     // Resolve effective sync options with branch awareness
-    const effectiveOpts = await resolveEffectiveSyncOptions(workspace, opts.promotion);
+    const effectiveOpts = await resolveEffectiveSyncOptions(workspace, opts, opts.promotion);
+    // Extract specific items configuration before merging overwrites gitBranches
+    const specificItems = getSpecificItemsForCurrentBranch(opts);
     // Merge CLI flags with resolved settings (CLI flags take precedence only for explicit overrides)
-    opts = mergeCliWithEffectiveOptions(opts, effectiveOpts);
+    opts = mergeCliWithEffectiveOptions(originalCliOpts, effectiveOpts);
     const codebases = await listSyncCodebases(opts);
     log.info(colors.gray("Computing the files to update locally to match remote (taking wmill.yaml into account)"));
     let resourceTypeToFormatExtension = {};
@@ -1020,7 +1083,7 @@ export async function pull(opts) {
     const local = !opts.stateful
         ? await FSFSElement(dntShim.Deno.cwd(), codebases, true)
         : await FSFSElement(path.join(dntShim.Deno.cwd(), ".wmill"), [], true);
-    const changes = await compareDynFSElement(remote, local, await ignoreF(opts), opts.json ?? false, opts, false, codebases, true);
+    const changes = await compareDynFSElement(remote, local, await ignoreF(opts), opts.json ?? false, opts, false, codebases, true, specificItems);
     log.info(`remote (${workspace.name}) -> local: ${changes.length} changes to apply`);
     // Handle JSON output for dry-run
     if (opts.dryRun && opts.jsonOutput) {
@@ -1032,6 +1095,12 @@ export async function pull(opts) {
                 ...(change.name === "edited" && change.codebase
                     ? { codebase_changed: true }
                     : {}),
+                ...(specificItems && isSpecificItem(change.path, specificItems)
+                    ? {
+                        branch_specific: true,
+                        branch_specific_path: getBranchSpecificPath(change.path, specificItems)
+                    }
+                    : {}),
             })),
             total: changes.length,
         };
@@ -1040,7 +1109,7 @@ export async function pull(opts) {
     }
     if (changes.length > 0) {
         if (!opts.jsonOutput) {
-            prettyChanges(changes);
+            prettyChanges(changes, specificItems);
         }
         if (opts.dryRun) {
             log.info(colors.gray(`Dry run complete.`));
@@ -1056,8 +1125,16 @@ export async function pull(opts) {
         const conflicts = [];
         log.info(colors.gray(`Applying changes to files ...`));
         for await (const change of changes) {
-            const target = path.join(dntShim.Deno.cwd(), change.path);
-            const stateTarget = path.join(dntShim.Deno.cwd(), ".wmill", change.path);
+            // Determine if this file should be written to a branch-specific path
+            let targetPath = change.path;
+            if (specificItems && isSpecificItem(change.path, specificItems)) {
+                const branchSpecificPath = getBranchSpecificPath(change.path, specificItems);
+                if (branchSpecificPath) {
+                    targetPath = branchSpecificPath;
+                }
+            }
+            const target = path.join(dntShim.Deno.cwd(), targetPath);
+            const stateTarget = path.join(dntShim.Deno.cwd(), ".wmill", targetPath);
             if (change.name === "edited") {
                 if (opts.stateful) {
                     try {
@@ -1089,11 +1166,11 @@ export async function pull(opts) {
                     }
                 }
                 if (exts.some((e) => change.path.endsWith(e))) {
-                    log.info(`Editing script content of ${change.path}`);
+                    log.info(`Editing script content of ${targetPath}${targetPath !== change.path ? colors.gray(` (branch-specific override for ${change.path})`) : ""}`);
                 }
                 else if (change.path.endsWith(".yaml") ||
                     change.path.endsWith(".json")) {
-                    log.info(`Editing ${getTypeStrFromPath(change.path)} ${change.path}`);
+                    log.info(`Editing ${getTypeStrFromPath(change.path)} ${targetPath}${targetPath !== change.path ? colors.gray(` (branch-specific override for ${change.path})`) : ""}`);
                 }
                 await dntShim.Deno.writeTextFile(target, change.after);
                 if (opts.stateful) {
@@ -1105,10 +1182,10 @@ export async function pull(opts) {
                 await ensureDir(path.dirname(target));
                 if (opts.stateful) {
                     await ensureDir(path.dirname(stateTarget));
-                    log.info(`Adding ${getTypeStrFromPath(change.path)} ${change.path}`);
+                    log.info(`Adding ${getTypeStrFromPath(change.path)} ${targetPath}${targetPath !== change.path ? colors.gray(` (branch-specific override for ${change.path})`) : ""}`);
                 }
                 await dntShim.Deno.writeTextFile(target, change.content);
-                log.info(`Writing ${getTypeStrFromPath(change.path)} ${change.path}`);
+                log.info(`Writing ${getTypeStrFromPath(change.path)} ${targetPath}${targetPath !== change.path ? colors.gray(` (branch-specific override for ${change.path})`) : ""}`);
                 if (opts.stateful) {
                     await dntShim.Deno.copyFile(target, stateTarget);
                 }
@@ -1166,6 +1243,12 @@ export async function pull(opts) {
                     ...(change.name === "edited" && change.codebase
                         ? { codebase_changed: true }
                         : {}),
+                    ...(specificItems && isSpecificItem(change.path, specificItems)
+                        ? {
+                            branch_specific: true,
+                            branch_specific_path: getBranchSpecificPath(change.path, specificItems)
+                        }
+                        : {}),
                 })),
                 total: changes.length,
             };
@@ -1179,17 +1262,27 @@ export async function pull(opts) {
         console.log(JSON.stringify({ success: true, message: "No changes to apply", total: 0 }, null, 2));
     }
 }
-function prettyChanges(changes) {
+function prettyChanges(changes, specificItems) {
     for (const change of changes) {
+        let displayPath = change.path;
+        let branchNote = "";
+        // Check if this will be written as a branch-specific file
+        if (specificItems && isSpecificItem(change.path, specificItems)) {
+            const branchSpecificPath = getBranchSpecificPath(change.path, specificItems);
+            if (branchSpecificPath) {
+                displayPath = branchSpecificPath;
+                branchNote = " (branch-specific)";
+            }
+        }
         if (change.name === "added") {
-            log.info(colors.green(`+ ${getTypeStrFromPath(change.path)} ` + change.path));
+            log.info(colors.green(`+ ${getTypeStrFromPath(change.path)} ` + displayPath + colors.gray(branchNote)));
         }
         else if (change.name === "deleted") {
-            log.info(colors.red(`- ${getTypeStrFromPath(change.path)} ` + change.path));
+            log.info(colors.red(`- ${getTypeStrFromPath(change.path)} ` + displayPath + colors.gray(branchNote)));
         }
         else if (change.name === "edited") {
             log.info(colors.yellow(`~ ${getTypeStrFromPath(change.path)} ` +
-                change.path +
+                displayPath + colors.gray(branchNote) +
                 (change.codebase ? ` (codebase changed)` : "")));
             if (change.before != change.after) {
                 showDiff(change.before, change.after);
@@ -1222,6 +1315,10 @@ function removeSuffix(str, suffix) {
     return str.slice(0, str.length - suffix.length);
 }
 export async function push(opts) {
+    // Save original CLI options before merging with config file
+    const originalCliOpts = { ...opts };
+    // Load configuration from wmill.yaml and merge with CLI options
+    opts = await mergeConfigWithConfigFile(opts);
     // Validate branch configuration early
     try {
         await validateBranchConfiguration(false, opts.yes);
@@ -1236,9 +1333,11 @@ export async function push(opts) {
     const workspace = await resolveWorkspace(opts);
     await requireLogin(opts);
     // Resolve effective sync options with branch awareness
-    const effectiveOpts = await resolveEffectiveSyncOptions(workspace, opts.promotion);
+    const effectiveOpts = await resolveEffectiveSyncOptions(workspace, opts, opts.promotion);
+    // Extract specific items configuration BEFORE merging overwrites gitBranches
+    const specificItems = getSpecificItemsForCurrentBranch(opts);
     // Merge CLI flags with resolved settings (CLI flags take precedence only for explicit overrides)
-    opts = mergeCliWithEffectiveOptions(opts, effectiveOpts);
+    opts = mergeCliWithEffectiveOptions(originalCliOpts, effectiveOpts);
     const codebases = await listSyncCodebases(opts);
     if (opts.raw) {
         log.info("--raw is now the default, you can remove it as a flag");
@@ -1263,7 +1362,7 @@ export async function push(opts) {
     }
     const remote = ZipFSElement((await downloadZip(workspace, opts.plainSecrets, opts.skipVariables, opts.skipResources, opts.skipResourceTypes, opts.skipSecrets, opts.includeSchedules, opts.includeTriggers, opts.includeUsers, opts.includeGroups, opts.includeSettings, opts.includeKey, opts.defaultTs)), !opts.json, opts.defaultTs ?? "bun", resourceTypeToFormatExtension, false);
     const local = await FSFSElement(path.join(dntShim.Deno.cwd(), ""), codebases, false);
-    const changes = await compareDynFSElement(local, remote, await ignoreF(opts), opts.json ?? false, opts, true, codebases, false);
+    const changes = await compareDynFSElement(local, remote, await ignoreF(opts), opts.json ?? false, opts, true, codebases, false, specificItems);
     const globalDeps = await findGlobalDeps();
     const tracker = await buildTracker(changes);
     const staleScripts = [];
@@ -1308,6 +1407,12 @@ export async function push(opts) {
                 ...(change.name === "edited" && change.codebase
                     ? { codebase_changed: true }
                     : {}),
+                ...(specificItems && isSpecificItem(change.path, specificItems)
+                    ? {
+                        branch_specific: true,
+                        branch_specific_path: getBranchSpecificPath(change.path, specificItems)
+                    }
+                    : {}),
             })),
             total: changes.length,
         };
@@ -1316,7 +1421,7 @@ export async function push(opts) {
     }
     if (changes.length > 0) {
         if (!opts.jsonOutput) {
-            prettyChanges(changes);
+            prettyChanges(changes, specificItems);
         }
         if (opts.dryRun) {
             log.info(colors.gray(`Dry run complete.`));
@@ -1603,6 +1708,12 @@ export async function push(opts) {
                     ...(change.name === "edited" && change.codebase
                         ? { codebase_changed: true }
                         : {}),
+                    ...(specificItems && isSpecificItem(change.path, specificItems)
+                        ? {
+                            branch_specific: true,
+                            branch_specific_path: getBranchSpecificPath(change.path, specificItems)
+                        }
+                        : {}),
                 })),
                 total: changes.length,
                 duration_ms: Math.round(performance.now() - start),

package/esm/src/commands/workspace/workspace.js

@@ -279,27 +279,27 @@ async function bind(opts, bindWorkspace) {
         return;
     }
     // For unbind, check if branch exists
-    if (!bindWorkspace && (!config.git_branches || !config.git_branches[branch])) {
-        log.error(colors.red(`Branch '${branch}' not found in wmill.yaml git_branches`));
+    if (!bindWorkspace && (!config.gitBranches || !config.gitBranches[branch])) {
+        log.error(colors.red(`Branch '${branch}' not found in wmill.yaml gitBranches`));
         return;
     }
     // Update the branch configuration with workspace binding
-    if (!config.git_branches) {
-        config.git_branches = {};
+    if (!config.gitBranches) {
+        config.gitBranches = {};
     }
-    if (!config.git_branches[branch]) {
-        config.git_branches[branch] = { overrides: {} };
+    if (!config.gitBranches[branch]) {
+        config.gitBranches[branch] = { overrides: {} };
     }
     if (bindWorkspace && activeWorkspace) {
-        config.git_branches[branch].baseUrl = activeWorkspace.remote;
-        config.git_branches[branch].workspaceId = activeWorkspace.workspaceId;
+        config.gitBranches[branch].baseUrl = activeWorkspace.remote;
+        config.gitBranches[branch].workspaceId = activeWorkspace.workspaceId;
         log.info(colors.green(`✓ Bound branch '${branch}' to workspace '${activeWorkspace.name}'\n` +
             `  ${activeWorkspace.workspaceId} on ${activeWorkspace.remote}`));
     }
     else {
         // Unbind
-        delete config.git_branches[branch].baseUrl;
-        delete config.git_branches[branch].workspaceId;
+        delete config.gitBranches[branch].baseUrl;
+        delete config.gitBranches[branch].workspaceId;
         log.info(colors.green(`✓ Removed workspace binding from branch '${branch}'`));
     }
     // Write back the updated config

package/esm/src/core/conf.js

@@ -1,13 +1,80 @@
 import * as dntShim from "../../_dnt.shims.js";
 import { log, yamlParseFile, Confirm, yamlStringify } from "../../deps.js";
 import { getCurrentGitBranch, isGitRepository } from "../utils/git.js";
+import { join, dirname, resolve, relative } from "node:path";
+import { existsSync } from "node:fs";
+import { execSync } from "node:child_process";
 export let showDiffs = false;
 export function setShowDiffs(value) {
     showDiffs = value;
 }
+function getGitRepoRoot() {
+    try {
+        const result = execSync("git rev-parse --show-toplevel", {
+            encoding: "utf8",
+            stdio: "pipe"
+        });
+        return result.trim();
+    }
+    catch (error) {
+        return null;
+    }
+}
+function findWmillYaml() {
+    const startDir = resolve(dntShim.Deno.cwd());
+    const isInGitRepo = isGitRepository();
+    // If not in git repo, only check current directory
+    if (!isInGitRepo) {
+        const wmillYamlPath = join(startDir, "wmill.yaml");
+        return existsSync(wmillYamlPath) ? wmillYamlPath : null;
+    }
+    // If in git repo, search up to git repository root
+    const gitRoot = getGitRepoRoot();
+    let currentDir = startDir;
+    let foundPath = null;
+    while (true) {
+        const wmillYamlPath = join(currentDir, "wmill.yaml");
+        if (existsSync(wmillYamlPath)) {
+            foundPath = wmillYamlPath;
+            break;
+        }
+        // Check if we've reached the git repository root
+        if (gitRoot && resolve(currentDir) === resolve(gitRoot)) {
+            break;
+        }
+        // Check if we've reached the filesystem root
+        const parentDir = dirname(currentDir);
+        if (parentDir === currentDir) {
+            break;
+        }
+        currentDir = parentDir;
+    }
+    // If wmill.yaml was found in a parent directory, warn the user and change working directory
+    if (foundPath && resolve(dirname(foundPath)) !== resolve(startDir)) {
+        const configDir = dirname(foundPath);
+        const relativePath = relative(startDir, foundPath);
+        log.warn(`⚠️  wmill.yaml found in parent directory: ${relativePath}`);
+        // Change working directory to where wmill.yaml was found
+        dntShim.Deno.chdir(configDir);
+        log.info(`📁 Changed working directory to: ${configDir}`);
+    }
+    return foundPath;
+}
+export function getWmillYamlPath() {
+    return findWmillYaml();
+}
 export async function readConfigFile() {
     try {
-        const conf = (await yamlParseFile("wmill.yaml"));
+        // First, try to find wmill.yaml recursively
+        const wmillYamlPath = findWmillYaml();
+        if (!wmillYamlPath) {
+            log.warn("No wmill.yaml found. Use 'wmill init' to bootstrap it. Using 'bun' as default typescript runtime.");
+            return {};
+        }
+        const conf = (await yamlParseFile(wmillYamlPath));
+        // Handle legacy format migrations (combine overrides and git_branches)
+        let needsConfigWrite = false;
+        const migrationMessages = [];
         // Handle obsolete overrides format
         if (conf && 'overrides' in conf) {
             const overrides = conf.overrides;
@@ -18,17 +85,55 @@ export async function readConfigFile() {
                     "   Please delete your wmill.yaml and run 'wmill init' to recreate it with the new format.");
             }
             else {
-                // Remove empty overrides with a note
-                log.info("ℹ️  Removing empty 'overrides: {}' from wmill.yaml (migrated to git_branches format)");
+                // Remove empty overrides
                 delete conf.overrides;
-                // Write the updated config back to file
-                try {
-                    await dntShim.Deno.writeTextFile("wmill.yaml", yamlStringify(conf));
+                needsConfigWrite = true;
+                migrationMessages.push("ℹ️  Removing empty 'overrides: {}' from wmill.yaml (migrated to gitBranches format)");
+            }
+        }
+        // Handle git_branches to gitBranches migration
+        if (conf && 'git_branches' in conf) {
+            if (!conf.gitBranches) {
+                // Deep copy git_branches to gitBranches (even if empty)
+                conf.gitBranches = JSON.parse(JSON.stringify(conf.git_branches));
+                needsConfigWrite = true;
+                migrationMessages.push("⚠️  Migrating 'git_branches' to 'gitBranches' (camelCase). The snake_case format is deprecated.");
+                migrationMessages.push("✅ Successfully migrated 'git_branches' to 'gitBranches' in wmill.yaml");
+            }
+            else {
+                migrationMessages.push("⚠️  Both 'git_branches' and 'gitBranches' found in wmill.yaml. Using 'gitBranches' and ignoring 'git_branches'.");
+            }
+            // Always remove the old field from config object (both file and memory)
+            delete conf.git_branches;
+        }
+        // Perform single atomic write if any migrations are needed
+        if (needsConfigWrite) {
+            try {
+                await dntShim.Deno.writeTextFile(wmillYamlPath, yamlStringify(conf));
+                // Log all migration messages after successful write
+                migrationMessages.forEach(msg => {
+                    if (msg.startsWith('⚠️')) {
+                        log.warn(msg);
+                    }
+                    else {
+                        log.info(msg);
+                    }
+                });
+            }
+            catch (error) {
+                log.warn(`Could not update wmill.yaml to apply migrations: ${error instanceof Error ? error.message : error}`);
+            }
+        }
+        else if (migrationMessages.length > 0) {
+            // Log messages for non-write cases (like "both found")
+            migrationMessages.forEach(msg => {
+                if (msg.startsWith('⚠️')) {
+                    log.warn(msg);
                 }
-                catch (error) {
-                    log.warn(`Could not update wmill.yaml to remove empty overrides: ${error instanceof Error ? error.message : error}`);
+                else {
+                    log.info(msg);
                 }
-            }
+            });
         }
         if (conf?.defaultTs == undefined) {
             log.warn("No defaultTs defined in your wmill.yaml. Using 'bun' as default.");
@@ -39,8 +144,19 @@ export async function readConfigFile() {
         if (e instanceof Error && (e.message.includes("overrides") || e.message.includes("Obsolete configuration format"))) {
             throw e; // Re-throw the specific obsolete format error
         }
-        log.warn("No wmill.yaml found. Use 'wmill init' to bootstrap it. Using 'bun' as default typescript runtime.");
-        return {};
+        // Since we already found the file path, this is likely a parsing or access error
+        if (e instanceof Error && e.message.includes("Error parsing yaml")) {
+            const yamlError = e.cause instanceof Error ? e.cause.message : String(e.cause);
+            throw new Error("❌ YAML syntax error in wmill.yaml:\n" +
+                "   " + yamlError + "\n" +
+                "   Please fix the YAML syntax in wmill.yaml or delete the file to start fresh.");
+        }
+        else {
+            // File exists but has other issues (permissions, etc.)
+            throw new Error("❌ Failed to read wmill.yaml:\n" +
+                "   " + (e instanceof Error ? e.message : String(e)) + "\n" +
+                "   Please check file permissions or fix the syntax.");
+        }
     }
 }
 // Default sync options - shared across the codebase to prevent duplication
@@ -74,33 +190,40 @@ export async function validateBranchConfiguration(skipValidation, autoAccept) {
         return;
     }
     const config = await readConfigFile();
-    const { git_branches } = config;
+    const { gitBranches } = config;
     const currentBranch = getCurrentGitBranch();
-    // In a git repository, git_branches section is recommended
-    if (!git_branches || Object.keys(git_branches).length === 0) {
-        log.warn("⚠️  WARNING: In a Git repository, the 'git_branches' section is recommended in wmill.yaml.\n" +
-            "   Consider adding a git_branches section with configuration for your Git branches.\n" +
+    // In a git repository, gitBranches section is recommended
+    if (!gitBranches || Object.keys(gitBranches).length === 0) {
+        log.warn("⚠️  WARNING: In a Git repository, the 'gitBranches' section is recommended in wmill.yaml.\n" +
+            "   Consider adding a gitBranches section with configuration for your Git branches.\n" +
             "   Run 'wmill init' to recreate the configuration file with proper branch setup.");
         return;
     }
-    // Current branch must be defined in git_branches config
-    if (currentBranch && !git_branches[currentBranch]) {
+    // Current branch must be defined in gitBranches config
+    if (currentBranch && !gitBranches[currentBranch]) {
         // In interactive mode, offer to create the branch
         if (dntShim.Deno.stdin.isTerminal()) {
-            const availableBranches = Object.keys(git_branches).join(', ');
-            log.info(`Current Git branch '${currentBranch}' is not defined in the git_branches configuration.\n` +
+            const availableBranches = Object.keys(gitBranches).join(', ');
+            log.info(`Current Git branch '${currentBranch}' is not defined in the gitBranches configuration.\n` +
                 `Available branches: ${availableBranches}`);
             const shouldCreate = autoAccept || await Confirm.prompt({
                 message: `Create empty branch configuration for '${currentBranch}'?`,
                 default: true,
             });
             if (shouldCreate) {
+                // Warn if branch name contains filesystem-unsafe characters
+                if (/[\/\\:*?"<>|.]/.test(currentBranch)) {
+                    const sanitizedBranchName = currentBranch.replace(/[\/\\:*?"<>|.]/g, '_');
+                    log.warn(`⚠️  WARNING: Branch name "${currentBranch}" contains filesystem-unsafe characters (/ \\ : * ? " < > | .).`);
+                    log.warn(`   Branch-specific files will be saved with sanitized name: "${sanitizedBranchName}"`);
+                    log.warn(`   Example: "file.variable.yaml" → "file.${sanitizedBranchName}.variable.yaml"`);
+                }
                 // Read current config, add branch, and write it back
                 const currentConfig = await readConfigFile();
-                if (!currentConfig.git_branches) {
-                    currentConfig.git_branches = {};
+                if (!currentConfig.gitBranches) {
+                    currentConfig.gitBranches = {};
                 }
-                currentConfig.git_branches[currentBranch] = { overrides: {} };
+                currentConfig.gitBranches[currentBranch] = { overrides: {} };
                 await dntShim.Deno.writeTextFile("wmill.yaml", yamlStringify(currentConfig));
                 log.info(`✅ Created empty branch configuration for '${currentBranch}'`);
             }
@@ -110,9 +233,15 @@ export async function validateBranchConfiguration(skipValidation, autoAccept) {
             }
         }
         else {
-            log.warn(`⚠️  WARNING: Current Git branch '${currentBranch}' is not defined in the git_branches configuration.\n` +
-                `   Consider adding configuration for branch '${currentBranch}' in the git_branches section of wmill.yaml.\n` +
-                `   Available branches: ${Object.keys(git_branches).join(', ')}`);
+            // Warn about filesystem-unsafe characters in branch name
+            if (/[\/\\:*?"<>|.]/.test(currentBranch)) {
+                const sanitizedBranchName = currentBranch.replace(/[\/\\:*?"<>|.]/g, '_');
+                log.warn(`⚠️  WARNING: Branch name "${currentBranch}" contains filesystem-unsafe characters (/ \\ : * ? " < > | .).`);
+                log.warn(`   Branch-specific files will use sanitized name: "${sanitizedBranchName}"`);
+            }
+            log.warn(`⚠️  WARNING: Current Git branch '${currentBranch}' is not defined in the gitBranches configuration.\n` +
+                `   Consider adding configuration for branch '${currentBranch}' in the gitBranches section of wmill.yaml.\n` +
+                `   Available branches: ${Object.keys(gitBranches).join(', ')}`);
             return;
         }
     }
@@ -120,13 +249,13 @@ export async function validateBranchConfiguration(skipValidation, autoAccept) {
 // Get effective settings by merging top-level settings with branch-specific overrides
 export async function getEffectiveSettings(config, promotion, skipBranchValidation, suppressLogs) {
     // Start with top-level settings from config
-    const { git_branches, ...topLevelSettings } = config;
+    const { gitBranches, ...topLevelSettings } = config;
     let effective = { ...topLevelSettings };
     if (isGitRepository()) {
         const currentBranch = getCurrentGitBranch();
         // If promotion is specified, use that branch's promotionOverrides or overrides
-        if (promotion && git_branches && git_branches[promotion]) {
-            const targetBranch = git_branches[promotion];
+        if (promotion && gitBranches && gitBranches[promotion]) {
+            const targetBranch = gitBranches[promotion];
             // First try promotionOverrides, then fall back to overrides
             if (targetBranch.promotionOverrides) {
                 Object.assign(effective, targetBranch.promotionOverrides);
@@ -145,8 +274,8 @@ export async function getEffectiveSettings(config, promotion, skipBranchValidati
             }
         }
         // Otherwise use current branch overrides (existing behavior)
-        else if (currentBranch && git_branches && git_branches[currentBranch] && git_branches[currentBranch].overrides) {
-            Object.assign(effective, git_branches[currentBranch].overrides);
+        else if (currentBranch && gitBranches && gitBranches[currentBranch] && gitBranches[currentBranch].overrides) {
+            Object.assign(effective, gitBranches[currentBranch].overrides);
             if (!suppressLogs) {
                 log.info(`Applied settings for Git branch: ${currentBranch}`);
             }

package/esm/src/core/context.js

@@ -79,7 +79,7 @@ async function tryResolveBranchWorkspace(opts) {
     }
     // Read wmill.yaml to check for branch workspace configuration
     const config = await readConfigFile();
-    const branchConfig = config.git_branches?.[currentBranch];
+    const branchConfig = config.gitBranches?.[currentBranch];
     // Check if branch has workspace configuration
     if (!branchConfig?.baseUrl || !branchConfig?.workspaceId) {
         return undefined;