@anvil-works/anvil-cli 0.4.3 → 0.5.1

package/dist/cli.js

@@ -42459,8 +42459,31 @@ var __webpack_exports__ = {};
     }
     const configDefaults = {
         devMode: false,
-        verbose: false
+        verbose: false,
+        preferredEditor: ""
+    };
+    const preferredEditors = [
+        "vscode",
+        "cursor",
+        "nvim",
+        "zed",
+        "windsurf",
+        "pycharm"
+    ];
+    const preferredEditorCommandByValue = {
+        vscode: "code",
+        cursor: "cursor",
+        nvim: "nvim",
+        zed: "zed",
+        windsurf: "windsurf",
+        pycharm: "charm"
     };
+    const settableConfigKeys = [
+        "anvilUrl",
+        "devMode",
+        "verbose",
+        "preferredEditor"
+    ];
     function isTestMode() {
         return "test" === process.env.NODE_ENV || !!process.env.RSTEST;
     }
@@ -42532,6 +42555,23 @@ var __webpack_exports__ = {};
         }
         return value;
     }
+    function parseConfigSetValue(key, value) {
+        if (!settableConfigKeys.includes(key)) throw new Error(`✖ Error: unknown config key '${key}'. Allowed keys: ${settableConfigKeys.join(", ")}`);
+        if ("preferredEditor" === key) {
+            let normalized = value.trim().toLowerCase();
+            if ("code" === normalized) normalized = "vscode";
+            if (!preferredEditors.includes(normalized)) throw new Error(`✖ Error: preferredEditor must be one of: ${preferredEditors.join(", ")} (alias: code -> vscode)`);
+            return normalized;
+        }
+        if ("anvilUrl" === key) return value.trim().replace(/\/+$/, "");
+        return coerceConfigValue(key, value);
+    }
+    function getPreferredEditorCommand(preferredEditorValue) {
+        const normalized = preferredEditorValue.trim().toLowerCase();
+        if ("code" === normalized) return "code";
+        if (preferredEditors.includes(normalized)) return preferredEditorCommandByValue[normalized];
+        return preferredEditorValue;
+    }
     function getAllConfig() {
         return config_config.store;
     }
@@ -47584,6 +47624,7 @@ var __webpack_exports__ = {};
             });
             this.ws.on("error", (error)=>{
                 logger_logger.debug(`[WebSocket ${this.sessionId}]`, `Error: ${error.message}`);
+                if (this.isClosing) return;
                 if (error.message.includes("502")) logger_logger.error(chalk_source.red("WebSocket connection failed (502 Bad Gateway) - likely a temporary server issue"));
                 else logger_logger.error(chalk_source.red(`WebSocket error: ${error.message}`));
                 this.emit("error", {
@@ -47684,15 +47725,20 @@ var __webpack_exports__ = {};
         }
         teardownSocket() {
             this.stopHeartbeat();
-            if (!this.ws) return;
+            const socket = this.ws;
+            this.ws = null;
+            if (!socket) return;
             try {
                 logger_logger.debug(`[WebSocket ${this.sessionId}]`, "Closing WebSocket");
-                this.ws.removeAllListeners();
-                if (this.ws.readyState === ws_wrapper.OPEN || this.ws.readyState === ws_wrapper.CONNECTING) this.ws.terminate();
+                if (socket.readyState === ws_wrapper.CONNECTING) {
+                    socket.once("error", ()=>{});
+                    socket.terminate();
+                    return;
+                }
+                if (socket.readyState === ws_wrapper.OPEN) return void socket.close();
             } catch (e) {
                 logger_logger.debug(`[WebSocket ${this.sessionId}]`, "Error closing WebSocket (ignoring):", e);
             }
-            this.ws = null;
         }
     }
     async function detectRemoteChanges(gitService, oldCommitId, newCommitId) {
@@ -49956,6 +50002,121 @@ var __webpack_exports__ = {};
         session.hasUncommittedChanges = hasUncommittedChanges;
         return session;
     }
+    function getUrlConfigKey(appId) {
+        return `anvil.auth.${appId}.url`;
+    }
+    function getUsernameConfigKey(appId) {
+        return `anvil.auth.${appId}.username`;
+    }
+    async function getLocalConfigValue(repoPath, key) {
+        try {
+            const value = (await esm_default(repoPath).raw([
+                "config",
+                "--local",
+                "--get",
+                key
+            ])).trim();
+            return value || void 0;
+        } catch  {
+            return;
+        }
+    }
+    async function getAppAuthBinding(repoPath, appId) {
+        const [url, username] = await Promise.all([
+            getLocalConfigValue(repoPath, getUrlConfigKey(appId)),
+            getLocalConfigValue(repoPath, getUsernameConfigKey(appId))
+        ]);
+        return {
+            url: url ? normalizeAnvilUrl(url) : void 0,
+            username: username || void 0
+        };
+    }
+    async function setAppAuthBinding(repoPath, appId, binding) {
+        const git = esm_default(repoPath);
+        if (binding.url) await git.raw([
+            "config",
+            "--local",
+            getUrlConfigKey(appId),
+            normalizeAnvilUrl(binding.url)
+        ]);
+        if (binding.username) await git.raw([
+            "config",
+            "--local",
+            getUsernameConfigKey(appId),
+            binding.username
+        ]);
+    }
+    function getCleanGitRemoteUrl(appId, anvilUrl) {
+        const normalized = normalizeAnvilUrl(anvilUrl);
+        const url = new URL(normalized);
+        return `${url.protocol}//${url.host}/git/${appId}.git`;
+    }
+    async function configureCredentialHelperForUrl(repoPath, anvilUrl) {
+        const normalized = normalizeAnvilUrl(anvilUrl);
+        const url = new URL(normalized);
+        const scope = `${url.protocol}//${url.host}`;
+        const git = esm_default(repoPath);
+        try {
+            await git.raw([
+                "config",
+                "--local",
+                "--unset-all",
+                `credential.${scope}.helper`
+            ]);
+        } catch  {}
+        await git.raw([
+            "config",
+            "--local",
+            "--add",
+            `credential.${scope}.helper`,
+            ""
+        ]);
+        await git.raw([
+            "config",
+            "--local",
+            "--add",
+            `credential.${scope}.helper`,
+            "!anvil git-credential"
+        ]);
+        await git.raw([
+            "config",
+            "--local",
+            `credential.${scope}.useHttpPath`,
+            "true"
+        ]);
+        await git.raw([
+            "config",
+            "--local",
+            `credential.${scope}.username`,
+            "git"
+        ]);
+    }
+    async function hardenCheckoutGitAuth(options) {
+        const { repoPath, appId, anvilUrl, username } = options;
+        const remoteName = options.remoteName || "origin";
+        const cleanRemoteUrl = getCleanGitRemoteUrl(appId, anvilUrl);
+        const git = esm_default(repoPath);
+        await git.raw([
+            "remote",
+            "set-url",
+            remoteName,
+            cleanRemoteUrl
+        ]);
+        await configureCredentialHelperForUrl(repoPath, anvilUrl);
+        await setAppAuthBinding(repoPath, appId, {
+            url: anvilUrl,
+            username
+        });
+        return {
+            cleanRemoteUrl
+        };
+    }
+    function parseAppIdFromGitPath(pathValue) {
+        if (!pathValue) return;
+        const normalizedPath = pathValue.startsWith("/") ? pathValue : `/${pathValue}`;
+        const match = normalizedPath.match(/\/git\/([A-Z0-9]+)\.git(?:$|\/)/);
+        return match ? match[1] : void 0;
+    }
     function decideFallbackUrl(explicitUrl, availableUrls = getAvailableAnvilUrls()) {
         if (explicitUrl) return {
             source: "explicit",
@@ -50546,14 +50707,24 @@ var __webpack_exports__ = {};
             let anvilUrl;
             let username = explicitUsername;
             let fallbackUrl;
+            let shouldPersistUsernameBinding = false;
             if (explicitAppId) {
                 finalAppId = explicitAppId;
+                const binding = await getAppAuthBinding(repoPath, explicitAppId);
+                if (binding.url && !explicitUrl) {
+                    anvilUrl = normalizeAnvilUrl(binding.url);
+                    logger_logger.verbose(chalk_source.cyan("Resolved URL from binding for app ID: ") + chalk_source.bold(anvilUrl));
+                }
+                if (binding.username && !explicitUsername) {
+                    username = binding.username;
+                    logger_logger.verbose(chalk_source.cyan("Resolved username from binding for app ID: ") + chalk_source.bold(username));
+                }
                 const remoteInfo = lookupRemoteInfoForAppId(explicitAppId, detectedFromAllRemotes);
-                if (remoteInfo.detectedUrl && !explicitUrl) {
+                if (remoteInfo.detectedUrl && !explicitUrl && !anvilUrl) {
                     anvilUrl = normalizeAnvilUrl(remoteInfo.detectedUrl);
                     logger_logger.verbose(chalk_source.cyan("Resolved URL from remote for app ID: ") + chalk_source.bold(anvilUrl));
                 }
-                if (remoteInfo.detectedUsername && !explicitUsername) {
+                if (remoteInfo.detectedUsername && !explicitUsername && !username) {
                     username = remoteInfo.detectedUsername;
                     logger_logger.verbose(chalk_source.cyan("Resolved username from remote for app ID: ") + chalk_source.bold(username));
                 }
@@ -50608,6 +50779,16 @@ var __webpack_exports__ = {};
                     if (selected.detectedUsername && !username) username = selected.detectedUsername;
                 }
             }
+            const binding = await getAppAuthBinding(repoPath, finalAppId);
+            if (binding.url && !explicitUrl) {
+                anvilUrl = normalizeAnvilUrl(binding.url);
+                logger_logger.verbose(chalk_source.cyan("Using app binding URL: ") + chalk_source.bold(anvilUrl));
+            }
+            if (binding.username && !explicitUsername) {
+                username = binding.username;
+                logger_logger.verbose(chalk_source.cyan("Using app binding username: ") + chalk_source.bold(username));
+            }
+            shouldPersistUsernameBinding = !binding.username && !explicitUsername;
             if (explicitUrl) anvilUrl = normalizeAnvilUrl(explicitUrl);
             else if (!anvilUrl) if (fallbackUrl) anvilUrl = fallbackUrl;
             else {
@@ -50627,6 +50808,13 @@ var __webpack_exports__ = {};
                 process.exit(0);
             }
             username = resolvedUsername;
+            if (shouldPersistUsernameBinding && username && auth_getAccountsForUrl(anvilUrl).length > 1) {
+                await setAppAuthBinding(repoPath, finalAppId, {
+                    url: anvilUrl,
+                    username
+                });
+                logger_logger.verbose(chalk_source.cyan("Saved app account binding for future non-interactive use."));
+            }
             if (username) logger_logger.verbose(chalk_source.cyan("Using account: ") + chalk_source.bold(username));
             if (!hasTokensForUrl(anvilUrl, username)) {
                 if (username) logger_logger.error(`Not logged in to ${anvilUrl} as ${username}`);
@@ -50685,7 +50873,6 @@ var __webpack_exports__ = {};
         });
         return watchCommand;
     }
-    var external_http_ = __webpack_require__("http");
     const external_node_url_namespaceObject = require("node:url");
     var external_node_child_process_ = __webpack_require__("node:child_process");
     let isDockerCached;
@@ -51148,6 +51335,7 @@ var __webpack_exports__ = {};
     defineLazyProperty(open_apps, 'browser', ()=>'browser');
     defineLazyProperty(open_apps, 'browserPrivate', ()=>'browserPrivate');
     const node_modules_open = open_open;
+    var external_http_ = __webpack_require__("http");
     const successPage = `<!DOCTYPE html>
   <html lang="en">
     <head>
@@ -51305,6 +51493,9 @@ var __webpack_exports__ = {};
     </body>
   </html>`;
     }
+    function oauth_login_base64url(buf) {
+        return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+    }
     async function waitForOAuthWithPrompt(authUrl, oauthPromise) {
         const rl = external_readline_namespaceObject.createInterface({
             input: process.stdin,
@@ -51329,8 +51520,382 @@ var __webpack_exports__ = {};
         process.stdout.write("\r" + " ".repeat(60) + "\r");
         return result.oauth;
     }
-    function login_base64url(buf) {
-        return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+    async function runInteractiveLoginFlow(anvilUrl) {
+        const codeVerifier = external_crypto_.randomBytes(48).toString("hex");
+        const codeChallenge = oauth_login_base64url(external_crypto_.createHash("sha256").update(codeVerifier, "ascii").digest());
+        const state = external_crypto_.randomBytes(16).toString("hex");
+        const server = external_http_.createServer();
+        await new Promise((resolve)=>server.listen(0, "127.0.0.1", resolve));
+        const address = server.address();
+        if (!address || "string" == typeof address) throw new Error("No address");
+        const port = address.port;
+        const redirectUri = `http://127.0.0.1:${port}/oauth-callback`;
+        const SCOPES = "apps:read apps:write user:read";
+        const authUrl = new URL(`${anvilUrl}/oauth/authorize`);
+        authUrl.searchParams.set("response_type", "code");
+        authUrl.searchParams.set("client_id", "anvil-sync");
+        authUrl.searchParams.set("redirect_uri", redirectUri);
+        authUrl.searchParams.set("scope", SCOPES);
+        authUrl.searchParams.set("state", state);
+        authUrl.searchParams.set("code_challenge", codeChallenge);
+        authUrl.searchParams.set("code_challenge_method", "S256");
+        const codePromise = new Promise((resolve, reject)=>{
+            server.on("request", (req, res)=>{
+                if (!req.url) return;
+                const url = new URL(req.url, `http://127.0.0.1:${port}`);
+                if ("/oauth-callback" !== url.pathname) return;
+                const code = url.searchParams.get("code") || void 0;
+                const error = url.searchParams.get("error") || void 0;
+                const recvState = url.searchParams.get("state");
+                if (!recvState || !code && !error) {
+                    res.statusCode = 400;
+                    res.end("Missing code, error or state");
+                    reject(new Error("Missing code/state/error"));
+                    server.close();
+                    return;
+                }
+                res.statusCode = 200;
+                res.setHeader("Content-Type", "text/html; charset=utf-8");
+                if (code) res.end(successPage);
+                else res.end(errorPage(error || "unknown"));
+                resolve({
+                    code,
+                    error,
+                    recvState
+                });
+                server.closeAllConnections();
+                server.close();
+            });
+        });
+        logger_logger.info(chalk_source.blue("Link to your Anvil account to continue."));
+        console.log();
+        logger_logger.info(chalk_source.gray(`   ${authUrl}`));
+        console.log();
+        const { code, error, recvState } = await waitForOAuthWithPrompt(authUrl, codePromise);
+        if (recvState !== state) throw new Error("Invalid state received from OAuth callback");
+        if (error) throw new Error(`Error received from OAuth callback: ${error}`);
+        const tokenResponse = await fetch(`${anvilUrl}/oauth/token`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded"
+            },
+            body: new URLSearchParams({
+                grant_type: "authorization_code",
+                code: code,
+                redirect_uri: redirectUri,
+                client_id: "anvil-sync",
+                code_verifier: codeVerifier
+            })
+        });
+        if (!tokenResponse.ok) {
+            const errorText = await tokenResponse.text();
+            throw new Error(`Failed to exchange authorization code for token. ${errorText}`);
+        }
+        const tokenData = await tokenResponse.json();
+        return login(anvilUrl, {
+            access_token: tokenData.access_token,
+            refresh_token: tokenData.refresh_token,
+            expires_in: tokenData.expires_in,
+            scope: tokenData.scope
+        });
+    }
+    const defaultCheckoutDeps = {
+        getValidAuthToken: auth_getValidAuthToken,
+        validateAppId: validateAppId,
+        runInteractiveLoginFlow: runInteractiveLoginFlow,
+        clone: async (repoUrl, destinationPath, options)=>{
+            const cloneArgs = [];
+            if (options?.branch) cloneArgs.push("--branch", options.branch);
+            if ("number" == typeof options?.depth) cloneArgs.push("--depth", String(options.depth));
+            if (options?.singleBranch) cloneArgs.push("--single-branch");
+            if (options?.origin) cloneArgs.push("--origin", options.origin);
+            if (options?.quiet) cloneArgs.push("--quiet");
+            if (options?.verbose) cloneArgs.push("--verbose");
+            await esm_default().clone(repoUrl, destinationPath, cloneArgs);
+        },
+        hardenCheckoutGitAuth: hardenCheckoutGitAuth
+    };
+    function parseCheckoutInput(input) {
+        const trimmed = input.trim();
+        if (!trimmed) throw new Error("Input is required.");
+        if (/^[A-Z0-9]+$/.test(trimmed)) return {
+            appId: trimmed
+        };
+        const asUrl = /^https?:\/\//.test(trimmed) ? trimmed : normalizeAnvilUrl(trimmed);
+        let parsed;
+        try {
+            parsed = new URL(asUrl);
+        } catch  {
+            throw new Error("Input must be an editor URL, /git URL, or bare app ID.");
+        }
+        const gitMatch = parsed.pathname.match(/\/git\/([A-Z0-9]+)\.git(?:$|\/)/);
+        if (gitMatch) return {
+            appId: gitMatch[1],
+            detectedUrl: `${parsed.protocol}//${parsed.host}`
+        };
+        const appsMatch = parsed.pathname.match(/\/apps\/([A-Z0-9]+)(?:\/|$)/);
+        if (appsMatch) return {
+            appId: appsMatch[1],
+            detectedUrl: `${parsed.protocol}//${parsed.host}`
+        };
+        throw new Error("Could not extract app ID. Expected URL path containing /apps/<APPID> or /git/<APPID>.git.");
+    }
+    function sanitizeDirectoryName(name) {
+        return name.trim().replace(/\s+/g, "_").replace(/[^a-zA-Z0-9._-]+/g, "_").replace(/_+/g, "_").replace(/^_+|_+$/g, "");
+    }
+    function formatPathForDisplay(destinationPath) {
+        const relative = external_path_default().relative(process.cwd(), destinationPath);
+        if ("" === relative) return ".";
+        if (relative.startsWith("..")) return destinationPath;
+        return relative.startsWith(".") ? relative : `./${relative}`;
+    }
+    function getDefaultDestinationDirectory(appId, appName) {
+        if (appName) {
+            const sanitized = sanitizeDirectoryName(appName);
+            if (sanitized) return sanitized;
+        }
+        return appId;
+    }
+    async function resolveCheckoutUrl(explicitUrl, parsedUrl) {
+        if (explicitUrl) return normalizeAnvilUrl(explicitUrl);
+        if (parsedUrl) return normalizeAnvilUrl(parsedUrl);
+        const decision = decideFallbackUrl(void 0);
+        if ("available-multiple" !== decision.source) return decision.url;
+        const choices = decision.urls.map((url)=>({
+                name: url,
+                value: url
+            }));
+        choices.push({
+            name: "Cancel",
+            value: null
+        });
+        return logger_logger.select("Multiple logged-in Anvil URLs found. Which one would you like to use?", choices, decision.urls[0]);
+    }
+    async function isPathInsideGitRepo(targetPath) {
+        const resolved = external_path_default().resolve(targetPath);
+        let current = resolved;
+        while(!external_fs_.existsSync(current)){
+            const parent = external_path_default().dirname(current);
+            if (parent === current) return false;
+            current = parent;
+        }
+        try {
+            const output = (await esm_default(current).raw([
+                "rev-parse",
+                "--is-inside-work-tree"
+            ])).trim();
+            return "true" === output;
+        } catch  {
+            return false;
+        }
+    }
+    async function isDirectoryNonEmpty(destinationPath) {
+        if (!external_fs_.existsSync(destinationPath)) return false;
+        const stats = await external_fs_.promises.stat(destinationPath);
+        if (!stats.isDirectory()) return true;
+        const entries = await external_fs_.promises.readdir(destinationPath);
+        return entries.length > 0;
+    }
+    async function validateCheckoutDestination(destinationPath, force = false) {
+        const nonEmpty = await isDirectoryNonEmpty(destinationPath);
+        if (nonEmpty && !force) throw new Error(`Destination '${destinationPath}' already exists and is not empty.`);
+        const insideGit = await isPathInsideGitRepo(destinationPath);
+        if (insideGit && !force) throw new Error(`Destination '${destinationPath}' is inside an existing Git repository.`);
+        if (force && nonEmpty) logger_logger.warn(`--force set: destination '${destinationPath}' is non-empty and clone may still fail.`);
+        if (force && insideGit) logger_logger.warn("--force set: cloning inside an existing Git repository.");
+    }
+    async function ensureCheckoutAuthToken(anvilUrl, username, deps = defaultCheckoutDeps) {
+        try {
+            return await deps.getValidAuthToken(anvilUrl, username);
+        } catch (e) {
+            const interactive = process.stdin.isTTY && process.stdout.isTTY;
+            if (!interactive) throw errors_createAuthError.required(`Not logged in to ${anvilUrl}. Run 'anvil login ${anvilUrl}' and retry.`);
+            const shouldLogin = await logger_logger.confirm(`Not logged in to ${anvilUrl}. Log in now?`, true);
+            if (!shouldLogin) throw errors_createAuthError.required(`Not logged in to ${anvilUrl}. Run 'anvil login ${anvilUrl}' and retry.`);
+            await deps.runInteractiveLoginFlow(anvilUrl);
+            return deps.getValidAuthToken(anvilUrl, username);
+        }
+    }
+    async function resolveCheckoutUsername(anvilUrl, explicitUsername, getAccounts = auth_getAccountsForUrl) {
+        if (explicitUsername) return explicitUsername;
+        const accounts = getAccounts(anvilUrl);
+        if (0 === accounts.length) return;
+        if (1 === accounts.length) {
+            logger_logger.verbose(chalk_source.cyan("Auto-selected account: ") + chalk_source.bold(accounts[0]));
+            return accounts[0];
+        }
+        const interactive = process.stdin.isTTY && process.stdout.isTTY;
+        if (!interactive) throw new Error(`Multiple accounts found for ${anvilUrl}. Use --user <USERNAME> to choose one.`);
+        const choices = accounts.map((acct)=>({
+                name: acct,
+                value: acct
+            }));
+        choices.push({
+            name: "Cancel",
+            value: null
+        });
+        return logger_logger.select(`Multiple accounts found for ${anvilUrl}. Which account should be used for checkout?`, choices, accounts[0]);
+    }
+    async function executeCheckout(options, deps = defaultCheckoutDeps) {
+        const parsed = parseCheckoutInput(options.input);
+        const anvilUrl = await resolveCheckoutUrl(options.url, parsed.detectedUrl);
+        if (!anvilUrl) return void logger_logger.info("Checkout cancelled.");
+        const resolvedUsername = await resolveCheckoutUsername(anvilUrl, options.user);
+        if (null === resolvedUsername) return void logger_logger.info("Checkout cancelled.");
+        const authToken = await ensureCheckoutAuthToken(anvilUrl, resolvedUsername, deps);
+        let checkoutUsername = resolvedUsername;
+        if (!checkoutUsername) {
+            const inferredUsername = await resolveCheckoutUsername(anvilUrl, void 0);
+            if (null === inferredUsername) return void logger_logger.info("Checkout cancelled.");
+            if (!inferredUsername) throw new Error(`Could not determine account for ${anvilUrl}. Use --user <USERNAME> so checkout can bind repository credentials.`);
+            checkoutUsername = inferredUsername;
+        }
+        const validation = await deps.validateAppId(parsed.appId, anvilUrl, checkoutUsername);
+        if (!validation.valid) throw new Error(validation.error || `App '${parsed.appId}' is not accessible on ${anvilUrl}.`);
+        const destinationDir = options.directory || getDefaultDestinationDirectory(parsed.appId, validation.app_name);
+        const destinationPath = external_path_default().resolve(process.cwd(), destinationDir);
+        const destinationDisplay = formatPathForDisplay(destinationPath);
+        await validateCheckoutDestination(destinationPath, options.force);
+        const cloneUrl = getGitPushUrl(parsed.appId, authToken, anvilUrl);
+        logger_logger.progress("checkout", `Checking out app ${parsed.appId} from ${anvilUrl}`);
+        logger_logger.info(chalk_source.gray(`   Destination directory: ${destinationDisplay}`));
+        await deps.clone(cloneUrl, destinationPath, {
+            branch: options.branch,
+            depth: options.depth,
+            singleBranch: options.singleBranch,
+            origin: options.origin,
+            quiet: options.quiet,
+            verbose: options.verbose
+        });
+        const remoteName = options.origin || "origin";
+        try {
+            await deps.hardenCheckoutGitAuth({
+                repoPath: destinationPath,
+                appId: parsed.appId,
+                anvilUrl,
+                username: checkoutUsername,
+                remoteName
+            });
+        } catch (e) {
+            throw new Error(`Checkout clone succeeded, but failed to configure repository credentials: ${errors_getErrorMessage(e)}. The repository exists at ${destinationDisplay}, but Git auth bridge setup is incomplete.`);
+        }
+        logger_logger.progressEnd("checkout", `Checked out ${parsed.appId} into ${destinationDisplay}`);
+        const preferredEditor = String(getConfig("preferredEditor") || "").trim();
+        const preferredEditorCommand = preferredEditor ? getPreferredEditorCommand(preferredEditor) : "";
+        if (options.open) if (preferredEditorCommand) await openInPreferredEditor(preferredEditorCommand, destinationPath);
+        else {
+            await node_modules_open(destinationPath);
+            logger_logger.info(chalk_source.gray(`Opened ${destinationDisplay}`));
+        }
+        if (preferredEditorCommand && !options.open) logger_logger.info(chalk_source.cyan(`Next: ${preferredEditorCommand} ${destinationDisplay}`));
+    }
+    async function openInPreferredEditor(editorCommand, destinationPath) {
+        await new Promise((resolve, reject)=>{
+            const child = (0, external_child_process_.spawn)(editorCommand, [
+                destinationPath
+            ], {
+                shell: true,
+                stdio: "inherit"
+            });
+            child.on("error", reject);
+            child.on("exit", (code)=>{
+                if (0 === code || null === code) resolve();
+                else reject(new Error(`Editor command '${editorCommand}' exited with code ${code}`));
+            });
+        });
+    }
+    function registerCheckoutCommand(program) {
+        const checkoutCommand = program.command("checkout <input> [directory]").description("Check out an Anvil app locally from editor URL, git URL, or app ID").alias("co").option("-O, --open", "Open destination after checkout").option("-b, --branch <BRANCH>", "Checkout a specific branch").option("--depth <N>", "Create a shallow clone with history truncated to N commits", (value)=>parseInt(value, 10)).option("--single-branch", "Clone only one branch").option("--origin <NAME>", "Use a custom remote name instead of origin").option("-q, --quiet", "Suppress git clone progress output").option("--verbose", "Enable verbose git clone output").option("-u, --url <ANVIL_URL>", "Specify Anvil server URL").option("-U, --user <USERNAME>", "Specify which user account to use").option("-f, --force", "Override safety checks for destination path").action(async (input, directory, options)=>{
+            try {
+                if ("number" == typeof options?.depth && (!Number.isFinite(options.depth) || options.depth <= 0)) throw new Error("--depth must be a positive integer");
+                await executeCheckout({
+                    input,
+                    directory,
+                    open: options?.open,
+                    branch: options?.branch,
+                    depth: options?.depth,
+                    singleBranch: options?.singleBranch,
+                    origin: options?.origin,
+                    quiet: options?.quiet,
+                    verbose: options?.verbose,
+                    url: options?.url,
+                    user: options?.user,
+                    force: options?.force
+                }, defaultCheckoutDeps);
+            } catch (e) {
+                logger_logger.error("Error: " + errors_getErrorMessage(e));
+                process.exit(1);
+            }
+        });
+        checkoutCommand.addHelpText("after", "\n" + chalk_source.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");
+    }
+    const defaultDeps = {
+        getValidAuthToken: auth_getValidAuthToken,
+        getAccountsForUrl: auth_getAccountsForUrl,
+        getAppAuthBinding: getAppAuthBinding,
+        cwd: ()=>process.cwd()
+    };
+    function parseGitCredentialRequest(rawInput) {
+        const out = {};
+        const lines = rawInput.split(/\r?\n/);
+        for (const line of lines){
+            if (!line) continue;
+            const eqIdx = line.indexOf("=");
+            if (eqIdx <= 0) continue;
+            const key = line.slice(0, eqIdx);
+            const value = line.slice(eqIdx + 1);
+            if ("protocol" === key || "host" === key || "path" === key || "username" === key) out[key] = value;
+        }
+        return out;
+    }
+    async function buildGitCredentialResponse(operation, request, deps = defaultDeps) {
+        if ("get" !== operation) return null;
+        if (!request.protocol || !request.host) return null;
+        const appId = parseAppIdFromGitPath(request.path);
+        if (!appId) return null;
+        const requestUrl = normalizeAnvilUrl(`${request.protocol}://${request.host}`);
+        const binding = await deps.getAppAuthBinding(deps.cwd(), appId);
+        const anvilUrl = binding.url ? normalizeAnvilUrl(binding.url) : requestUrl;
+        let username = binding.username;
+        if (!username) {
+            const accounts = deps.getAccountsForUrl(anvilUrl);
+            if (1 === accounts.length) username = accounts[0];
+            else if (accounts.length > 1) throw new Error(`Multiple accounts found for ${anvilUrl}; bind one with anvil checkout --user.`);
+            else throw new Error(`No account found for ${anvilUrl}. Run 'anvil login ${anvilUrl}'.`);
+        }
+        const token = await deps.getValidAuthToken(anvilUrl, username);
+        return {
+            username: "git",
+            password: token
+        };
+    }
+    async function readStdin() {
+        const chunks = [];
+        for await (const chunk of process.stdin)chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+        return Buffer.concat(chunks).toString("utf8");
+    }
+    function writeGitCredentialResponse(response) {
+        if (!response) return;
+        const lines = [];
+        for (const [k, v] of Object.entries(response))lines.push(`${k}=${v}`);
+        process.stdout.write(lines.join("\n") + "\n\n");
+    }
+    async function executeGitCredentialOperation(operation, deps = defaultDeps) {
+        const raw = await readStdin();
+        const request = parseGitCredentialRequest(raw);
+        const response = await buildGitCredentialResponse(operation, request, deps);
+        writeGitCredentialResponse(response);
+    }
+    function registerGitCredentialCommand(program) {
+        program.command("git-credential <operation>", {
+            hidden: true
+        }).description("Internal helper command for Git HTTPS authentication").action(async (operation)=>{
+            try {
+                await executeGitCredentialOperation(operation);
+            } catch  {
+                process.exit(1);
+            }
+        });
     }
     function registerLoginCommand(program) {
         const loginCommand = program.command("login [anvil-server-url]").description("Log in to Anvil using OAuth").alias("l").action(async (anvilUrl)=>{
@@ -51339,93 +51904,8 @@ var __webpack_exports__ = {};
                     anvilUrl = normalizeAnvilUrl(anvilUrl.trim());
                     setConfig("anvilUrl", anvilUrl);
                 } else anvilUrl = resolveAnvilUrl();
-                const codeVerifier = external_crypto_.randomBytes(48).toString("hex");
-                const codeChallenge = login_base64url(external_crypto_.createHash("sha256").update(codeVerifier, "ascii").digest());
-                const state = external_crypto_.randomBytes(16).toString("hex");
-                const server = external_http_.createServer();
-                await new Promise((resolve)=>server.listen(0, "127.0.0.1", resolve));
-                const address = server.address();
-                if (!address || "string" == typeof address) throw new Error("No address");
-                const port = address.port;
-                const redirectUri = `http://127.0.0.1:${port}/oauth-callback`;
-                const SCOPES = "apps:read apps:write user:read";
-                const authUrl = new URL(`${anvilUrl}/oauth/authorize`);
-                authUrl.searchParams.set("response_type", "code");
-                authUrl.searchParams.set("client_id", "anvil-sync");
-                authUrl.searchParams.set("redirect_uri", redirectUri);
-                authUrl.searchParams.set("scope", SCOPES);
-                authUrl.searchParams.set("state", state);
-                authUrl.searchParams.set("code_challenge", codeChallenge);
-                authUrl.searchParams.set("code_challenge_method", "S256");
-                const codePromise = new Promise((resolve, reject)=>{
-                    server.on("request", (req, res)=>{
-                        if (!req.url) return;
-                        const url = new URL(req.url, `http://127.0.0.1:${port}`);
-                        if ("/oauth-callback" !== url.pathname) return;
-                        const code = url.searchParams.get("code") || void 0;
-                        const error = url.searchParams.get("error") || void 0;
-                        const recvState = url.searchParams.get("state");
-                        if (!recvState || !code && !error) {
-                            res.statusCode = 400;
-                            res.end("Missing code, error or state");
-                            reject(new Error("Missing code/state/error"));
-                            server.close();
-                            return;
-                        }
-                        res.statusCode = 200;
-                        res.setHeader("Content-Type", "text/html; charset=utf-8");
-                        if (code) res.end(successPage);
-                        else res.end(errorPage(error || "unknown"));
-                        resolve({
-                            code,
-                            error,
-                            recvState
-                        });
-                        server.closeAllConnections();
-                        server.close();
-                    });
-                });
-                logger_logger.info(chalk_source.blue("Link to your Anvil account to continue."));
-                console.log();
-                logger_logger.info(chalk_source.gray(`   ${authUrl}`));
-                console.log();
-                const { code, error, recvState } = await waitForOAuthWithPrompt(authUrl, codePromise);
-                if (recvState !== state) {
-                    logger_logger.error("Invalid state received from OAuth callback");
-                    process.exit(1);
-                }
-                if (error) {
-                    logger_logger.error(`Error received from OAuth callback: ${error}`);
-                    process.exit(1);
-                }
-                const tokenResponse = await fetch(`${anvilUrl}/oauth/token`, {
-                    method: "POST",
-                    headers: {
-                        "Content-Type": "application/x-www-form-urlencoded"
-                    },
-                    body: new URLSearchParams({
-                        grant_type: "authorization_code",
-                        code: code,
-                        redirect_uri: redirectUri,
-                        client_id: "anvil-sync",
-                        code_verifier: codeVerifier
-                    })
-                });
-                if (tokenResponse.ok) {
-                    const tokenData = await tokenResponse.json();
-                    const result = await login(anvilUrl, {
-                        access_token: tokenData.access_token,
-                        refresh_token: tokenData.refresh_token,
-                        expires_in: tokenData.expires_in,
-                        scope: tokenData.scope
-                    });
-                    logger_logger.success("Logged in as " + chalk_source.bold(result.email));
-                } else {
-                    logger_logger.error("Failed to exchange authorization code for token.");
-                    const errorText = await tokenResponse.text();
-                    logger_logger.error(`   Server response: ${errorText}`);
-                    process.exit(1);
-                }
+                const result = await runInteractiveLoginFlow(anvilUrl);
+                logger_logger.success("Logged in as " + chalk_source.bold(result.email));
             } catch (e) {
                 logger_logger.error("Error: " + e.message);
                 process.exit(1);
@@ -51529,6 +52009,14 @@ var __webpack_exports__ = {};
         });
         logoutCommand.addHelpText("after", "\n" + chalk_source.bold("Examples:") + "\n  anvil logout                    Logout from all accounts (or prompt if multiple)\n  anvil logout anvil.works        Logout from anvil.works\n  anvil logout -u anvil.works     Logout from anvil.works (using option)\n  anvil logout -u anvil.works -U user@example.com  Logout specific user\n");
     }
+    const defaultConfigResetDeps = {
+        logout: logout,
+        resetConfig: resetConfig
+    };
+    async function performConfigReset(deps = defaultConfigResetDeps) {
+        await deps.logout();
+        deps.resetConfig();
+    }
     function registerConfigCommand(program) {
         const configCommand = program.command("config").description("Manage configuration").alias("c");
         configCommand.command("get <key>").description("Get a configuration value").action(async (key)=>{
@@ -51547,8 +52035,7 @@ var __webpack_exports__ = {};
         });
         configCommand.command("set <key> <value>").description("Set a configuration value").action(async (key, value)=>{
             try {
-                let typedValue = coerceConfigValue(key, value);
-                if ("anvilUrl" === key && "string" == typeof typedValue) typedValue = typedValue.trim().replace(/\/+$/, "");
+                const typedValue = parseConfigSetValue(key, value);
                 setConfig(key, typedValue);
                 logger_logger.success(`Set ${key} = ${typedValue}`);
             } catch (error) {
@@ -51608,7 +52095,7 @@ var __webpack_exports__ = {};
         });
         configCommand.command("reset").description("Reset configuration to defaults").action(async ()=>{
             try {
-                resetConfig();
+                await performConfigReset();
                 logger_logger.success("Configuration reset to defaults.");
             } catch (e) {
                 logger_logger.error("Error: " + e.message);
@@ -51624,6 +52111,136 @@ var __webpack_exports__ = {};
             console.log();
         });
     }
+    const onboard_defaultDeps = {
+        getLatestVersion: getLatestVersion,
+        getAccountsForUrl: auth_getAccountsForUrl,
+        runInteractiveLoginFlow: runInteractiveLoginFlow,
+        executeCheckout: executeCheckout
+    };
+    const DEFAULT_ANVIL_SERVER_URL_PROMPT = "Default Anvil server URL";
+    async function getOnboardVersionStatus(currentVersion, latestVersionGetter = getLatestVersion) {
+        const latestVersion = await latestVersionGetter();
+        if (!latestVersion) return {
+            currentVersion,
+            latestVersion: null,
+            isOutdated: null
+        };
+        if (!semver_default().valid(currentVersion) || !semver_default().valid(latestVersion)) return {
+            currentVersion,
+            latestVersion,
+            isOutdated: null
+        };
+        return {
+            currentVersion,
+            latestVersion,
+            isOutdated: semver_default().lt(currentVersion, latestVersion)
+        };
+    }
+    function formatLoggedInAccounts(accounts) {
+        if (0 === accounts.length) return "no account";
+        if (1 === accounts.length) return accounts[0];
+        return `${accounts.length} accounts`;
+    }
+    function isInteractiveSession() {
+        return !!(process.stdin.isTTY && process.stdout.isTTY);
+    }
+    async function runOnboardFlow(version, deps = onboard_defaultDeps) {
+        if (!isInteractiveSession()) throw new Error("`anvil onboard` is interactive and requires a TTY terminal.");
+        console.log();
+        logger_logger.info(chalk_source.cyan.bold("Anvil Onboarding"));
+        console.log();
+        logger_logger.progress("onboard-version", "Checking CLI version...");
+        const versionStatus = await getOnboardVersionStatus(version, deps.getLatestVersion);
+        logger_logger.progressEnd("onboard-version");
+        logger_logger.info(chalk_source.cyan("CLI version: ") + chalk_source.bold(versionStatus.currentVersion));
+        if (versionStatus.latestVersion) {
+            logger_logger.info(chalk_source.cyan("Latest version: ") + chalk_source.bold(versionStatus.latestVersion));
+            if (versionStatus.isOutdated) {
+                logger_logger.warn("Your anvil-cli is out of date.");
+                logger_logger.info(chalk_source.gray("Run `anvil update` to see update commands."));
+                const continueOnOldVersion = await logger_logger.confirm("Continue onboarding anyway?", true);
+                if (!continueOnOldVersion) return void logger_logger.info("Onboarding cancelled.");
+            }
+        } else logger_logger.warn("Could not determine latest published version.");
+        console.log();
+        const currentUrl = resolveAnvilUrl();
+        logger_logger.info(chalk_source.gray("Leave this blank unless you're using a dedicated enterprise/on-prem Anvil installation."));
+        const urlAnswer = await logger_logger.prompt([
+            {
+                type: "input",
+                name: "anvilUrl",
+                message: DEFAULT_ANVIL_SERVER_URL_PROMPT,
+                default: currentUrl
+            }
+        ]);
+        const configuredAnvilUrl = parseConfigSetValue("anvilUrl", urlAnswer.anvilUrl);
+        setConfig("anvilUrl", configuredAnvilUrl);
+        logger_logger.success(`Set default Anvil server URL (anvilUrl) = ${configuredAnvilUrl}`);
+        const currentEditor = String(getConfig("preferredEditor") || "").trim().toLowerCase();
+        const editorChoices = [
+            {
+                name: "None",
+                value: ""
+            },
+            ...preferredEditors.map((editor)=>({
+                    name: editor,
+                    value: editor
+                }))
+        ];
+        const selectedEditor = await logger_logger.select("Preferred editor", editorChoices, editorChoices.some((choice)=>choice.value === currentEditor) ? currentEditor : "");
+        setConfig("preferredEditor", selectedEditor);
+        if (selectedEditor) logger_logger.success(`Set preferredEditor = ${selectedEditor}`);
+        else logger_logger.info("Left preferredEditor unset.");
+        const currentVerbose = !!getConfig("verbose");
+        const enableVerbose = await logger_logger.confirm("Enable verbose logging?", currentVerbose);
+        setConfig("verbose", enableVerbose);
+        logger_logger.success(`Set verbose = ${enableVerbose}`);
+        console.log();
+        const existingAccounts = deps.getAccountsForUrl(configuredAnvilUrl);
+        if (existingAccounts.length > 0) logger_logger.success(`Already logged in to ${configuredAnvilUrl} as ${formatLoggedInAccounts(existingAccounts)}.`);
+        else {
+            const shouldLogin = await logger_logger.confirm(`You're not logged in to ${configuredAnvilUrl}. Log in now?`, true);
+            if (shouldLogin) {
+                const loginResult = await deps.runInteractiveLoginFlow(configuredAnvilUrl);
+                logger_logger.success("Logged in as " + chalk_source.bold(loginResult.email));
+            } else logger_logger.warn("Skipping login.");
+        }
+        console.log();
+        const shouldCheckout = await logger_logger.confirm("Check out an app now?", true);
+        if (shouldCheckout) {
+            const checkoutAnswer = await logger_logger.prompt([
+                {
+                    type: "input",
+                    name: "input",
+                    message: "App ID or app URL to checkout"
+                }
+            ]);
+            const checkoutInput = checkoutAnswer.input.trim();
+            if (checkoutInput) {
+                const preferredEditorCommand = getPreferredEditorCommand(selectedEditor);
+                let openAfterCheckout = false;
+                if (preferredEditorCommand) openAfterCheckout = await logger_logger.confirm(`Open checked out app in ${preferredEditorCommand} after checkout?`, true);
+                else logger_logger.info("No preferred editor is configured, so open-in-editor is skipped.");
+                await deps.executeCheckout({
+                    input: checkoutInput,
+                    url: configuredAnvilUrl,
+                    open: openAfterCheckout
+                });
+            } else logger_logger.info("No app provided; skipping checkout.");
+        } else logger_logger.info("Skipping checkout.");
+        console.log();
+        logger_logger.success("Onboarding complete.");
+    }
+    function registerOnboardCommand(program, version) {
+        program.command("onboard").description("Guided setup for configuration, login, and optional app checkout").action(async ()=>{
+            try {
+                await runOnboardFlow(version, onboard_defaultDeps);
+            } catch (e) {
+                logger_logger.error("Error: " + errors_getErrorMessage(e));
+                process.exit(1);
+            }
+        });
+    }
     const packageJson = JSON.parse((0, external_fs_.readFileSync)((0, external_path_namespaceObject.join)(__dirname, "../package.json"), "utf-8"));
     const VERSION = packageJson.version;
     setLogger(new CLILogger({
@@ -51670,9 +52287,12 @@ var __webpack_exports__ = {};
             console.log();
             console.log(chalk_source.cyan("To update, run one of the following commands:"));
             console.log();
-            console.log(chalk_source.gray("  npm:   ") + chalk_source.white("npm update -g @anvil-works/anvil-cli"));
-            console.log(chalk_source.gray("  pnpm:  ") + chalk_source.white("pnpm update -g @anvil-works/anvil-cli"));
-            console.log(chalk_source.gray("  yarn:  ") + chalk_source.white("yarn global upgrade @anvil-works/anvil-cli"));
+            if ("win32" === process.platform) {
+                console.log(chalk_source.gray("  PowerShell: ") + chalk_source.white("irm https://anvil.works/install/anvil-cli/install.ps1 | iex"));
+                console.log(chalk_source.gray("  CMD:        ") + chalk_source.white("curl -fsSL https://anvil.works/install/anvil-cli/install.cmd -o install.cmd && install.cmd && del install.cmd"));
+            } else console.log(chalk_source.gray("  macOS/Linux: ") + chalk_source.white("curl -fsSL https://anvil.works/install/anvil-cli/install.sh | sh"));
+            console.log(chalk_source.gray("  npm:         ") + chalk_source.white("npm update -g @anvil-works/anvil-cli"));
+            console.log(chalk_source.gray("  pnpm:        ") + chalk_source.white("pnpm update -g @anvil-works/anvil-cli"));
             console.log();
         } catch (e) {
             logger_logger.error("Error: " + e.message);
@@ -51687,14 +52307,17 @@ var __webpack_exports__ = {};
         });
         if (!opts.json) {
             const commandName = actionCommand?.name();
-            if ("update" !== commandName) checkVersionAndWarn();
+            if ("update" !== commandName && "git-credential" !== commandName) checkVersionAndWarn();
         }
     });
     const cli_watchCommand = registerWatchCommand(cli_program);
+    registerCheckoutCommand(cli_program);
+    registerGitCredentialCommand(cli_program);
     registerLoginCommand(cli_program);
     registerLogoutCommand(cli_program);
     registerConfigCommand(cli_program);
     registerVersionCommand(cli_program, VERSION);
+    registerOnboardCommand(cli_program, VERSION);
     cli_program.command("update").description("Update anvil to the latest version").alias("u").action(async ()=>{
         await handleUpdateCommand();
     });