@xano/cli 1.2.0 → 1.3.1-beta.0

package/dist/base-command.d.ts

@@ -15,6 +15,11 @@ export interface CredentialsFile {
     };
 }
 export declare function buildUserAgent(version: string): string;
+/**
+ * True when `error` is the "foreign dispatcher rejected by built-in fetch"
+ * failure (Node 26+). The real code lives on `error.cause.code`.
+ */
+export declare function isInvalidDispatcherError(error: unknown): boolean;
 export interface SandboxTenant {
     created_at?: string;
     description?: string;
@@ -22,7 +27,7 @@ export interface SandboxTenant {
     ephemeral?: boolean;
     id: number;
     name: string;
-    sandbox_expires_at?: string | number;
+    sandbox_expires_at?: number | string;
     state?: string;
     xano_domain?: string;
 }
@@ -52,57 +57,40 @@ export default abstract class BaseCommand extends Command {
         config: LocalProfileConfig;
         path: string;
     };
-    protected updateNotice: string | null;
-    init(): Promise<void>;
-    /**
-     * Find and parse the nearest project-local profile.yaml, unless an explicit
-     * -p/XANO_PROFILE was given (in which case the local file is ignored).
-     */
-    private loadLocalProfile;
-    /** Print the one-line target banner when a local profile.yaml is in effect. */
-    private maybePrintLocalProfileBanner;
-    finally(_: Error | undefined): Promise<void>;
-    private isJsonOutput;
+    protected updateNotice: null | string;
     /**
      * Apply insecure TLS mode if the active profile has insecure: true.
      * Sets NODE_TLS_REJECT_UNAUTHORIZED=0 so all fetch() calls skip cert verification.
      */
     protected applyInsecureFromProfile(): void;
-    protected getDefaultProfile(): string;
-    protected getProfile(): string | undefined;
+    /**
+     * Report a failure as exit 1 for commands that reserve exit 2 for findings: operational errors,
+     * flag errors and oclif's own default exit 2 all become 1, and under `-o json` the failure is also
+     * written to stdout as `{"error": {"exit": 1, "message"}}`. A deliberate exit 0 passes through.
+     */
+    protected catchAsOperational(error: Error & {
+        oclif?: {
+            exit?: number;
+        };
+    }): Promise<void>;
+    finally(_: Error | undefined): Promise<void>;
     /**
      * Get the resolved credentials file path, respecting --config flag and XANO_CONFIG env var.
      * Reads -c/--config from process.argv directly because oclif doesn't set this.flags
      * from parsed results — the static flags property is the flag definition, not parsed values.
      */
     protected getCredentialsPath(): string;
-    protected loadCredentialsFile(): CredentialsFile | null;
+    protected getDefaultProfile(): string;
     /**
      * Get or create the singleton sandbox environment for the authenticated user.
      * Returns the sandbox object (existing or newly created).
      */
     protected getOrCreateSandbox(profile: ProfileConfig, verbose: boolean): Promise<SandboxTenant>;
-    /**
-     * Resolve the profile from flags and any project-local profile.yaml,
-     * validating instance_origin and access_token exist.
-     * Precedence: -p/XANO_PROFILE > profile.yaml > credentials default.
-     */
-    protected resolveProfile(flags: {
-        profile?: string;
-    }): {
-        profile: ProfileConfig;
-        profileName: string;
-    };
-    /**
-     * Parse an API error response and return a clean error message.
-     * Extracts the message from JSON responses and adds context for common errors.
-     */
-    protected parseApiError(response: Response, fallbackPrefix: string): Promise<string>;
-    /**
-     * Make an HTTP request with optional verbose logging.
-     * Use this for all Metadata API calls to support the --verbose flag.
-     */
-    protected verboseFetch(url: string, options: RequestInit, verbose: boolean, authToken?: string): Promise<Response>;
+    protected getProfile(): string | undefined;
+    init(): Promise<void>;
+    /** Raw-argv check: the parsed flags are not available yet when the banner prints. */
+    protected isJsonOutput(): boolean;
+    protected loadCredentialsFile(): CredentialsFile | null;
     /**
      * Poll a static-host build until it reaches a terminal status (ok | error),
      * showing a live, ticking spinner with the current stage and elapsed time —
@@ -117,17 +105,47 @@ export default abstract class BaseCommand extends Command {
     protected logStaticHostUrls(opts: {
         profile: ProfileConfig;
         staticHost: string;
+        tenantName?: string;
         verbose: boolean;
         workspaceId: string;
     }): Promise<void>;
+    /**
+     * Parse an API error response and return a clean error message.
+     * Extracts the message from JSON responses and adds context for common errors.
+     */
+    protected parseApiError(response: Response, fallbackPrefix: string): Promise<string>;
+    /**
+     * Resolve the profile from flags and any project-local profile.yaml,
+     * validating instance_origin and access_token exist.
+     * Precedence: -p/XANO_PROFILE > profile.yaml > credentials default.
+     */
+    protected resolveProfile(flags: {
+        profile?: string;
+    }): {
+        profile: ProfileConfig;
+        profileName: string;
+    };
+    /**
+     * Make an HTTP request with optional verbose logging.
+     * Use this for all Metadata API calls to support the --verbose flag.
+     */
+    protected verboseFetch(url: string, options: RequestInit, verbose: boolean, authToken?: string): Promise<Response>;
     protected waitForBuild(opts: {
         buildId: number | string;
         intervalMs?: number;
         profile: ProfileConfig;
         quiet?: boolean;
         staticHost: string;
+        tenantName?: string;
         timeoutMs?: number;
         verbose: boolean;
         workspaceId: string;
     }): Promise<string>;
+    /**
+     * Find and parse the nearest project-local profile.yaml, unless an explicit
+     * -p/XANO_PROFILE was given (in which case the local file is ignored).
+     */
+    private loadLocalProfile;
+    /** Print the one-line target banner when a local profile.yaml is in effect. */
+    private maybePrintLocalProfileBanner;
 }

package/dist/base-command.js

@@ -2,7 +2,7 @@ import { Command, Flags, ux } from '@oclif/core';
 import * as yaml from 'js-yaml';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
-import * as path from 'node:path';
+import path from 'node:path';
 import { Agent } from 'undici';
 import { checkForUpdate } from './update-check.js';
 import { applyLocalOverrides, findLocalProfilePath, formatLocalProfileBanner, parseLocalProfile, resolveProfileSelection, } from './utils/local-config.js';
@@ -29,13 +29,46 @@ function resolveRequestTimeoutMs(env = process.env) {
         return DEFAULT_REQUEST_TIMEOUT_MS;
     return parsed;
 }
+/**
+ * Whether the built-in `fetch` on this runtime accepts a dispatcher built from
+ * our bundled userland `undici`. Node <= 24 accepts it; Node 26 rejects a
+ * foreign dispatcher with UND_ERR_INVALID_ARG, which `fetch` surfaces only as
+ * the generic "fetch failed" — breaking *every* command (DEV-7773).
+ *
+ * Starts optimistic (`true`); flipped to `false` the first time a request fails
+ * with UND_ERR_INVALID_ARG (see `verboseFetch`, which then retries without the
+ * dispatcher). Once flipped, every later request skips the dispatcher outright.
+ */
+let dispatcherSupported = true;
+/**
+ * True when `error` is the "foreign dispatcher rejected by built-in fetch"
+ * failure (Node 26+). The real code lives on `error.cause.code`.
+ */
+export function isInvalidDispatcherError(error) {
+    if (!(error instanceof Error))
+        return false;
+    const { cause } = error;
+    const code = cause && typeof cause === 'object' && 'code' in cause
+        ? cause.code
+        : error.code;
+    return code === 'UND_ERR_INVALID_ARG';
+}
 /**
  * Lazily-built undici dispatcher whose header/body inactivity timeouts match our
  * request timeout, so undici's internal 300s default never fires first. Built
  * once and reused across requests. `timeout === 0` means "no bound".
+ *
+ * Returns `undefined` when this runtime has been found to reject a foreign
+ * dispatcher (Node 26+, DEV-7773). Dropping the dispatcher does NOT regress the
+ * large-push timeout: the per-request `AbortSignal.timeout(timeoutMs)` in
+ * `verboseFetch` already bounds the whole request (headers included) to the same
+ * 15-min ceiling the dispatcher enforced, so undici's hidden 300s
+ * `headersTimeout` is subsumed by it.
  */
 let sharedDispatcher;
 function getRequestDispatcher(timeoutMs) {
+    if (!dispatcherSupported)
+        return undefined;
     if (timeoutMs === 0) {
         sharedDispatcher ??= new Agent({ bodyTimeout: 0, headersTimeout: 0 });
         return sharedDispatcher;
@@ -103,76 +136,6 @@ export default class BaseCommand extends Command {
     // Null when none was found or when an explicit -p/XANO_PROFILE overrides it.
     localProfile = null;
     updateNotice = null;
-    async init() {
-        await super.init();
-        this.localProfile = this.loadLocalProfile();
-        this.applyInsecureFromProfile();
-        this.maybePrintLocalProfileBanner();
-        const forceUpdateCheck = process.env.XANO_FORCE_UPDATE_CHECK === '1';
-        this.updateNotice = checkForUpdate(this.config.version, forceUpdateCheck);
-    }
-    /**
-     * Find and parse the nearest project-local profile.yaml, unless an explicit
-     * -p/XANO_PROFILE was given (in which case the local file is ignored).
-     */
-    loadLocalProfile() {
-        if (argvHasProfileFlag(process.argv, process.env)) {
-            return null;
-        }
-        // Walks up to the filesystem root (git-style). parseLocalProfile returns
-        // null for a profile.yaml with no recognized keys, so an unrelated file
-        // belonging to another tool is ignored rather than hijacked.
-        const filePath = findLocalProfilePath(process.cwd());
-        if (!filePath) {
-            return null;
-        }
-        let config;
-        try {
-            config = parseLocalProfile(fs.readFileSync(filePath, 'utf8'));
-        }
-        catch (error) {
-            this.error(`${filePath}: ${error.message}`);
-        }
-        if (!config) {
-            this.warn(`Ignoring ${filePath}: no recognized profile keys found.`);
-            return null;
-        }
-        return { config, path: filePath };
-    }
-    /** Print the one-line target banner when a local profile.yaml is in effect. */
-    maybePrintLocalProfileBanner() {
-        if (!this.localProfile || this.isJsonOutput()) {
-            return;
-        }
-        // Credential-management commands (the `profile` topic) operate on the
-        // credentials store directly and intentionally ignore the project-local
-        // pin, so the banner would be misleading for them.
-        if (this.id?.startsWith('profile')) {
-            return;
-        }
-        const { config, path: filePath } = this.localProfile;
-        const profileName = config.profile ?? this.getDefaultProfile();
-        const relativePath = path.relative(process.cwd(), filePath) || path.basename(filePath);
-        this.log(formatLocalProfileBanner(profileName, config.workspace, relativePath));
-    }
-    async finally(_) {
-        if (this.updateNotice && !this.isJsonOutput()) {
-            this.log(this.updateNotice);
-        }
-        await super.finally(_);
-    }
-    isJsonOutput() {
-        const args = process.argv;
-        for (let i = 0; i < args.length; i++) {
-            if (args[i] === '--output' && args[i + 1] === 'json')
-                return true;
-            if (args[i] === '-o' && args[i + 1] === 'json')
-                return true;
-            if (args[i] === '--output=json' || args[i] === '-o=json')
-                return true;
-        }
-        return false;
-    }
     /**
      * Apply insecure TLS mode if the active profile has insecure: true.
      * Sets NODE_TLS_REJECT_UNAUTHORIZED=0 so all fetch() calls skip cert verification.
@@ -193,22 +156,23 @@ export default class BaseCommand extends Command {
             // Don't fail the command if we can't read the profile for insecure check
         }
     }
-    // Helper method to get the default profile from credentials file
-    getDefaultProfile() {
-        try {
-            const credentials = this.loadCredentialsFile();
-            if (credentials?.default) {
-                return credentials.default;
-            }
-            return 'default';
-        }
-        catch {
-            return 'default';
-        }
+    /**
+     * Report a failure as exit 1 for commands that reserve exit 2 for findings: operational errors,
+     * flag errors and oclif's own default exit 2 all become 1, and under `-o json` the failure is also
+     * written to stdout as `{"error": {"exit": 1, "message"}}`. A deliberate exit 0 passes through.
+     */
+    async catchAsOperational(error) {
+        if (error.oclif?.exit === 0)
+            return super.catch(error);
+        if (this.isJsonOutput())
+            this.log(JSON.stringify({ error: { exit: 1, message: error.message } }, null, 2));
+        this.error(error, { exit: 1 });
     }
-    // Helper method to get the profile flag value
-    getProfile() {
-        return this.flags?.profile;
+    async finally(_) {
+        if (this.updateNotice && !this.isJsonOutput()) {
+            this.log(this.updateNotice);
+        }
+        await super.finally(_);
     }
     /**
      * Get the resolved credentials file path, respecting --config flag and XANO_CONFIG env var.
@@ -225,17 +189,18 @@ export default class BaseCommand extends Command {
         }
         return resolveCredentialsPath();
     }
-    loadCredentialsFile() {
-        const credentialsPath = this.getCredentialsPath();
-        if (!fs.existsSync(credentialsPath)) {
-            return null;
+    // Helper method to get the default profile from credentials file
+    getDefaultProfile() {
+        try {
+            const credentials = this.loadCredentialsFile();
+            if (credentials?.default) {
+                return credentials.default;
+            }
+            return 'default';
         }
-        const fileContent = fs.readFileSync(credentialsPath, 'utf8');
-        const parsed = yaml.load(fileContent);
-        if (parsed && typeof parsed === 'object' && 'profiles' in parsed) {
-            return parsed;
+        catch {
+            return 'default';
         }
-        return null;
     }
     /**
      * Get or create the singleton sandbox environment for the authenticated user.
@@ -256,6 +221,105 @@ export default class BaseCommand extends Command {
         }
         return (await response.json());
     }
+    // Helper method to get the profile flag value
+    getProfile() {
+        return this.flags?.profile;
+    }
+    async init() {
+        await super.init();
+        this.localProfile = this.loadLocalProfile();
+        this.applyInsecureFromProfile();
+        this.maybePrintLocalProfileBanner();
+        const forceUpdateCheck = process.env.XANO_FORCE_UPDATE_CHECK === '1';
+        this.updateNotice = checkForUpdate(this.config.version, forceUpdateCheck);
+    }
+    /** Raw-argv check: the parsed flags are not available yet when the banner prints. */
+    isJsonOutput() {
+        const args = this.argv;
+        for (let i = 0; i < args.length; i++) {
+            if (args[i] === '--output' && args[i + 1] === 'json')
+                return true;
+            if (args[i] === '-o' && args[i + 1] === 'json')
+                return true;
+            if (args[i] === '--output=json' || args[i] === '-o=json')
+                return true;
+        }
+        return false;
+    }
+    loadCredentialsFile() {
+        const credentialsPath = this.getCredentialsPath();
+        if (!fs.existsSync(credentialsPath)) {
+            return null;
+        }
+        const fileContent = fs.readFileSync(credentialsPath, 'utf8');
+        const parsed = yaml.load(fileContent);
+        if (parsed && typeof parsed === 'object' && 'profiles' in parsed) {
+            return parsed;
+        }
+        return null;
+    }
+    /**
+     * Poll a static-host build until it reaches a terminal status (ok | error),
+     * showing a live, ticking spinner with the current stage and elapsed time —
+     * mirroring the UI's build progress for async (package.json) builds, which
+     * keep running after the upload returns.
+     *
+     * On a TTY it renders an animated spinner via ux.action; when quiet (JSON
+     * output) or non-interactive it falls back to plain one-line status updates.
+     *
+     * Returns the final status. Resolves to the last-seen status on timeout.
+     */
+    async logStaticHostUrls(opts) {
+        const { profile, staticHost, tenantName, verbose, workspaceId } = opts;
+        // When a tenant is scoped, target the tenant's static hosting; otherwise the
+        // workspace-level static host (default, unchanged behavior).
+        const scope = tenantName ? `/tenant/${tenantName}` : '';
+        const url = `${profile.instance_origin}/api:meta/workspace/${workspaceId}${scope}/static_host/${staticHost}`;
+        try {
+            const response = await this.verboseFetch(url, {
+                headers: { accept: 'application/json', Authorization: `Bearer ${profile.access_token}` },
+                method: 'GET',
+            }, verbose, profile.access_token);
+            if (!response.ok)
+                return;
+            const host = (await response.json());
+            if (host.dev?.default_url)
+                this.log(`Dev URL: ${host.dev.default_url}`);
+            if (host.dev?.custom_url)
+                this.log(`Dev Custom URL: ${host.dev.custom_url}`);
+            if (host.prod?.default_url)
+                this.log(`Prod URL: ${host.prod.default_url}`);
+            if (host.prod?.custom_url)
+                this.log(`Prod Custom URL: ${host.prod.custom_url}`);
+        }
+        catch {
+            // Non-fatal — the build succeeded, we just can't show the URL.
+        }
+    }
+    /**
+     * Parse an API error response and return a clean error message.
+     * Extracts the message from JSON responses and adds context for common errors.
+     */
+    async parseApiError(response, fallbackPrefix) {
+        const errorText = await response.text();
+        let message = `${fallbackPrefix} (${response.status})`;
+        try {
+            const errorJson = JSON.parse(errorText);
+            if (errorJson.message) {
+                message = errorJson.message;
+            }
+        }
+        catch {
+            if (errorText) {
+                message += `\n${errorText}`;
+            }
+        }
+        // Provide guidance when sandbox access is denied (free plan restriction)
+        if (response.status === 500 && message === 'Access Denied.') {
+            message = 'Sandbox is not available on the Free plan. Upgrade your plan to use sandbox features.';
+        }
+        return message;
+    }
     /**
      * Resolve the profile from flags and any project-local profile.yaml,
      * validating instance_origin and access_token exist.
@@ -289,30 +353,6 @@ export default class BaseCommand extends Command {
         }
         return { profile, profileName };
     }
-    /**
-     * Parse an API error response and return a clean error message.
-     * Extracts the message from JSON responses and adds context for common errors.
-     */
-    async parseApiError(response, fallbackPrefix) {
-        const errorText = await response.text();
-        let message = `${fallbackPrefix} (${response.status})`;
-        try {
-            const errorJson = JSON.parse(errorText);
-            if (errorJson.message) {
-                message = errorJson.message;
-            }
-        }
-        catch {
-            if (errorText) {
-                message += `\n${errorText}`;
-            }
-        }
-        // Provide guidance when sandbox access is denied (free plan restriction)
-        if (response.status === 500 && message === 'Access Denied.') {
-            message = 'Sandbox is not available on the Free plan. Upgrade your plan to use sandbox features.';
-        }
-        return message;
-    }
     /**
      * Make an HTTP request with optional verbose logging.
      * Use this for all Metadata API calls to support the --verbose flag.
@@ -324,81 +364,74 @@ export default class BaseCommand extends Command {
             ...options.headers,
         };
         const timeoutMs = resolveRequestTimeoutMs();
-        const fetchOptions = {
+        // Build the fetch options fresh each attempt: a retry needs a new
+        // AbortSignal (the first attempt's may already be aborted/consumed) and,
+        // when the dispatcher is the culprit, no dispatcher at all.
+        const buildFetchOptions = (withDispatcher) => ({
             ...options,
             // undici dispatcher: lifts the hidden 300s headers/body timeout to our bound
-            dispatcher: getRequestDispatcher(timeoutMs),
+            ...(withDispatcher ? { dispatcher: getRequestDispatcher(timeoutMs) } : {}),
             headers,
             // belt-and-suspenders hard ceiling that also covers DNS/connect stalls;
             // surfaces as a clean AbortError (see describeNetworkError). 0 = no bound.
+            // This alone bounds the whole request, so dropping the dispatcher (Node 26)
+            // does not lose the large-push timeout protection.
             ...(timeoutMs > 0 && !options.signal ? { signal: AbortSignal.timeout(timeoutMs) } : {}),
-        };
+        });
         const contentType = headers['Content-Type'] || 'application/json';
+        const logDiagnostic = this.isJsonOutput() ? this.logToStderr.bind(this) : this.log.bind(this);
         if (verbose) {
-            this.log('');
-            this.log('─'.repeat(60));
-            this.log(`→ ${method} ${url}`);
-            this.log(`  Content-Type: ${contentType}`);
+            logDiagnostic('');
+            logDiagnostic('─'.repeat(60));
+            logDiagnostic(`→ ${method} ${url}`);
+            logDiagnostic(`  Content-Type: ${contentType}`);
             if (authToken) {
-                this.log(`  Authorization: Bearer ${authToken.slice(0, 8)}...${authToken.slice(-4)}`);
+                logDiagnostic(`  Authorization: Bearer ${authToken.slice(0, 8)}...${authToken.slice(-4)}`);
             }
             if (options.body) {
                 const bodyStr = typeof options.body === 'string' ? options.body : String(options.body);
                 const bodyPreview = bodyStr.length > 500 ? bodyStr.slice(0, 500) + '...' : bodyStr;
-                this.log(`  Body: ${bodyPreview}`);
+                logDiagnostic(`  Body: ${bodyPreview}`);
             }
         }
         const startTime = Date.now();
-        const response = await fetch(url, fetchOptions);
+        let response;
+        try {
+            response = await fetch(url, buildFetchOptions(dispatcherSupported));
+        }
+        catch (error) {
+            // Node 26+ rejects our userland-undici dispatcher with UND_ERR_INVALID_ARG,
+            // surfaced only as "fetch failed" (DEV-7773). Disable it for the rest of the
+            // process and retry once without it; the AbortSignal.timeout ceiling above
+            // still bounds the request, so the large-push protection is preserved.
+            if (dispatcherSupported && isInvalidDispatcherError(error)) {
+                dispatcherSupported = false;
+                if (verbose) {
+                    logDiagnostic('  (this Node runtime rejected undici dispatcher; retrying without it — see DEV-7773)');
+                }
+                response = await fetch(url, buildFetchOptions(false));
+            }
+            else {
+                throw error;
+            }
+        }
         const elapsed = Date.now() - startTime;
         if (verbose) {
-            this.log(`← ${response.status} ${response.statusText} (${elapsed}ms)`);
-            this.log('─'.repeat(60));
-            this.log('');
+            logDiagnostic(`← ${response.status} ${response.statusText} (${elapsed}ms)`);
+            logDiagnostic('─'.repeat(60));
+            logDiagnostic('');
         }
         return response;
     }
-    /**
-     * Poll a static-host build until it reaches a terminal status (ok | error),
-     * showing a live, ticking spinner with the current stage and elapsed time —
-     * mirroring the UI's build progress for async (package.json) builds, which
-     * keep running after the upload returns.
-     *
-     * On a TTY it renders an animated spinner via ux.action; when quiet (JSON
-     * output) or non-interactive it falls back to plain one-line status updates.
-     *
-     * Returns the final status. Resolves to the last-seen status on timeout.
-     */
-    async logStaticHostUrls(opts) {
-        const { profile, staticHost, verbose, workspaceId } = opts;
-        const url = `${profile.instance_origin}/api:meta/workspace/${workspaceId}/static_host/${staticHost}`;
-        try {
-            const response = await this.verboseFetch(url, {
-                headers: { accept: 'application/json', Authorization: `Bearer ${profile.access_token}` },
-                method: 'GET',
-            }, verbose, profile.access_token);
-            if (!response.ok)
-                return;
-            const host = (await response.json());
-            if (host.dev?.default_url)
-                this.log(`Dev URL: ${host.dev.default_url}`);
-            if (host.dev?.custom_url)
-                this.log(`Dev Custom URL: ${host.dev.custom_url}`);
-            if (host.prod?.default_url)
-                this.log(`Prod URL: ${host.prod.default_url}`);
-            if (host.prod?.custom_url)
-                this.log(`Prod Custom URL: ${host.prod.custom_url}`);
-        }
-        catch {
-            // Non-fatal — the build succeeded, we just can't show the URL.
-        }
-    }
     async waitForBuild(opts) {
-        const { buildId, profile, quiet, staticHost, verbose, workspaceId } = opts;
+        const { buildId, profile, quiet, staticHost, tenantName, verbose, workspaceId } = opts;
         const intervalMs = opts.intervalMs ?? 2000;
         const timeoutMs = opts.timeoutMs ?? 600_000; // 10 min
         const terminal = new Set(['error', 'ok']);
-        const url = `${profile.instance_origin}/api:meta/workspace/${workspaceId}/static_host/${staticHost}/build/${buildId}`;
+        // When a tenant is scoped, target the tenant's static hosting; otherwise the
+        // workspace-level static host (default, unchanged behavior).
+        const scope = tenantName ? `/tenant/${tenantName}` : '';
+        const url = `${profile.instance_origin}/api:meta/workspace/${workspaceId}${scope}/static_host/${staticHost}/build/${buildId}`;
         // Spinner only on an interactive TTY and when not emitting JSON. Verbose mode
         // also disables it (the spinner would interleave with request/response logs).
         const animate = Boolean(process.stdout.isTTY) && !quiet && !verbose;
@@ -461,6 +494,50 @@ export default class BaseCommand extends Command {
         conclude(`stopped waiting after ${Math.round(timeoutMs / 1000)}s (last status: ${stage || 'unknown'})`);
         return stage;
     }
+    /**
+     * Find and parse the nearest project-local profile.yaml, unless an explicit
+     * -p/XANO_PROFILE was given (in which case the local file is ignored).
+     */
+    loadLocalProfile() {
+        if (argvHasProfileFlag(process.argv, process.env)) {
+            return null;
+        }
+        // Walks up to the filesystem root (git-style). parseLocalProfile returns
+        // null for a profile.yaml with no recognized keys, so an unrelated file
+        // belonging to another tool is ignored rather than hijacked.
+        const filePath = findLocalProfilePath(process.cwd());
+        if (!filePath) {
+            return null;
+        }
+        let config;
+        try {
+            config = parseLocalProfile(fs.readFileSync(filePath, 'utf8'));
+        }
+        catch (error) {
+            this.error(`${filePath}: ${error.message}`);
+        }
+        if (!config) {
+            this.warn(`Ignoring ${filePath}: no recognized profile keys found.`);
+            return null;
+        }
+        return { config, path: filePath };
+    }
+    /** Print the one-line target banner when a local profile.yaml is in effect. */
+    maybePrintLocalProfileBanner() {
+        if (!this.localProfile || this.isJsonOutput()) {
+            return;
+        }
+        // Credential-management commands (the `profile` topic) operate on the
+        // credentials store directly and intentionally ignore the project-local
+        // pin, so the banner would be misleading for them.
+        if (this.id?.startsWith('profile')) {
+            return;
+        }
+        const { config, path: filePath } = this.localProfile;
+        const profileName = config.profile ?? this.getDefaultProfile();
+        const relativePath = path.relative(process.cwd(), filePath) || path.basename(filePath);
+        this.log(formatLocalProfileBanner(profileName, config.workspace, relativePath));
+    }
 }
 /** Human-friendly label for a build status stage. */
 function stageLabel(status) {

package/dist/commands/auth/index.d.ts

@@ -48,10 +48,10 @@ export default class Auth extends Command {
     run(): Promise<AuthResult>;
     protected toErrorJson(err: unknown): unknown;
     private acquireToken;
-    private getHeaders;
     private fetchBranches;
     private fetchInstances;
     private fetchWorkspaces;
+    private getHeaders;
     private promptForToken;
     private promptProfileName;
     private readTokenFromStdin;