@sanity/runtime-cli 14.8.6 → 14.10.0

package/dist/commands/blueprints/init.js

@@ -4,7 +4,7 @@ import { blueprintInitCore } from '../../cores/blueprints/init.js';
 import { Logger } from '../../utils/logger.js';
 import { validTokenOrErrorMessage } from '../../utils/validated-token.js';
 export default class InitCommand extends RuntimeCommand {
-    static summary = 'Initialize a local Blueprint and optionally provision a remote Stack deployment';
+    static summary = 'Initialize a Blueprint and create a remote Stack';
     static description = `A Blueprint is your local infrastructure-as-code configuration that defines Sanity resources (datasets, functions, etc.). A Stack is the remote deployment target where your Blueprint is applied.
 [NOTE: Currently, accounts are limited to three (3) Stacks per project scope.]
 
@@ -57,7 +57,7 @@ After initialization, use 'blueprints plan' to preview changes, then 'blueprints
         const result = await validTokenOrErrorMessage(log);
         if (!result.ok)
             this.error(result.error.message);
-        const { success, error } = await blueprintInitCore({
+        const initResult = await blueprintInitCore({
             bin: this.config.bin,
             log,
             token: result.value,
@@ -65,7 +65,7 @@ After initialization, use 'blueprints plan' to preview changes, then 'blueprints
             args: this.args,
             flags: this.flags,
         });
-        if (!success)
-            this.error(error);
+        if (!initResult.success)
+            this.coreError(initResult);
     }
 }

package/dist/commands/blueprints/logs.js

@@ -22,7 +22,7 @@ If you're not seeing expected logs, verify your Stack is deployed with 'blueprin
         }),
     };
     async run() {
-        const { success, streaming, error, json } = await blueprintLogsCore({
+        const result = await blueprintLogsCore({
             bin: this.config.bin,
             log: Logger(this.log.bind(this), this.flags),
             auth: this.auth,
@@ -31,10 +31,10 @@ If you're not seeing expected logs, verify your Stack is deployed with 'blueprin
             validateResources: this.flags['validate-resources'],
             flags: this.flags,
         });
-        if (streaming)
-            return streaming;
-        if (!success)
-            this.error(error);
-        return json;
+        if (result.streaming)
+            return result.streaming;
+        if (!result.success)
+            this.coreError(result);
+        return result.json;
     }
 }

package/dist/commands/blueprints/plan.js

@@ -2,7 +2,7 @@ import { LocalBlueprintCommand, stackFlag, unhide } from '../../baseCommands.js'
 import { blueprintPlanCore } from '../../cores/blueprints/plan.js';
 import { Logger } from '../../utils/logger.js';
 export default class PlanCommand extends LocalBlueprintCommand {
-    static summary = 'Enumerate resources to be deployed to the remote Stack - will not modify any resources';
+    static summary = 'Preview changes that will be applied to the remote Stack';
     static description = `Use this command to preview what changes will be applied to your remote Stack before deploying. This is a safe, read-only operation—no resources are created, modified, or deleted.
 
 Run 'blueprints plan' after making local changes to your Blueprint manifest to verify the expected diff. When ready, run 'blueprints deploy' to apply changes.`;
@@ -11,7 +11,7 @@ Run 'blueprints plan' after making local changes to your Blueprint manifest to v
         stack: unhide(stackFlag),
     };
     async run() {
-        const { success, error, json } = await blueprintPlanCore({
+        const result = await blueprintPlanCore({
             bin: this.config.bin,
             log: Logger(this.log.bind(this), this.flags),
             token: this.sanityToken,
@@ -19,8 +19,8 @@ Run 'blueprints plan' after making local changes to your Blueprint manifest to v
             validateResources: this.flags['validate-resources'],
             flags: this.flags,
         });
-        if (!success)
-            this.error(error);
-        return json;
+        if (!result.success)
+            this.coreError(result);
+        return result.json;
     }
 }

package/dist/commands/blueprints/promote.js

@@ -3,8 +3,10 @@ import { DeployedStackCommand } from '../../baseCommands.js';
 import { blueprintPromoteCore } from '../../cores/blueprints/promote.js';
 import { Logger } from '../../utils/logger.js';
 export default class PromoteCommand extends DeployedStackCommand {
-    static summary = 'Promote a Stack deployment to a broader scope';
-    static description = `EXPERIMENTAL! Promotes a Stack, changing its scope from project to organization. This is a one-way trip.`;
+    static summary = 'Promote a Stack from project scope to organization scope';
+    static description = `Promotes a deployed Stack to organization scope, enabling management of org-level resources. Promotion cannot be reversed.
+
+Your local Blueprint configuration will be updated to reflect the new scope.`;
     static hidden = true;
     static examples = [
         '<%= config.bin %> <%= command.id %>',
@@ -21,7 +23,7 @@ export default class PromoteCommand extends DeployedStackCommand {
         }),
     };
     async run() {
-        const { success, error, json } = await blueprintPromoteCore({
+        const result = await blueprintPromoteCore({
             bin: this.config.bin,
             log: Logger(this.log.bind(this), this.flags),
             token: this.sanityToken,
@@ -34,8 +36,8 @@ export default class PromoteCommand extends DeployedStackCommand {
             validateResources: this.flags['validate-resources'],
             flags: this.flags,
         });
-        if (!success)
-            this.error(error);
-        return json;
+        if (!result.success)
+            this.coreError(result);
+        return result.json;
     }
 }

package/dist/commands/blueprints/stacks.js

@@ -3,7 +3,7 @@ import { LocalBlueprintCommand, organizationIdFlagConfig, projectIdFlagConfig, }
 import { blueprintStacksCore } from '../../cores/blueprints/stacks.js';
 import { Logger } from '../../utils/logger.js';
 export default class StacksCommand extends LocalBlueprintCommand {
-    static summary = "List all remote Stack deployments (defaults to the current Blueprint's project scope)";
+    static summary = 'List remote Stack deployments for your project or organization';
     static description = `Shows all Stacks associated with a project or organization. By default, lists Stacks scoped to the local Blueprint.
 
 Use this to discover existing Stacks you can scope a local Blueprint to (using 'blueprints config --edit'), or to audit what's deployed across your project.`;
@@ -17,7 +17,7 @@ Use this to discover existing Stacks you can scope a local Blueprint to (using '
         'organization-id': Flags.string({ ...organizationIdFlagConfig, exclusive: ['project-id'] }),
     };
     async run() {
-        const { success, error, json } = await blueprintStacksCore({
+        const result = await blueprintStacksCore({
             bin: this.config.bin,
             log: Logger(this.log.bind(this), this.flags),
             token: this.sanityToken,
@@ -25,8 +25,8 @@ Use this to discover existing Stacks you can scope a local Blueprint to (using '
             validateResources: this.flags['validate-resources'],
             flags: this.flags,
         });
-        if (!success)
-            this.error(error);
-        return json;
+        if (!result.success)
+            this.coreError(result);
+        return result.json;
     }
 }

package/dist/commands/functions/add.js

@@ -61,14 +61,14 @@ After adding, use 'functions dev' to test locally, then 'blueprints deploy' to p
         }),
     };
     async run() {
-        const { success, error } = await functionAddCore({
+        const result = await functionAddCore({
             bin: this.config.bin,
             log: Logger(this.log.bind(this), this.flags),
             blueprint: this.blueprint,
             validateResources: this.flags['validate-resources'],
             flags: this.flags,
         });
-        if (!success)
-            this.error(error);
+        if (!result.success)
+            this.coreError(result);
     }
 }

package/dist/commands/functions/build.js

@@ -19,7 +19,7 @@ export default class BuildCommand extends LocalBlueprintCommand {
         'out-dir': Flags.string({ char: 'o', description: 'Output directory for zip files' }),
     };
     async run() {
-        const { success, error, json } = await functionBuildCore({
+        const result = await functionBuildCore({
             bin: this.config.bin,
             log: Logger(this.log.bind(this), this.flags),
             args: { name: this.args.name },
@@ -27,8 +27,8 @@ export default class BuildCommand extends LocalBlueprintCommand {
             blueprint: this.blueprint,
             validateResources: this.flags['validate-resources'],
         });
-        if (!success)
-            this.error(error);
-        return json;
+        if (!result.success)
+            this.coreError(result);
+        return result.json;
     }
 }

package/dist/commands/functions/dev.js

@@ -34,15 +34,15 @@ To invoke a function with the CLI, use 'functions test'.`;
     };
     async run() {
         const { flags } = await this.parse(DevCommand);
-        const { success, error, streaming } = await functionDevCore({
+        const result = await functionDevCore({
             bin: this.config.bin,
             log: Logger(this.log.bind(this), this.flags),
             validateResources: this.flags['validate-resources'],
             flags,
         });
-        if (!success)
-            this.error(error);
-        if (streaming)
-            await streaming;
+        if (!result.success)
+            this.coreError(result);
+        if (result.streaming)
+            await result.streaming;
     }
 }

package/dist/commands/functions/env/add.js

@@ -16,7 +16,7 @@ Environment variables are useful for API keys, configuration values, and other s
         '<%= config.bin %> <%= command.id %> MyFunction API_URL https://api.example.com/',
     ];
     async run() {
-        const { success, error, json } = await functionEnvAddCore({
+        const result = await functionEnvAddCore({
             bin: this.config.bin,
             log: Logger(this.log.bind(this), this.flags),
             args: this.args,
@@ -29,8 +29,8 @@ Environment variables are useful for API keys, configuration values, and other s
             stackId: this.stackId,
             validateResources: this.flags['validate-resources'],
         });
-        if (!success)
-            this.error(error);
-        return json;
+        if (!result.success)
+            this.coreError(result);
+        return result.json;
     }
 }

package/dist/commands/functions/env/list.js

@@ -12,7 +12,7 @@ Use 'functions env add' to set variables or 'functions env remove' to delete the
     };
     static examples = ['<%= config.bin %> <%= command.id %> MyFunction'];
     async run() {
-        const { success, error, json } = await functionEnvListCore({
+        const result = await functionEnvListCore({
             bin: this.config.bin,
             log: Logger(this.log.bind(this), this.flags),
             args: this.args,
@@ -25,8 +25,8 @@ Use 'functions env add' to set variables or 'functions env remove' to delete the
             stackId: this.stackId,
             validateResources: this.flags['validate-resources'],
         });
-        if (!success)
-            this.error(error);
-        return json;
+        if (!result.success)
+            this.coreError(result);
+        return result.json;
     }
 }

package/dist/commands/functions/env/remove.js

@@ -13,7 +13,7 @@ Use 'functions env list' to see current variables before removing.`;
     };
     static examples = ['<%= config.bin %> <%= command.id %> MyFunction API_URL'];
     async run() {
-        const { success, error, json } = await functionEnvRemoveCore({
+        const result = await functionEnvRemoveCore({
             bin: this.config.bin,
             log: Logger(this.log.bind(this), this.flags),
             args: this.args,
@@ -26,8 +26,8 @@ Use 'functions env list' to see current variables before removing.`;
             stackId: this.stackId,
             validateResources: this.flags['validate-resources'],
         });
-        if (!success)
-            this.error(error);
-        return json;
+        if (!result.success)
+            this.coreError(result);
+        return result.json;
     }
 }

package/dist/commands/functions/logs.js

@@ -48,7 +48,7 @@ Use --watch (-w) to stream logs in real-time. Use --delete to clear all logs for
         }),
     };
     async run() {
-        const { success, error, json } = await functionLogsCore({
+        const result = await functionLogsCore({
             bin: this.config.bin,
             log: Logger(this.log.bind(this), this.flags),
             error: (msg, options) => this.error(msg, options),
@@ -64,8 +64,8 @@ Use --watch (-w) to stream logs in real-time. Use --delete to clear all logs for
             helpText: LogsCommand.getHelpText(this.config.bin, 'functions logs'),
             validateResources: this.flags['validate-resources'],
         });
-        if (!success)
-            this.error(error);
-        return json;
+        if (!result.success)
+            this.coreError(result);
+        return result.json;
     }
 }

package/dist/commands/functions/test.js

@@ -159,7 +159,7 @@ Provide test data via --data (inline JSON), --file (JSON file), or --document-id
                     '  --document-id-before and --document-id-after');
             }
         }
-        const { success, error, json } = await functionTestCore({
+        const result = await functionTestCore({
             bin: this.config.bin,
             log: Logger(this.log.bind(this), this.flags),
             error: (msg, options) => this.error(msg, options),
@@ -169,8 +169,8 @@ Provide test data via --data (inline JSON), --file (JSON file), or --document-id
             helpText: TestCommand.getHelpText(this.config.bin, 'functions test'),
             validateResources: this.flags['validate-resources'],
         });
-        if (!success)
-            this.error(error);
-        return json;
+        if (!result.success)
+            this.coreError(result);
+        return result.json;
     }
 }

package/dist/constants.d.ts

@@ -4,6 +4,7 @@ export declare const SANITY_FUNCTION_PREFIX = "sanity.function.";
 export declare const SANITY_FUNCTION_DOCUMENT = "sanity.function.document";
 export declare const SANITY_FUNCTION_MEDIA_LIBRARY_ASSET = "sanity.function.media-library.asset";
 export declare const SANITY_FUNCTION_SCHEDULED = "sanity.function.cron";
+export declare const SANITY_FUNCTION_SYNC_TAG_INVALIDATE = "sanity.function.sync-tag-invalidate";
 export declare const SANITY_PROJECT = "sanity.project";
 export declare const SANITY_PROJECT_CORS = "sanity.project.cors";
 export declare const SANITY_PROJECT_DATASET = "sanity.project.dataset";

package/dist/constants.js

@@ -4,6 +4,7 @@ export const SANITY_FUNCTION_PREFIX = 'sanity.function.';
 export const SANITY_FUNCTION_DOCUMENT = 'sanity.function.document';
 export const SANITY_FUNCTION_MEDIA_LIBRARY_ASSET = 'sanity.function.media-library.asset';
 export const SANITY_FUNCTION_SCHEDULED = 'sanity.function.cron';
+export const SANITY_FUNCTION_SYNC_TAG_INVALIDATE = 'sanity.function.sync-tag-invalidate';
 export const SANITY_PROJECT = 'sanity.project';
 export const SANITY_PROJECT_CORS = 'sanity.project.cors';
 export const SANITY_PROJECT_DATASET = 'sanity.project.dataset';
@@ -29,6 +30,7 @@ export const FUNCTION_TYPES = [
 export const PROJECT_SCOPED_FUNCTION_TYPES = new Set([
     SANITY_FUNCTION_DOCUMENT,
     SANITY_FUNCTION_MEDIA_LIBRARY_ASSET,
+    SANITY_FUNCTION_SYNC_TAG_INVALIDATE,
 ]);
 export const ORGANIZATION_SCOPED_FUNCTION_TYPES = new Set([
     SANITY_FUNCTION_SCHEDULED,

package/dist/cores/blueprints/config.js

@@ -111,7 +111,6 @@ function printConfig(options) {
     const { projectId, organizationId, stackId, updatedAt } = config;
     const scopeType = projectId ? 'project' : 'organization';
     const scopeId = projectId ? projectId : organizationId;
-    log.verbose(JSON.stringify(config));
     log(`${styleText('bold', `${configLabel} configuration:`)}`);
     log(`  Deployment: ${labeledId('stack', stackId)}`);
     log(`   Scoped to: ${labeledId(scopeType, scopeId)}`);

package/dist/cores/blueprints/deploy.d.ts

@@ -12,6 +12,7 @@ export interface BlueprintDeployOptions extends CoreConfig {
         'fn-installer'?: string;
         'no-wait'?: boolean;
         'new-stack-name'?: string;
+        message?: string;
         verbose?: boolean;
     };
 }

package/dist/cores/blueprints/deploy.js

@@ -25,7 +25,11 @@ export async function blueprintDeployCore(options) {
         if (operationStatus === 'QUEUED' || operationStatus === 'IN_PROGRESS') {
             return {
                 success: false,
-                error: 'A Stack operation is already in progress. Please wait for it to complete before deploying.',
+                error: 'A Stack operation is already in progress.',
+                suggestions: [
+                    `Run \`npx ${bin} blueprints info\` to check operation status.`,
+                    'Wait for the current operation to complete, then try again.',
+                ],
             };
         }
         const resources = [...blueprint.resources];
@@ -50,13 +54,21 @@ export async function blueprintDeployCore(options) {
                 scopeId,
                 name: stackName,
                 document: { resources },
+                userMessage: flags.message,
             },
             auth,
             logger: log,
         });
         if (!deployOk) {
             spinner.fail(`${styleText('red', 'Failed')} to update Stack deployment`);
-            return { success: false, error: deployError || 'Failed to update Stack deployment' };
+            return {
+                success: false,
+                error: deployError || 'Failed to update Stack deployment',
+                suggestions: [
+                    `Run \`npx ${bin} blueprints plan\` to preview changes before deploying.`,
+                    `Run \`npx ${bin} blueprints doctor\` to check your configuration.`,
+                ],
+            };
         }
         spinner.stop().clear();
         if (noWait) {
@@ -88,7 +100,14 @@ export async function blueprintDeployCore(options) {
                 if (!ok) {
                     if (logStreamCleanup)
                         logStreamCleanup();
-                    return { success: false, error: 'Failed to check Stack deployment status' };
+                    return {
+                        success: false,
+                        error: 'Failed to check Stack deployment status',
+                        suggestions: [
+                            'The deployment may still be running on Sanity servers.',
+                            `Run \`npx ${bin} blueprints info\` to check status.`,
+                        ],
+                    };
                 }
                 const operation = currentStack.recentOperation;
                 if (!operation) {
@@ -99,7 +118,14 @@ export async function blueprintDeployCore(options) {
                 if (operation.status === 'FAILED') {
                     if (logStreamCleanup)
                         logStreamCleanup();
-                    return { success: false, error: 'Stack deployment failed' };
+                    return {
+                        success: false,
+                        error: 'Stack deployment failed',
+                        suggestions: [
+                            `Run \`npx ${bin} blueprints logs\` to review deployment logs.`,
+                            `Run \`npx ${bin} blueprints plan\` to identify issues with your Blueprint.`,
+                        ],
+                    };
                 }
                 if (operation.status === 'COMPLETED') {
                     if (logStreamCleanup)

package/dist/cores/blueprints/destroy.js

@@ -55,8 +55,16 @@ export async function blueprintDestroyCore(options) {
                 return { success: false, error: blueprintStack.error || 'Failed to get Stack' };
             stack = blueprintStack.stack;
         }
-        if (!stack)
-            return { success: false, error: 'Stack deployment not found' };
+        if (!stack) {
+            return {
+                success: false,
+                error: 'Stack deployment not found',
+                suggestions: [
+                    `Run \`npx ${bin} blueprints stacks\` to list available Stacks.`,
+                    `Run \`npx ${bin} blueprints doctor\` to check your configuration.`,
+                ],
+            };
+        }
         const destroySpinner = log.ora({
             text: `Destroying Stack deployment "${styleText('bold', stack.name)}" ${niceId(stack.id)}...`,
             color: 'red',
@@ -122,7 +130,14 @@ export async function blueprintDestroyCore(options) {
                 if (operation.status === 'FAILED') {
                     if (logStreamCleanup)
                         logStreamCleanup();
-                    return { success: false, error: 'Stack destruction failed' };
+                    return {
+                        success: false,
+                        error: 'Stack destruction failed',
+                        suggestions: [
+                            `Run \`npx ${bin} blueprints logs\` to review destruction logs.`,
+                            `Run \`npx ${bin} blueprints info\` to view current Stack status.`,
+                        ],
+                    };
                 }
                 if (!idleMessageShown && Date.now() - lastLogAt > 60_000) {
                     log(`No new activity for 60 seconds. The destruction is still running on Sanity servers.`);

package/dist/cores/blueprints/doctor.js

@@ -163,6 +163,8 @@ export async function blueprintDoctorCore(options) {
                             ? `  ${styleText('dim', new Date(time).toLocaleString('sv-SE'))}`
                             : '';
                         stackRows.push(['Operation', `${op.status}${timestamp}`]);
+                        if (op.userMessage)
+                            stackRows.push(['  Message', `"${op.userMessage}"`]);
                     }
                     if (stack.resources) {
                         stackRows.push(['Resources', `${stack.resources.length}`]);
@@ -284,6 +286,7 @@ export async function blueprintDoctorCore(options) {
             return {
                 success: false,
                 error: `${errorMessage}. Unable to fix: Missing authentication token`,
+                suggestions: ['Run `npx @sanity/cli login` to authenticate, then try again.'],
                 data: { diagnostics: flatDiagnostics },
             };
         }
@@ -291,6 +294,7 @@ export async function blueprintDoctorCore(options) {
             return {
                 success: false,
                 error: `${errorMessage}. Unable to fix: ${tokenOrError.error.message}`,
+                suggestions: ['Run `npx @sanity/cli login` to re-authenticate.'],
                 data: { diagnostics: flatDiagnostics },
             };
         }
@@ -298,6 +302,7 @@ export async function blueprintDoctorCore(options) {
             return {
                 success: false,
                 error: `${errorMessage}. Unable to fix: Blueprint is missing or invalid`,
+                suggestions: [`Run \`npx ${bin} blueprints init\` to create a new Blueprint.`],
                 data: { diagnostics: flatDiagnostics },
             };
         }
@@ -310,6 +315,10 @@ export async function blueprintDoctorCore(options) {
             flags: { edit: true, verbose: v },
         });
     }
-    log(styleText('dim', `  Run \`npx ${bin} blueprints doctor --fix\` to resolve configuration issues.`));
-    return { success: false, error: errorMessage, data: { diagnostics: flatDiagnostics } };
+    return {
+        success: false,
+        error: errorMessage,
+        suggestions: [`Run \`npx ${bin} blueprints doctor --fix\` to fix configuration issues.`],
+        data: { diagnostics: flatDiagnostics },
+    };
 }

package/dist/cores/blueprints/plan.js

@@ -9,13 +9,17 @@ export async function blueprintPlanCore(options) {
     log(formatResourceTree(resources));
     if (!token || !scopeType || !scopeId) {
         log(styleText('dim', 'Unable to retrieve live Stack deployment for comparison'));
-        const errorMessage = !token
-            ? `Missing authentication token. Run \`npx ${bin} login\` to authenticate.`
-            : `Missing Blueprint configuration. Run \`npx ${bin} blueprints doctor --fix\` to repair.`;
-        return {
-            success: false,
-            error: errorMessage,
-        };
+        return !token
+            ? {
+                success: false,
+                error: 'Missing authentication token',
+                suggestions: [`Run \`npx ${bin} login\` to authenticate.`],
+            }
+            : {
+                success: false,
+                error: 'Missing Blueprint configuration',
+                suggestions: [`Run \`npx ${bin} blueprints doctor --fix\` to fix your configuration.`],
+            };
     }
     const stackId = flags.stack
         ? await resolveStackIdByNameOrId(flags.stack, { token, scopeType, scopeId }, log)
@@ -24,7 +28,8 @@ export async function blueprintPlanCore(options) {
         log(styleText('dim', 'Unable to retrieve live Stack deployment for comparison'));
         return {
             success: false,
-            error: `Missing Stack deployment configuration. Run \`npx ${bin} blueprints doctor --fix\` to repair.`,
+            error: 'Missing Stack deployment configuration',
+            suggestions: [`Run \`npx ${bin} blueprints doctor --fix\` to fix your configuration.`],
         };
     }
     const auth = { token, scopeType, scopeId };
@@ -48,12 +53,15 @@ export async function blueprintPlanCore(options) {
                     log(`  ${styleText(['bold', 'red'], '✘')} ${msg}`);
                 }
             }
-            log(`\n  Fix the issues above before running "${styleText(['bold', 'magenta'], `npx ${bin} blueprints deploy`)}"`);
         }
         else {
             log(styleText('dim', '\nUnable to retrieve deployment plan from server'));
         }
-        return { success: false, error: 'Deployment plan has problems' };
+        return {
+            success: false,
+            error: 'Deployment plan has problems',
+            suggestions: [`Fix the issues above, then run \`npx ${bin} blueprints deploy\`.`],
+        };
     }
     log('');
     log(formatDeploymentPlan(planResponse.deploymentPlan));

package/dist/cores/blueprints/promote.js

@@ -3,13 +3,13 @@ import { patchConfigFile } from '../../actions/blueprints/config.js';
 import { promoteStack } from '../../actions/blueprints/stacks.js';
 import { niceId } from '../../utils/display/presenters.js';
 export async function blueprintPromoteCore(options) {
-    const { log, stackId, auth, flags, deployedStack, blueprint } = options;
+    const { bin = 'sanity', log, stackId, auth, flags, deployedStack, blueprint } = options;
     let message = `"${deployedStack.name}" ${niceId(deployedStack.id)}`;
     if (deployedStack.scopeType === 'organization') {
         message = `Stack ${message} is already org-scoped. Promote again?`;
     }
     else {
-        message = `Are you sure you want to promote Stack ${message}?`;
+        message = `Promote Stack ${message} from project to organization scope? You will need admin access to your organization.`;
     }
     if (!flags.force) {
         const confirmed = await confirm({ message });
@@ -22,7 +22,12 @@ export async function blueprintPromoteCore(options) {
         const { ok, error, stack } = await promoteStack({ stackId, auth, logger: log });
         if (!ok) {
             spinner.fail('Failed to promote Stack');
-            return { success: false, error: error || 'Failed to promote Stack' };
+            const suggestions = [];
+            if (error && /access|permission|forbidden/i.test(error)) {
+                suggestions.push('Verify you have organization admin access.');
+            }
+            suggestions.push(`Run \`npx ${bin} blueprints info\` to check the current Stack scope.`);
+            return { success: false, error: error || 'Failed to promote Stack', suggestions };
         }
         spinner.stop().clear();
         log(`Stack "${stack.name}" ${niceId(stack.id)} promoted successfully`);
@@ -39,6 +44,9 @@ export async function blueprintPromoteCore(options) {
             return {
                 success: false,
                 error: 'Stack promoted successfully but failed to update local Blueprint configuration. No config file found.',
+                suggestions: [
+                    `Run \`npx ${bin} blueprints config --edit\` to update your local configuration.`,
+                ],
             };
         }
         return { success: true, json: { stack }, data: { stack } };

package/dist/cores/blueprints/stacks.js

@@ -21,15 +21,26 @@ export async function blueprintStacksCore(options) {
         scopeId = flagProjectId;
     }
     if (!scopeType || !scopeId) {
-        log.error('Run in a Blueprint directory or provide a Project with --project-id');
-        return { success: false, error: 'Unable to determine scope for Blueprint Stacks' };
+        return {
+            success: false,
+            error: 'Unable to determine scope for Blueprint Stacks',
+            suggestions: ['Run in a Blueprint directory or provide a project with --project-id.'],
+        };
     }
     try {
         const spinner = log.ora('Fetching Stacks...').start();
         const { ok, stacks, error } = await listStacks({ token, scopeType, scopeId }, log);
         if (!ok) {
             spinner.fail('Failed to list Stacks');
-            return { success: false, error: error || 'Failed to list stacks' };
+            const suggestions = [];
+            if (error && /access|permission|forbidden/i.test(error)) {
+                suggestions.push('Verify you have access to this organization or project.', `Try a different scope with --project-id or --organization-id.`);
+            }
+            return {
+                success: false,
+                error: error || 'Failed to list stacks',
+                suggestions: suggestions.length ? suggestions : undefined,
+            };
         }
         spinner.stop().clear();
         if (!stacks || stacks.length === 0) {