@anvil-works/anvil-cli 0.7.0-canary.11 → 0.7.0-canary.13

package/dist/cli.js

@@ -13718,7 +13718,7 @@ Promise.resolve(executeGitCredentialOperation(process.argv[2] || "get", {
     }
     function getCredentialHelperModulePath(options) {
         const currentModulePath = options?.currentModulePath ?? __filename;
-        if (isAnvilCliPackageFile(currentModulePath)) return currentModulePath;
+        if (isAnvilCliPackageFile(currentModulePath) && "cli.js" !== external_path_default().basename(currentModulePath)) return currentModulePath;
         return (options?.resolvePackageEntry ?? (()=>requireFromHere.resolve("@anvil-works/anvil-cli")))();
     }
     async function getRepositoryGitDir(repoPath, git = esm_default(repoPath)) {
@@ -14689,6 +14689,77 @@ Promise.resolve(executeGitCredentialOperation(process.argv[2] || "get", {
                 throw errors_createGitError.commandFailed("status", e.message);
             }
         }
+        async discardModeOnlyChanges(paths) {
+            const discarded = [];
+            for (const relativePath of paths)try {
+                const headMode = await this.getHeadFileMode(relativePath);
+                if ("100644" !== headMode && "100755" !== headMode) continue;
+                const contentUnchanged = await this.hasSameContentAsHead(relativePath);
+                if (!contentUnchanged) continue;
+                await this.restoreExecutableBit(relativePath, "100755" === headMode);
+                discarded.push(relativePath);
+            } catch (e) {
+                throw errors_createGitError.commandFailed("discard mode-only changes", e.message);
+            }
+            return discarded;
+        }
+        async discardStagedModeOnlyChanges(paths) {
+            const discarded = [];
+            for (const relativePath of paths)try {
+                const headMode = await this.getHeadFileMode(relativePath);
+                if ("100644" !== headMode && "100755" !== headMode) continue;
+                const indexContentUnchanged = await this.hasSameIndexContentAsHead(relativePath);
+                if (!indexContentUnchanged) continue;
+                await this.git.raw([
+                    "reset",
+                    "-q",
+                    "HEAD",
+                    "--",
+                    relativePath
+                ]);
+                await this.restoreExecutableBit(relativePath, "100755" === headMode);
+                discarded.push(relativePath);
+            } catch (e) {
+                throw errors_createGitError.commandFailed("discard staged mode-only changes", e.message);
+            }
+            return discarded;
+        }
+        async getHeadFileMode(relativePath) {
+            const output = await this.git.raw([
+                "ls-tree",
+                "HEAD",
+                "--",
+                relativePath
+            ]);
+            const match = output.match(/^(\d{6})\s/);
+            return match?.[1] ?? null;
+        }
+        async hasSameContentAsHead(relativePath) {
+            const headHash = (await this.git.revparse([
+                `HEAD:${relativePath}`
+            ])).trim();
+            const worktreeHash = (await this.git.raw([
+                "hash-object",
+                "--",
+                relativePath
+            ])).trim();
+            return headHash === worktreeHash;
+        }
+        async hasSameIndexContentAsHead(relativePath) {
+            const headHash = (await this.git.revparse([
+                `HEAD:${relativePath}`
+            ])).trim();
+            const indexHash = (await this.git.revparse([
+                `:${relativePath}`
+            ])).trim();
+            return headHash === indexHash;
+        }
+        async restoreExecutableBit(relativePath, executable) {
+            const filePath = external_path_default().join(this.repoPath, relativePath);
+            const stat = await external_fs_.promises.stat(filePath);
+            const mode = executable ? 73 | stat.mode : -74 & stat.mode;
+            if ((511 & stat.mode) !== (511 & mode)) await external_fs_.promises.chmod(filePath, mode);
+        }
         async hasUncommittedChanges() {
             const status = await this.getStatus();
             return !status.isClean;
@@ -14828,6 +14899,32 @@ Promise.resolve(executeGitCredentialOperation(process.argv[2] || "get", {
                 throw errors_createGitError.commandFailed("rebase --abort", e.message);
             }
         }
+        async isAncestor(ancestorRef, descendantRef) {
+            try {
+                const mergeBase = (await this.git.raw([
+                    "merge-base",
+                    ancestorRef,
+                    descendantRef
+                ])).trim();
+                const ancestorCommit = (await this.git.revparse([
+                    ancestorRef
+                ])).trim();
+                return mergeBase === ancestorCommit;
+            } catch  {
+                return false;
+            }
+        }
+        async mergeFastForward(ref) {
+            try {
+                await this.git.raw([
+                    "merge",
+                    "--ff-only",
+                    ref
+                ]);
+            } catch (e) {
+                throw errors_createGitError.commandFailed("merge --ff-only", e.message);
+            }
+        }
         async deleteRef(ref) {
             try {
                 await this.git.raw([
@@ -14872,11 +14969,12 @@ Promise.resolve(executeGitCredentialOperation(process.argv[2] || "get", {
             } catch (error) {}
         }
     }
-    async function getStagedFileChanges(git) {
+    async function getStagedFileChanges(git, gitService) {
         try {
             const status = await git.status();
             const renames = status.renamed || [];
             const stagedFiles = status.files.filter((f)=>" " !== f.index && "?" !== f.index);
+            const stagedModeOnlyPaths = new Set(gitService ? await gitService.discardStagedModeOnlyChanges(stagedFiles.filter((f)=>"R" !== f.index && "D" !== f.index).map((f)=>f.path)) : []);
             const stagedRenames = [];
             for (const f of stagedFiles)if ("R" === f.index) {
                 const rename = renames.find((r)=>r.to === f.path);
@@ -14889,19 +14987,23 @@ Promise.resolve(executeGitCredentialOperation(process.argv[2] || "get", {
             const stagedRenamedFromPaths = new Set(stagedRenames.map((r)=>r.from));
             const stagedRenamedToPaths = new Set(stagedRenames.map((r)=>r.path));
             const changes = [];
-            for (const f of stagedFiles)if ("R" !== f.index) {
-                if (!(stagedRenamedFromPaths.has(f.path) || stagedRenamedToPaths.has(f.path))) if ("D" === f.index) changes.push({
-                    path: f.path,
-                    type: "unlink"
-                });
-                else if ("A" === f.index || "?" === f.index) changes.push({
-                    path: f.path,
-                    type: "add"
-                });
-                else changes.push({
-                    path: f.path,
-                    type: "change"
-                });
+            for (const f of stagedFiles){
+                if ("R" !== f.index) {
+                    if (!stagedModeOnlyPaths.has(f.path)) {
+                        if (!(stagedRenamedFromPaths.has(f.path) || stagedRenamedToPaths.has(f.path))) if ("D" === f.index) changes.push({
+                            path: f.path,
+                            type: "unlink"
+                        });
+                        else if ("A" === f.index || "?" === f.index) changes.push({
+                            path: f.path,
+                            type: "add"
+                        });
+                        else changes.push({
+                            path: f.path,
+                            type: "change"
+                        });
+                    }
+                }
             }
             changes.push(...stagedRenames);
             return changes;
@@ -17657,13 +17759,14 @@ Promise.resolve(executeGitCredentialOperation(process.argv[2] || "get", {
         }
         async getStagedChanges() {
             try {
-                return await getStagedFileChanges(this.config.gitService.getGit());
+                return await getStagedFileChanges(this.config.gitService.getGit(), this.config.gitService);
             } catch (e) {
                 logger_logger.error(external_chalk_default().red(`Error getting staged changes: ${errors_getErrorMessage(e)}`));
                 return [];
             }
         }
         async getUnstagedChanges(status) {
+            const modeOnlyChanges = new Set(await this.config.gitService.discardModeOnlyChanges(status.modified));
             const renames = status.renamed;
             const stagedRenamedFromPaths = new Set(renames.map((r)=>r.from));
             const stagedRenamedToPaths = new Set(renames.map((r)=>r.to));
@@ -17683,7 +17786,7 @@ Promise.resolve(executeGitCredentialOperation(process.argv[2] || "get", {
             const allRenamedFromPaths = new Set(allRenames.map((r)=>r.from));
             const allRenamedToPaths = new Set(allRenames.map((r)=>r.to));
             return [
-                ...status.modified.map((f)=>({
+                ...status.modified.filter((f)=>!modeOnlyChanges.has(f)).map((f)=>({
                         path: f,
                         type: "change"
                     })),
@@ -17891,7 +17994,7 @@ Promise.resolve(executeGitCredentialOperation(process.argv[2] || "get", {
                 await this.handleConflict(json_resp, originalFilePaths, retryCount);
                 return;
             }
-            if (200 === resp.status) return void await this.handleSuccess(json_resp);
+            if (200 === resp.status) return void await this.handleSuccess(json_resp, originalFilePaths);
             logger_logger.error(`Unexpected response status: ${resp.status}`);
             throw {
                 type: "server_error",
@@ -17994,13 +18097,20 @@ Promise.resolve(executeGitCredentialOperation(process.argv[2] || "get", {
                 reason: "Unknown conflict"
             };
         }
-        async handleSuccess(json_resp) {
+        async handleSuccess(json_resp, originalFilePaths) {
             const version = json_resp.version;
-            this.config.setCommitId(version);
+            const oldCommitId = json_resp.previous_commit ?? null;
+            const commitIdBeforePostSaveSync = this.config.getCommitId();
+            this.emit("saved", {
+                oldCommitId,
+                newCommitId: version,
+                branch: this.config.getCurrentBranch()
+            });
             if (this.postSaveCallback) {
                 logger_logger.progressUpdate("sync", "Syncing back");
-                await this.postSaveCallback();
+                await this.postSaveCallback(new Set(originalFilePaths));
             }
+            if (this.config.getCommitId() === commitIdBeforePostSaveSync) this.config.setCommitId(version);
         }
         async rerouteChanges(changes) {
             logger_logger.verbose(external_chalk_default().blue(`Re-routing ${changes.length} local change(s)...`));
@@ -18071,12 +18181,22 @@ Promise.resolve(executeGitCredentialOperation(process.argv[2] || "get", {
             try {
                 const oldCommitId = this.config.getCommitId();
                 let locallyChangedFiles;
+                let initialStatus;
                 if (knownLocalChanges) locallyChangedFiles = knownLocalChanges;
                 else {
-                    const status = await this.config.gitService.getStatus();
-                    locallyChangedFiles = buildLocalChangesSet(status);
+                    initialStatus = await this.config.gitService.getStatus();
+                    locallyChangedFiles = buildLocalChangesSet(initialStatus);
                 }
-                await this.fetchAndResetFromAnvil(locallyChangedFiles);
+                let syncMode;
+                if (!knownLocalChanges && initialStatus && this.isCleanForFastForward(initialStatus)) syncMode = await this.fetchAndMoveCleanTreeToAnvilHead(oldCommitId, locallyChangedFiles);
+                else {
+                    await this.fetchAndResetFromAnvil(locallyChangedFiles);
+                    syncMode = "preservation";
+                }
+                if ("clean-move" === syncMode) return {
+                    localOnlyChanges: [],
+                    conflicts: []
+                };
                 const newCommitId = await this.config.gitService.getCommitId();
                 this.config.setCommitId(newCommitId);
                 const remoteChangedFiles = await detectRemoteChanges(this.config.gitService, oldCommitId, newCommitId);
@@ -18101,15 +18221,43 @@ Promise.resolve(executeGitCredentialOperation(process.argv[2] || "get", {
             }
         }
         async fetchAndResetFromAnvil(localChangesToPreserve = new Set()) {
+            const oldCommitId = this.config.getCommitId();
+            await this.withFetchedAnvilRef((tempRef)=>this.resetToFetchedAnvilRef(tempRef, oldCommitId, localChangesToPreserve));
+        }
+        async fetchAndMoveCleanTreeToAnvilHead(oldCommitId, locallyChangedFiles) {
+            return this.withFetchedAnvilRef(async (tempRef)=>{
+                const localHead = await this.config.gitService.getCommitId();
+                if (await this.config.gitService.isAncestor(localHead, tempRef)) await this.config.gitService.mergeFastForward(tempRef);
+                else {
+                    const statusBeforeHardReset = await this.config.gitService.getStatus();
+                    if (!this.isCleanForFastForward(statusBeforeHardReset)) {
+                        for (const filePath of buildLocalChangesSet(statusBeforeHardReset))locallyChangedFiles.add(filePath);
+                        await this.resetToFetchedAnvilRef(tempRef, oldCommitId, locallyChangedFiles);
+                        return "preservation";
+                    }
+                    await this.config.gitService.reset(tempRef, "hard");
+                }
+                const newCommitId = await this.config.gitService.getCommitId();
+                this.config.setCommitId(newCommitId);
+                await this.config.editorYaml.reload();
+                return "clean-move";
+            });
+        }
+        async withFetchedAnvilRef(callback) {
             const validToken = await auth_getValidAuthToken(this.config.anvilUrl, this.config.username);
             this.config.setAuthToken(validToken);
             const httpUrl = getGitFetchUrl(this.config.appId, this.config.getAuthToken(), this.config.anvilUrl);
             const currentBranch = this.config.getCurrentBranch();
             const tempRef = `anvil-sync-temp-${Date.now()}`;
-            const oldCommitId = this.config.getCommitId();
-            await this.config.gitService.fetch(httpUrl, `+${currentBranch}:${tempRef}`);
+            try {
+                await this.config.gitService.fetch(httpUrl, `+${currentBranch}:${tempRef}`);
+                return await callback(tempRef);
+            } finally{
+                await this.config.gitService.deleteRef(`refs/heads/${tempRef}`);
+            }
+        }
+        async resetToFetchedAnvilRef(tempRef, oldCommitId, localChangesToPreserve) {
             await this.config.gitService.reset(tempRef, "mixed");
-            await this.config.gitService.deleteRef(`refs/heads/${tempRef}`);
             const newCommitId = await this.config.gitService.getCommitId();
             await this.config.gitService.checkout([
                 ".anvil_editor.yaml",
@@ -18119,6 +18267,9 @@ Promise.resolve(executeGitCredentialOperation(process.argv[2] || "get", {
             await this.deleteFilesRemovedOnAnvilLocally(oldCommitId, newCommitId, localChangesToPreserve);
             await this.discardFormattingOnlyYamlChanges();
         }
+        isCleanForFastForward(status) {
+            return status.isClean && 0 === status.modified.length && 0 === status.notAdded.length && 0 === status.created.length && 0 === status.deleted.length && 0 === status.staged.length && 0 === status.renamed.length;
+        }
         async deleteFilesRemovedOnAnvilLocally(oldCommitId, newCommitId, localChangesToPreserve) {
             try {
                 const status = await this.config.gitService.getStatus();
@@ -18332,11 +18483,12 @@ Promise.resolve(executeGitCredentialOperation(process.argv[2] || "get", {
                 isPaused: ()=>this.isPausedForUserInput
             });
             this.saveProcessor.setSyncCallback((filePaths)=>this.syncManager.syncRemoteChanges(filePaths));
-            this.saveProcessor.setPostSaveCallback(()=>this.syncManager.fetchAndResetFromAnvil());
+            this.saveProcessor.setPostSaveCallback((filePaths)=>this.syncAfterSave(filePaths));
             this.saveProcessor.on("save-started", (data)=>this.emit("save-started", data));
             this.saveProcessor.on("save-succeeded", (data)=>this.emit("save-succeeded", data));
             this.saveProcessor.on("save-failed", (data)=>this.emit("save-failed", data));
             this.saveProcessor.on("save-complete", (data)=>this.emit("save-complete", data));
+            this.saveProcessor.on("saved", (data)=>this.emit("saved", data));
             this.saveProcessor.on("anvil-yaml-dependencies-changed", ()=>{
                 this.queueDependencyRefresh("anvil.yaml dependencies changed");
             });
@@ -18344,6 +18496,12 @@ Promise.resolve(executeGitCredentialOperation(process.argv[2] || "get", {
             this.saveProcessor.on("sync-conflict", (data)=>this.emit("sync-conflict", data));
             this.saveProcessor.on("max-retries-exceeded", (data)=>this.emit("max-retries-exceeded", data));
         }
+        async syncAfterSave(savedFilePaths) {
+            const status = await this.gitService.getStatus();
+            const locallyChangedFiles = buildLocalChangesSet(status);
+            if (!this.stagedOnly) for (const filePath of savedFilePaths)locallyChangedFiles.add(filePath);
+            return this.syncManager.syncRemoteChanges(locallyChangedFiles);
+        }
         async connectWebSocket() {
             this.wsClient = new WebSocketClient({
                 appId: this.appId,
@@ -20170,12 +20328,396 @@ Promise.resolve(executeGitCredentialOperation(process.argv[2] || "get", {
         });
         checkoutCommand.addHelpText("after", "\n" + external_chalk_default().bold("Examples:") + '\n  anvil checkout http://localhost:3000/build/apps/APPID/code/assets/theme.css\n  anvil checkout https://anvil.works/git/APPID.git\n  anvil checkout APPID --url anvil.works\n  anvil checkout APPID --branch master --depth 1 --single-branch\n  anvil checkout APPID -O  # open editor/file browser after checkout\n  anvil checkout APPID my-local-folder --force\n  anvil checkout  # interactive search/select app list\n  anvil checkout -Q "dashboard"  # preseed picker search\n');
     }
+    const defaultGitAuthDoctorDeps = {
+        getAppAuthBinding: getAppAuthBinding,
+        getAccountsForUrl: auth_getAccountsForUrl,
+        hasTokensForUrl: hasTokensForUrl,
+        runCredentialFill: runGitCredentialFill
+    };
+    function getHighestStatus(statuses) {
+        if (statuses.includes("error")) return "error";
+        if (statuses.includes("warning")) return "warning";
+        return "ok";
+    }
+    function finding(status, code, message) {
+        return {
+            status,
+            code,
+            message
+        };
+    }
+    function redactSecrets(value) {
+        return value.replace(/^password=.*$/gim, "password=<redacted>").replace(/(https?:\/\/git:)[^@\s]+@/g, "$1<redacted>@").replace(/(access[_-]?token=)[^&\s]+/gi, "$1<redacted>").replace(/(refresh[_-]?token=)[^&\s]+/gi, "$1<redacted>");
+    }
+    function splitShellCommand(command) {
+        const tokens = [];
+        let current = "";
+        let state = "normal";
+        for(let i = 0; i < command.length; i++){
+            const ch = command[i];
+            if ("single" === state) {
+                if ("'" === ch) state = "normal";
+                else current += ch;
+                continue;
+            }
+            if ("double" === state) {
+                if ("\"" === ch) state = "normal";
+                else if ("\\" === ch && i + 1 < command.length && [
+                    "$",
+                    "`",
+                    "\"",
+                    "\\",
+                    "\n"
+                ].includes(command[i + 1])) current += command[++i];
+                else current += ch;
+                continue;
+            }
+            if (/\s/.test(ch)) {
+                if (current) {
+                    tokens.push(current);
+                    current = "";
+                }
+            } else if ("'" === ch) state = "single";
+            else if ("\"" === ch) state = "double";
+            else if ("\\" === ch && i + 1 < command.length) current += command[++i];
+            else current += ch;
+        }
+        if ("normal" !== state) throw new Error("Unterminated quote in helper command");
+        if (current) tokens.push(current);
+        return tokens;
+    }
+    function parseCredentialHelperCommand(command) {
+        const trimmed = command.trim();
+        if (!trimmed || !trimmed.startsWith("!")) return {};
+        const tokens = splitShellCommand(trimmed.slice(1).trim());
+        return {
+            execPath: tokens[0],
+            helperPath: tokens[1]
+        };
+    }
+    function readHelperModulePath(helperPath) {
+        try {
+            const helperSource = external_fs_default().readFileSync(helperPath, "utf8");
+            const match = helperSource.match(/executeGitCredentialOperation\s*}\s*=\s*require\((["'])(.*?)\1\)/);
+            return match?.[2];
+        } catch  {
+            return;
+        }
+    }
+    function inspectCredentialHelperCommand(raw) {
+        const details = {
+            raw
+        };
+        try {
+            const parsed = parseCredentialHelperCommand(raw);
+            details.execPath = parsed.execPath;
+            details.helperPath = parsed.helperPath;
+        } catch (e) {
+            details.parseError = e.message;
+            return details;
+        }
+        if (details.execPath) details.execExists = external_fs_default().existsSync(details.execPath);
+        if (details.helperPath) {
+            details.helperExists = external_fs_default().existsSync(details.helperPath);
+            if (details.helperExists) {
+                try {
+                    const stat = external_fs_default().statSync(details.helperPath);
+                    details.helperExecutable = (73 & stat.mode) !== 0;
+                } catch  {
+                    details.helperExecutable = false;
+                }
+                details.modulePath = readHelperModulePath(details.helperPath);
+                if (details.modulePath) details.moduleExists = external_fs_default().existsSync(details.modulePath);
+            }
+        }
+        return details;
+    }
+    function detectAnvilRemote(remote) {
+        const fetchUrl = remote.refs.fetch;
+        const out = {
+            name: remote.name,
+            fetchUrl
+        };
+        if (!fetchUrl) return out;
+        const httpMatch = fetchUrl.match(/^(https?):\/\/(?:[^@/?#]+@)?([^/?#]+)\/git\/([A-Z0-9]+)\.git(?:[?#].*)?$/);
+        if (httpMatch) {
+            const [, protocol, host, appId] = httpMatch;
+            return {
+                ...out,
+                appId,
+                anvilUrl: normalizeAnvilUrl(`${protocol}://${host}`),
+                transport: "https"
+            };
+        }
+        const sshMatch = fetchUrl.match(/^ssh:\/\/(?:([^@]+)@)?([^:\/]+)(?::\d+)?\/(?:git\/)?([A-Z0-9]+)\.git(?:[?#].*)?$/);
+        if (sshMatch) {
+            const [, , host, appId] = sshMatch;
+            return {
+                ...out,
+                appId,
+                anvilUrl: normalizeAnvilUrl(host),
+                transport: "ssh"
+            };
+        }
+        return out;
+    }
+    async function getLocalConfigValues(repoPath, key) {
+        try {
+            const output = await esm_default(repoPath).raw([
+                "config",
+                "--local",
+                "--get-all",
+                key
+            ]);
+            const values = output.split(/\r?\n/);
+            if ("" === values[values.length - 1]) values.pop();
+            return values;
+        } catch  {
+            return [];
+        }
+    }
+    function buildCredentialInput(anvilUrl, appId) {
+        const url = new URL(anvilUrl);
+        return `protocol=${url.protocol.replace(/:$/, "")}\nhost=${url.host}\npath=git/${appId}.git\n\n`;
+    }
+    async function runGitCredentialFill(repoPath, input) {
+        return new Promise((resolve)=>{
+            const child = (0, external_child_process_namespaceObject.spawn)("git", [
+                "credential",
+                "fill"
+            ], {
+                cwd: repoPath,
+                env: {
+                    ...process.env,
+                    GIT_TERMINAL_PROMPT: "0"
+                },
+                stdio: [
+                    "pipe",
+                    "pipe",
+                    "pipe"
+                ]
+            });
+            let stdout = "";
+            let stderr = "";
+            child.stdout.setEncoding("utf8");
+            child.stderr.setEncoding("utf8");
+            child.stdout.on("data", (chunk)=>{
+                stdout += chunk;
+            });
+            child.stderr.on("data", (chunk)=>{
+                stderr += chunk;
+            });
+            child.on("error", (error)=>{
+                resolve({
+                    exitCode: null,
+                    stdout: redactSecrets(stdout),
+                    stderr: redactSecrets(stderr),
+                    error: redactSecrets(error.message)
+                });
+            });
+            child.on("close", (code)=>{
+                resolve({
+                    exitCode: code,
+                    stdout: redactSecrets(stdout),
+                    stderr: redactSecrets(stderr)
+                });
+            });
+            child.stdin.end(input);
+        });
+    }
+    async function buildAppReport(repoPath, remote, deps) {
+        const appId = remote.appId;
+        const anvilUrl = remote.anvilUrl;
+        const url = new URL(anvilUrl);
+        const credentialScope = `${url.protocol}//${url.host}`;
+        const helperConfigKey = `credential.${credentialScope}.helper`;
+        const helperValues = await getLocalConfigValues(repoPath, helperConfigKey);
+        const nonEmptyHelperValues = helperValues.filter((value)=>"" !== value.trim());
+        const helperDetails = nonEmptyHelperValues.map(inspectCredentialHelperCommand);
+        const findings = [];
+        if (0 === helperValues.length) findings.push(finding("error", "missing_helper_config", `No local ${helperConfigKey} entries found.`));
+        else if (0 === nonEmptyHelperValues.length) findings.push(finding("error", "missing_helper_command", `${helperConfigKey} only resets helpers; no Anvil helper command is configured.`));
+        for (const helper of helperDetails){
+            if (helper.parseError) findings.push(finding("error", "helper_parse_failed", `Could not parse helper command: ${helper.parseError}`));
+            if (helper.execPath && false === helper.execExists) findings.push(finding("error", "helper_exec_missing", `Credential helper Node executable does not exist: ${helper.execPath}`));
+            if (helper.helperPath) {
+                if (false === helper.helperExists) findings.push(finding("error", "helper_file_missing", `Credential helper script does not exist: ${helper.helperPath}`));
+                else if (false === helper.helperExecutable) findings.push(finding("warning", "helper_not_executable", `Credential helper script is not executable: ${helper.helperPath}`));
+            } else findings.push(finding("error", "helper_path_missing", "Credential helper command does not include a helper script path."));
+            if (helper.modulePath && false === helper.moduleExists) findings.push(finding("error", "helper_module_missing", `Generated helper points at a missing module: ${helper.modulePath}`));
+            if (helper.modulePath && "cli.js" === external_path_default().basename(helper.modulePath)) findings.push(finding("error", "helper_module_cli_entry", `Generated helper points at the CLI entry instead of the API entry: ${helper.modulePath}`));
+        }
+        const binding = await deps.getAppAuthBinding(repoPath, appId);
+        if (!binding.url) findings.push(finding("warning", "missing_app_binding_url", `No anvil.auth.${appId}.url binding is configured.`));
+        if (!binding.username) findings.push(finding("warning", "missing_app_binding_username", `No anvil.auth.${appId}.username binding is configured.`));
+        const authUrl = binding.url ? normalizeAnvilUrl(binding.url) : anvilUrl;
+        let accounts = [];
+        let authUsername = binding.username;
+        let hasUsableAuth = false;
+        try {
+            accounts = await deps.getAccountsForUrl(authUrl);
+            if (authUsername || 1 !== accounts.length) {
+                if (!authUsername && accounts.length > 1) findings.push(finding("error", "multiple_accounts_without_binding", `Multiple accounts are logged in for ${authUrl}; bind one with anvil checkout --user.`));
+            } else authUsername = accounts[0];
+            hasUsableAuth = authUsername ? await deps.hasTokensForUrl(authUrl, authUsername) : accounts.length <= 1 && await deps.hasTokensForUrl(authUrl);
+            if (!hasUsableAuth) findings.push(finding("error", "missing_usable_auth", authUsername ? `No usable auth tokens found for ${authUrl} as ${authUsername}.` : `No usable auth tokens found for ${authUrl}.`));
+        } catch (e) {
+            findings.push(finding("error", "auth_lookup_failed", `Auth lookup failed: ${redactSecrets(e.message)}`));
+        }
+        const fillResult = await deps.runCredentialFill(repoPath, buildCredentialInput(anvilUrl, appId));
+        const credentialSimulation = {
+            status: 0 === fillResult.exitCode && /^password=/im.test(fillResult.stdout) ? "ok" : "error",
+            exitCode: fillResult.exitCode,
+            stdout: redactSecrets(fillResult.stdout),
+            stderr: redactSecrets(fillResult.stderr),
+            error: fillResult.error ? redactSecrets(fillResult.error) : void 0
+        };
+        if ("ok" !== credentialSimulation.status) findings.push(finding("error", "credential_fill_failed", credentialSimulation.error || credentialSimulation.stderr.trim() || "git credential fill did not return a password."));
+        const report = {
+            appId,
+            anvilUrl,
+            remoteName: remote.name,
+            remoteUrl: remote.fetchUrl,
+            credentialScope,
+            helperConfigKey,
+            helperValues,
+            helperDetails,
+            binding: {
+                url: binding.url,
+                username: binding.username,
+                hasUrl: !!binding.url,
+                hasUsername: !!binding.username
+            },
+            auth: {
+                url: authUrl,
+                username: authUsername,
+                accounts,
+                hasUsableAuth
+            },
+            credentialSimulation,
+            findings
+        };
+        return report;
+    }
+    async function buildGitAuthDoctorReport(repoPathInput = process.cwd(), options = {}) {
+        const deps = options.deps ?? defaultGitAuthDoctorDeps;
+        const inputPath = external_path_default().resolve(repoPathInput);
+        const git = esm_default(inputPath);
+        const repoPath = (await git.raw([
+            "rev-parse",
+            "--show-toplevel"
+        ])).trim();
+        const rawGitDir = (await git.raw([
+            "rev-parse",
+            "--git-dir"
+        ])).trim();
+        const gitDir = external_path_default().isAbsolute(rawGitDir) ? rawGitDir : external_path_default().resolve(inputPath, rawGitDir);
+        setRepoContext(repoPath);
+        const remotes = (await git.getRemotes(true)).map(detectAnvilRemote);
+        const anvilRemotes = remotes.filter((remote)=>remote.appId && remote.anvilUrl && "https" === remote.transport);
+        const findings = [];
+        if (0 === anvilRemotes.length) findings.push(finding("error", "missing_anvil_https_remote", "No HTTPS Anvil git remotes were detected."));
+        const apps = await Promise.all(anvilRemotes.map((remote)=>buildAppReport(repoPath, remote, deps)));
+        const status = getHighestStatus([
+            ...findings.map((item)=>item.status),
+            ...apps.flatMap((app)=>app.findings.map((item)=>item.status))
+        ]);
+        return {
+            repoPath,
+            gitDir,
+            remotes,
+            apps,
+            findings,
+            status
+        };
+    }
+    function formatStatus(status) {
+        if ("ok" === status) return external_chalk_default().green("[ok]");
+        if ("warning" === status) return external_chalk_default().yellow("[warn]");
+        return external_chalk_default().red("[error]");
+    }
+    function formatGitAuthDoctorReport(report) {
+        const lines = [];
+        lines.push(external_chalk_default().bold("Git auth doctor"));
+        lines.push(`Repository: ${report.repoPath}`);
+        lines.push(`Git dir: ${report.gitDir}`);
+        lines.push(`Overall: ${formatStatus(report.status)}`);
+        lines.push("");
+        lines.push(external_chalk_default().bold("Detected remotes:"));
+        if (0 === report.remotes.length) lines.push("  (none)");
+        else for (const remote of report.remotes){
+            const appText = remote.appId && remote.anvilUrl ? ` -> ${remote.appId} on ${remote.anvilUrl}` : "";
+            lines.push(`  - ${remote.name}: ${remote.fetchUrl || "(no fetch URL)"}${appText}`);
+        }
+        for (const app of report.apps){
+            lines.push("");
+            lines.push(external_chalk_default().bold(`App ${app.appId} (${app.remoteName})`));
+            lines.push(`  URL: ${app.anvilUrl}`);
+            lines.push(`  Credential scope: ${app.credentialScope}`);
+            lines.push(`  Helper config: ${app.helperConfigKey}`);
+            if (0 === app.helperValues.length) lines.push("    (none)");
+            else for (const value of app.helperValues)lines.push(`    - ${value || "(reset helper list)"}`);
+            for (const helper of app.helperDetails){
+                lines.push(`  Helper command: ${helper.raw}`);
+                lines.push(`    Node: ${helper.execPath || "(missing)"} ${false === helper.execExists ? "[missing]" : ""}`.trimEnd());
+                lines.push(`    Script: ${helper.helperPath || "(missing)"} ${false === helper.helperExists ? "[missing]" : ""}`.trimEnd());
+                if (helper.modulePath) lines.push(`    Module: ${helper.modulePath} ${false === helper.moduleExists ? "[missing]" : ""}`.trimEnd());
+            }
+            lines.push(`  Binding URL: ${app.binding.url || "(missing)"}`);
+            lines.push(`  Binding user: ${app.binding.username || "(missing)"}`);
+            lines.push(`  Auth tokens: ${app.auth.hasUsableAuth ? "available" : "not available"}${app.auth.username ? ` for ${app.auth.username}` : ""}`);
+            if (app.credentialSimulation) {
+                lines.push(`  Credential fill: ${formatStatus(app.credentialSimulation.status)} exit=${app.credentialSimulation.exitCode}`);
+                if (app.credentialSimulation.stdout.trim()) {
+                    lines.push("    stdout:");
+                    for (const line of app.credentialSimulation.stdout.trim().split(/\r?\n/))lines.push(`      ${line}`);
+                }
+                if (app.credentialSimulation.stderr.trim()) {
+                    lines.push("    stderr:");
+                    for (const line of app.credentialSimulation.stderr.trim().split(/\r?\n/))lines.push(`      ${line}`);
+                }
+            }
+            if (app.findings.length > 0) {
+                lines.push("  Findings:");
+                for (const item of app.findings)lines.push(`    ${formatStatus(item.status)} ${item.code}: ${item.message}`);
+            }
+        }
+        if (report.findings.length > 0) {
+            lines.push("");
+            lines.push(external_chalk_default().bold("Repository findings:"));
+            for (const item of report.findings)lines.push(`  ${formatStatus(item.status)} ${item.code}: ${item.message}`);
+        }
+        return lines.join("\n");
+    }
+    function registerGitAuthCommand(program) {
+        const gitAuthCommand = program.command("git-auth").description("Diagnose Anvil Git authentication");
+        gitAuthCommand.command("doctor").description("Diagnose why plain Git commands cannot authenticate to Anvil").option("--repo <PATH>", "Repository path to diagnose", process.cwd()).action(async (options)=>{
+            try {
+                const report = await buildGitAuthDoctorReport(options.repo || process.cwd());
+                if (getGlobalOutputConfig().jsonMode) logJsonResult("error" !== report.status, {
+                    data: report
+                });
+                else logger_logger.info(formatGitAuthDoctorReport(report));
+                if ("error" === report.status) process.exitCode = 1;
+            } catch (e) {
+                const message = redactSecrets(e.message);
+                if (getGlobalOutputConfig().jsonMode) logJsonResult(false, {
+                    error: message
+                });
+                else logger_logger.error(`Git auth doctor failed: ${message}`);
+                process.exitCode = 1;
+            }
+        });
+    }
     const gitCredential_defaultDeps = {
         getValidAuthToken: auth_getValidAuthToken,
         getAccountsForUrl: auth_getAccountsForUrl,
         getAppAuthBinding: getAppAuthBinding,
         cwd: ()=>process.cwd()
     };
+    function sanitizeCredentialError(message) {
+        return message.replace(/^password=.*$/gim, "password=<redacted>").replace(/(https?:\/\/git:)[^@\s]+@/g, "$1<redacted>@").replace(/(access[_-]?token=)[^&\s]+/gi, "$1<redacted>").replace(/(refresh[_-]?token=)[^&\s]+/gi, "$1<redacted>");
+    }
     function parseGitCredentialRequest(rawInput) {
         const out = {};
         const lines = rawInput.split(/\r?\n/);
@@ -20236,7 +20778,11 @@ Promise.resolve(executeGitCredentialOperation(process.argv[2] || "get", {
         }).description("Internal helper command for Git HTTPS authentication").action(async (operation)=>{
             try {
                 await executeGitCredentialOperation(operation);
-            } catch  {
+            } catch (e) {
+                if ("1" === process.env["ANVIL_GIT_CREDENTIAL_DEBUG"]) {
+                    const message = e instanceof Error ? e.message : String(e);
+                    process.stderr.write(`anvil git-credential failed: ${sanitizeCredentialError(message)}\n`);
+                }
                 process.exit(1);
             }
         });
@@ -21945,6 +22491,7 @@ Promise.resolve(executeGitCredentialOperation(process.argv[2] || "get", {
         });
         const watchCommand = registerWatchCommand(program);
         registerCheckoutCommand(program);
+        registerGitAuthCommand(program);
         registerGitCredentialCommand(program);
         registerLoginCommand(program);
         registerLogoutCommand(program);