@sanity/runtime-cli 11.2.0 → 12.0.0

package/README.md

@@ -20,7 +20,7 @@ $ npm install -g @sanity/runtime-cli
 $ sanity-run COMMAND
 running command...
 $ sanity-run (--version)
-@sanity/runtime-cli/11.2.0 linux-x64 node-v24.11.1
+@sanity/runtime-cli/12.0.0 linux-x64 node-v24.11.1
 $ sanity-run --help [COMMAND]
 USAGE
   $ sanity-run COMMAND
@@ -92,7 +92,7 @@ EXAMPLES
   $ sanity-run blueprints add function --name my-function --fn-type document-create --fn-type document-update --lang js
 ```
 
-_See code: [src/commands/blueprints/add.ts](https://github.com/sanity-io/runtime-cli/blob/v11.2.0/src/commands/blueprints/add.ts)_
+_See code: [src/commands/blueprints/add.ts](https://github.com/sanity-io/runtime-cli/blob/v12.0.0/src/commands/blueprints/add.ts)_
 
 ## `sanity-run blueprints config`
 
@@ -100,14 +100,13 @@ View or edit Blueprint configuration
 
 ```
 USAGE
-  $ sanity-run blueprints config [-t] [--project-id <value> -e] [--organization-id <value> ] [--stack-id <value> ]
+  $ sanity-run blueprints config [--project-id <value> -e] [--organization-id <value> ] [--stack-id <value> ]
 
 FLAGS
-  -e, --edit                     Edit the configuration
-  -t, --test-config              Validate the configuration
-      --organization-id=<value>  Update the Organization ID in the configuration. Requires --edit flag
-      --project-id=<value>       Update the Project ID in the configuration. Requires --edit flag
-      --stack-id=<value>         Update the Stack ID in the configuration. Requires --edit flag
+  -e, --edit                     Modify the configuration interactively, or directly when combined with ID flags.
+      --organization-id=<value>  Directly set the Organization ID in the configuration. Requires --edit flag
+      --project-id=<value>       Directly set the Project ID in the configuration. Requires --edit flag
+      --stack-id=<value>         Directly set the Stack ID in the configuration. Requires --edit flag
 
 DESCRIPTION
   View or edit Blueprint configuration
@@ -115,8 +114,6 @@ DESCRIPTION
 EXAMPLES
   $ sanity-run blueprints config
 
-  $ sanity-run blueprints config --test-config
-
   $ sanity-run blueprints config --edit
 
   $ sanity-run blueprints config --edit --project-id <projectId>
@@ -124,7 +121,7 @@ EXAMPLES
   $ sanity-run blueprints config --edit --project-id <projectId> --stack-id <stackId>
 ```
 
-_See code: [src/commands/blueprints/config.ts](https://github.com/sanity-io/runtime-cli/blob/v11.2.0/src/commands/blueprints/config.ts)_
+_See code: [src/commands/blueprints/config.ts](https://github.com/sanity-io/runtime-cli/blob/v12.0.0/src/commands/blueprints/config.ts)_
 
 ## `sanity-run blueprints deploy`
 
@@ -135,7 +132,7 @@ USAGE
   $ sanity-run blueprints deploy [--no-wait]
 
 FLAGS
-  --no-wait  Do not wait for deployment to complete
+  --no-wait  Do not wait for Stack deployment to complete
 
 DESCRIPTION
   Deploy a Blueprint
@@ -146,11 +143,11 @@ EXAMPLES
   $ sanity-run blueprints deploy --no-wait
 ```
 
-_See code: [src/commands/blueprints/deploy.ts](https://github.com/sanity-io/runtime-cli/blob/v11.2.0/src/commands/blueprints/deploy.ts)_
+_See code: [src/commands/blueprints/deploy.ts](https://github.com/sanity-io/runtime-cli/blob/v12.0.0/src/commands/blueprints/deploy.ts)_
 
 ## `sanity-run blueprints destroy`
 
-Destroy a Blueprint deployment (will not delete local files)
+Destroy a Blueprint Stack deployment and its resources (will not delete local files)
 
 ```
 USAGE
@@ -158,14 +155,14 @@ USAGE
     [--no-wait]
 
 FLAGS
-  --force                    Force destroy (skip confirmation)
-  --no-wait                  Do not wait for destruction to complete
+  --force                    Force Stack destruction (skip confirmation)
+  --no-wait                  Do not wait for Stack destruction to complete
   --organization-id=<value>  Organization associated with the Stack
   --project-id=<value>       Project associated with the Stack
   --stack-id=<value>         Stack ID to destroy (defaults to current Stack)
 
 DESCRIPTION
-  Destroy a Blueprint deployment (will not delete local files)
+  Destroy a Blueprint Stack deployment and its resources (will not delete local files)
 
 EXAMPLES
   $ sanity-run blueprints destroy
@@ -173,7 +170,7 @@ EXAMPLES
   $ sanity-run blueprints destroy --stack-id <stackId> --project-id <projectId> --force --no-wait
 ```
 
-_See code: [src/commands/blueprints/destroy.ts](https://github.com/sanity-io/runtime-cli/blob/v11.2.0/src/commands/blueprints/destroy.ts)_
+_See code: [src/commands/blueprints/destroy.ts](https://github.com/sanity-io/runtime-cli/blob/v12.0.0/src/commands/blueprints/destroy.ts)_
 
 ## `sanity-run blueprints doctor`
 
@@ -191,21 +188,21 @@ DESCRIPTION
   Diagnose potential issues with Blueprint configuration
 ```
 
-_See code: [src/commands/blueprints/doctor.ts](https://github.com/sanity-io/runtime-cli/blob/v11.2.0/src/commands/blueprints/doctor.ts)_
+_See code: [src/commands/blueprints/doctor.ts](https://github.com/sanity-io/runtime-cli/blob/v12.0.0/src/commands/blueprints/doctor.ts)_
 
 ## `sanity-run blueprints info`
 
-Show information about a Blueprint deployment
+Show information about a Blueprint Stack deployment
 
 ```
 USAGE
   $ sanity-run blueprints info [--id <value>]
 
 FLAGS
-  --id=<value>  Stack ID to show info for (defaults to current stack)
+  --id=<value>  Stack ID to show info for (defaults to current Stack)
 
 DESCRIPTION
-  Show information about a Blueprint deployment
+  Show information about a Blueprint Stack deployment
 
 EXAMPLES
   $ sanity-run blueprints info
@@ -213,7 +210,7 @@ EXAMPLES
   $ sanity-run blueprints info --stack-id <stackId>
 ```
 
-_See code: [src/commands/blueprints/info.ts](https://github.com/sanity-io/runtime-cli/blob/v11.2.0/src/commands/blueprints/info.ts)_
+_See code: [src/commands/blueprints/info.ts](https://github.com/sanity-io/runtime-cli/blob/v12.0.0/src/commands/blueprints/info.ts)_
 
 ## `sanity-run blueprints init [DIR]`
 
@@ -222,7 +219,7 @@ Initialize a new Blueprint
 ```
 USAGE
   $ sanity-run blueprints init [DIR] [--dir <value>] [--example <value> | --blueprint-type json|js|ts | --stack-id
-    <value> | --stack-name <value>] [--project-id <value>] [--organization-id <value>]
+    <value> | --stack-name <value>] [--project-id <value>] [--organization-id <value>] [--verbose]
 
 ARGUMENTS
   [DIR]  Directory to create the Blueprint in
@@ -236,6 +233,7 @@ FLAGS
   --project-id=<value>       Sanity Project ID to use for the Blueprint
   --stack-id=<value>         Existing Stack ID to use for the Blueprint
   --stack-name=<value>       Name to use for a NEW Stack
+  --verbose                  Verbose output
 
 DESCRIPTION
   Initialize a new Blueprint
@@ -252,21 +250,21 @@ EXAMPLES
   $ sanity-run blueprints init --blueprint-type <json|js|ts> --stack-name <stackName>
 ```
 
-_See code: [src/commands/blueprints/init.ts](https://github.com/sanity-io/runtime-cli/blob/v11.2.0/src/commands/blueprints/init.ts)_
+_See code: [src/commands/blueprints/init.ts](https://github.com/sanity-io/runtime-cli/blob/v12.0.0/src/commands/blueprints/init.ts)_
 
 ## `sanity-run blueprints logs`
 
-Display logs for a Blueprint deployment
+Display logs for a Blueprint Stack deployment
 
 ```
 USAGE
   $ sanity-run blueprints logs [-w]
 
 FLAGS
-  -w, --watch  Watch for new logs (streaming mode)
+  -w, --watch  Watch for new Stack logs (streaming mode)
 
 DESCRIPTION
-  Display logs for a Blueprint deployment
+  Display logs for a Blueprint Stack deployment
 
 EXAMPLES
   $ sanity-run blueprints logs
@@ -274,7 +272,7 @@ EXAMPLES
   $ sanity-run blueprints logs --watch
 ```
 
-_See code: [src/commands/blueprints/logs.ts](https://github.com/sanity-io/runtime-cli/blob/v11.2.0/src/commands/blueprints/logs.ts)_
+_See code: [src/commands/blueprints/logs.ts](https://github.com/sanity-io/runtime-cli/blob/v12.0.0/src/commands/blueprints/logs.ts)_
 
 ## `sanity-run blueprints plan`
 
@@ -291,7 +289,7 @@ EXAMPLES
   $ sanity-run blueprints plan
 ```
 
-_See code: [src/commands/blueprints/plan.ts](https://github.com/sanity-io/runtime-cli/blob/v11.2.0/src/commands/blueprints/plan.ts)_
+_See code: [src/commands/blueprints/plan.ts](https://github.com/sanity-io/runtime-cli/blob/v12.0.0/src/commands/blueprints/plan.ts)_
 
 ## `sanity-run blueprints stacks`
 
@@ -316,7 +314,7 @@ EXAMPLES
   $ sanity-run blueprints stacks --organization-id <organizationId>
 ```
 
-_See code: [src/commands/blueprints/stacks.ts](https://github.com/sanity-io/runtime-cli/blob/v11.2.0/src/commands/blueprints/stacks.ts)_
+_See code: [src/commands/blueprints/stacks.ts](https://github.com/sanity-io/runtime-cli/blob/v12.0.0/src/commands/blueprints/stacks.ts)_
 
 ## `sanity-run functions add`
 
@@ -358,7 +356,7 @@ EXAMPLES
   $ sanity-run functions add --name my-function --type document-create --type document-update --lang js
 ```
 
-_See code: [src/commands/functions/add.ts](https://github.com/sanity-io/runtime-cli/blob/v11.2.0/src/commands/functions/add.ts)_
+_See code: [src/commands/functions/add.ts](https://github.com/sanity-io/runtime-cli/blob/v12.0.0/src/commands/functions/add.ts)_
 
 ## `sanity-run functions dev`
 
@@ -381,7 +379,7 @@ EXAMPLES
   $ sanity-run functions dev --host 127.0.0.1 --port 8974
 ```
 
-_See code: [src/commands/functions/dev.ts](https://github.com/sanity-io/runtime-cli/blob/v11.2.0/src/commands/functions/dev.ts)_
+_See code: [src/commands/functions/dev.ts](https://github.com/sanity-io/runtime-cli/blob/v12.0.0/src/commands/functions/dev.ts)_
 
 ## `sanity-run functions env add NAME KEY VALUE`
 
@@ -403,7 +401,7 @@ EXAMPLES
   $ sanity-run functions env add MyFunction API_URL https://api.example.com/
 ```
 
-_See code: [src/commands/functions/env/add.ts](https://github.com/sanity-io/runtime-cli/blob/v11.2.0/src/commands/functions/env/add.ts)_
+_See code: [src/commands/functions/env/add.ts](https://github.com/sanity-io/runtime-cli/blob/v12.0.0/src/commands/functions/env/add.ts)_
 
 ## `sanity-run functions env list NAME`
 
@@ -423,7 +421,7 @@ EXAMPLES
   $ sanity-run functions env list MyFunction
 ```
 
-_See code: [src/commands/functions/env/list.ts](https://github.com/sanity-io/runtime-cli/blob/v11.2.0/src/commands/functions/env/list.ts)_
+_See code: [src/commands/functions/env/list.ts](https://github.com/sanity-io/runtime-cli/blob/v12.0.0/src/commands/functions/env/list.ts)_
 
 ## `sanity-run functions env remove NAME KEY`
 
@@ -444,7 +442,7 @@ EXAMPLES
   $ sanity-run functions env remove MyFunction API_URL
 ```
 
-_See code: [src/commands/functions/env/remove.ts](https://github.com/sanity-io/runtime-cli/blob/v11.2.0/src/commands/functions/env/remove.ts)_
+_See code: [src/commands/functions/env/remove.ts](https://github.com/sanity-io/runtime-cli/blob/v12.0.0/src/commands/functions/env/remove.ts)_
 
 ## `sanity-run functions logs NAME`
 
@@ -478,7 +476,7 @@ EXAMPLES
   $ sanity-run functions logs <name> --delete
 ```
 
-_See code: [src/commands/functions/logs.ts](https://github.com/sanity-io/runtime-cli/blob/v11.2.0/src/commands/functions/logs.ts)_
+_See code: [src/commands/functions/logs.ts](https://github.com/sanity-io/runtime-cli/blob/v12.0.0/src/commands/functions/logs.ts)_
 
 ## `sanity-run functions test NAME`
 
@@ -527,7 +525,7 @@ EXAMPLES
   $ sanity-run functions test <name> --event update --data-before '{ "title": "before" }' --data-after '{ "title": "after" }'
 ```
 
-_See code: [src/commands/functions/test.ts](https://github.com/sanity-io/runtime-cli/blob/v11.2.0/src/commands/functions/test.ts)_
+_See code: [src/commands/functions/test.ts](https://github.com/sanity-io/runtime-cli/blob/v12.0.0/src/commands/functions/test.ts)_
 
 ## `sanity-run help [COMMAND]`
 

package/dist/actions/blueprints/blueprint.d.ts

@@ -1,6 +1,7 @@
 import { type Blueprint } from '@sanity/blueprints-parser';
 import type { BlueprintParserError, Resource } from '../../utils/types.js';
 import { type ScopeType } from '../../utils/types.js';
+import { type BlueprintsConfig } from './config.js';
 declare const SUPPORTED_FILE_EXTENSIONS: readonly [".json", ".js", ".mjs", ".ts"];
 type BlueprintFileExtension = (typeof SUPPORTED_FILE_EXTENSIONS)[number];
 export declare const JSON_BLUEPRINT_CONTENT: {
@@ -28,9 +29,11 @@ export declare function findBlueprintFile(blueprintPath?: string): FileInfo | nu
 /** Result of the blueprint read operation */
 export interface ReadBlueprintResult {
     fileInfo: FileInfo;
+    blueprintConfig: BlueprintsConfig | null;
     rawBlueprint: Record<string, unknown>;
     parsedBlueprint: Blueprint;
     errors: BlueprintParserError[];
+    /** @deprecated - use blueprintConfig.configPath instead */
     configPath?: string;
     scopeType?: ScopeType;
     scopeId?: string;

package/dist/actions/blueprints/blueprint.js

@@ -6,7 +6,7 @@ import { findUpSync } from 'find-up';
 import { createJiti } from 'jiti';
 import { isLocalFunctionResource } from '../../utils/types.js';
 import { validateFunctionResource } from '../../utils/validate/resource.js';
-import { backfillOrganizationId, readConfigFile } from './config.js';
+import { backfillOrganizationId, backfillProjectBasedStackId, readConfigFile, } from './config.js';
 const SUPPORTED_FILE_EXTENSIONS = ['.json', '.js', '.mjs', '.ts'];
 let SUPPORTED_FILE_NAMES = SUPPORTED_FILE_EXTENSIONS.map((ext) => `blueprint${ext}`);
 SUPPORTED_FILE_NAMES = [
@@ -130,13 +130,12 @@ export async function readLocalBlueprint(blueprintPath) {
         throw Error('Unable to read Blueprint');
     }
     const { SANITY_ORGANIZATION_ID: envOrganizationId, SANITY_PROJECT_ID: envProjectId, SANITY_BLUEPRINT_STACK_ID: envStackId, } = env;
-    const configIds = readConfigFile(foundFilePath);
-    const configPath = configIds?.configPath;
+    const blueprintConfig = readConfigFile(foundFilePath);
     // passively heal config on disk by getting organizationId from projectId
-    if (configIds && !configIds.organizationId && configIds.projectId) {
+    if (blueprintConfig?.projectId && !blueprintConfig.organizationId) {
         try {
             await backfillOrganizationId({
-                projectId: configIds.projectId,
+                projectId: blueprintConfig.projectId,
                 blueprintFilePath: foundFilePath,
             });
         }
@@ -147,25 +146,36 @@ export async function readLocalBlueprint(blueprintPath) {
         organizationId = envOrganizationId;
     else if (moduleOrganizationId)
         organizationId = moduleOrganizationId;
-    else if (configIds?.organizationId)
-        organizationId = configIds.organizationId;
+    else if (blueprintConfig?.organizationId)
+        organizationId = blueprintConfig.organizationId;
     let projectId;
     if (envProjectId)
         projectId = envProjectId;
     else if (moduleProjectId)
         projectId = moduleProjectId;
-    else if (configIds?.projectId)
-        projectId = configIds.projectId;
+    else if (blueprintConfig?.projectId)
+        projectId = blueprintConfig.projectId;
     let stackId;
     if (envStackId)
         stackId = envStackId;
     else if (moduleStackId)
         stackId = moduleStackId;
-    else if (configIds?.stackId)
-        stackId = configIds.stackId;
+    else if (blueprintConfig?.stackId)
+        stackId = blueprintConfig.stackId;
     // LAUNCH LIMIT: 1 Stack per Project - infer stackId from projectId
-    if (!stackId && projectId)
-        stackId = `ST-${projectId}`;
+    // this code path exists to handle project-based stacks from initial Blueprints/Functions launch
+    if (!stackId && projectId) {
+        try {
+            // try to assume project-based stack if no stackId is provided
+            stackId = await backfillProjectBasedStackId({
+                blueprintFilePath: foundFilePath,
+                projectId,
+            });
+        }
+        catch {
+            // our assumption was wrong, so we'll leave stackId undefined
+        }
+    }
     let scopeType;
     let scopeId;
     // Scope is as specific as possible; project > organization
@@ -189,6 +199,7 @@ export async function readLocalBlueprint(blueprintPath) {
     }
     return {
         fileInfo: { blueprintFilePath: foundFilePath, fileName, extension },
+        blueprintConfig,
         rawBlueprint,
         errors,
         scopeType,
@@ -196,7 +207,8 @@ export async function readLocalBlueprint(blueprintPath) {
         organizationId,
         projectId,
         stackId,
-        configPath,
+        /** @deprecated */
+        configPath: blueprintConfig?.configPath,
         // fallback to the raw blueprint if the parser found errors
         parsedBlueprint: parsedBlueprint || rawBlueprint,
     };

package/dist/actions/blueprints/config.d.ts

@@ -1,11 +1,27 @@
-export interface BlueprintsConfig {
-    configPath: string;
+import { BLUEPRINT_CONFIG_VERSION, RUNTIME_CLI_VERSION } from '../../config.js';
+export interface ConfigUpdate {
     organizationId?: string;
     projectId?: string;
     stackId?: string;
 }
+export interface BlueprintsConfig extends ConfigUpdate {
+    configPath: string;
+    blueprintConfigVersion?: typeof BLUEPRINT_CONFIG_VERSION;
+    runtimeCliVersion?: typeof RUNTIME_CLI_VERSION;
+    updatedAt?: number;
+}
 export declare function readConfigFile(blueprintFilePath?: string): BlueprintsConfig | null;
-export declare function writeConfigFile({ blueprintFilePath, organizationId, projectId, stackId, }: {
+/**
+ * Create or update the config file to disk.
+ * One of organizationId or projectId must be provided. Not both.
+ * Blueprint config version and updatedAt timestamp are set automatically.
+ * @param options - the options to write the config file
+ * @param options.blueprintFilePath - the path to the blueprint file
+ * @param options.organizationId - the organization ID
+ * @param options.projectId - the project ID
+ * @param options.stackId - the stack ID
+ */
+export declare function writeConfigFile(options: {
     blueprintFilePath?: string;
     stackId?: string;
 } & ({
@@ -15,6 +31,17 @@ export declare function writeConfigFile({ blueprintFilePath, organizationId, pro
     projectId: string;
     organizationId?: string;
 })): void;
+/**
+ * Update the config file with the given properties.
+ * Config file must already exist.
+ * Adds timestamp. No validation or transformation is performed.
+ * @param blueprintFilePath - the path to the blueprint file
+ * @param updateableProperties - the properties to update
+ * @param updateableProperties.organizationId - the organization ID
+ * @param updateableProperties.projectId - the project ID
+ * @param updateableProperties.stackId - the stack ID
+ */
+export declare function patchConfigFile(blueprintFilePath: string, updateableProperties: ConfigUpdate): void;
 /**
  * Find and write an organizationId to the config file by getting it from the projectId
  * @throws {Error} if unable to fetch project
@@ -24,3 +51,7 @@ export declare function backfillOrganizationId({ blueprintFilePath, projectId, }
     blueprintFilePath: string;
     projectId: string;
 }): Promise<string>;
+export declare function backfillProjectBasedStackId({ blueprintFilePath, projectId, }: {
+    blueprintFilePath: string;
+    projectId: string;
+}): Promise<string | undefined>;

package/dist/actions/blueprints/config.js

@@ -1,11 +1,12 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { cwd } from 'node:process';
-import config, { BLUEPRINT_CONFIG_FILE, BLUEPRINT_CONFIG_VERSION, BLUEPRINT_DIR, } from '../../config.js';
+import config, { BLUEPRINT_CONFIG_DIR, BLUEPRINT_CONFIG_FILE, BLUEPRINT_CONFIG_VERSION, RUNTIME_CLI_VERSION, } from '../../config.js';
 import { getProject } from '../sanity/projects.js';
+import { listStacks } from './stacks.js';
 export function readConfigFile(blueprintFilePath) {
     const blueprintDir = blueprintFilePath ? dirname(blueprintFilePath) : cwd();
-    const configPath = join(blueprintDir, BLUEPRINT_DIR, BLUEPRINT_CONFIG_FILE);
+    const configPath = join(blueprintDir, BLUEPRINT_CONFIG_DIR, BLUEPRINT_CONFIG_FILE);
     if (existsSync(configPath)) {
         try {
             const config = JSON.parse(readFileSync(configPath, 'utf8'));
@@ -17,22 +18,27 @@ export function readConfigFile(blueprintFilePath) {
     }
     return null;
 }
-export function writeConfigFile({ blueprintFilePath, organizationId, projectId, stackId, }) {
+/**
+ * Create or update the config file to disk.
+ * One of organizationId or projectId must be provided. Not both.
+ * Blueprint config version and updatedAt timestamp are set automatically.
+ * @param options - the options to write the config file
+ * @param options.blueprintFilePath - the path to the blueprint file
+ * @param options.organizationId - the organization ID
+ * @param options.projectId - the project ID
+ * @param options.stackId - the stack ID
+ */
+export function writeConfigFile(options) {
+    const { blueprintFilePath, organizationId, projectId, stackId } = options;
     const blueprintDir = blueprintFilePath ? dirname(blueprintFilePath) : cwd();
-    const configDir = join(blueprintDir, BLUEPRINT_DIR);
+    const configDir = join(blueprintDir, BLUEPRINT_CONFIG_DIR);
     const configPath = join(configDir, BLUEPRINT_CONFIG_FILE);
-    if (!existsSync(configDir)) {
+    if (!existsSync(configDir))
         mkdirSync(configDir, { recursive: true });
-    }
     let config = {};
-    if (existsSync(configPath)) {
-        try {
-            config = JSON.parse(readFileSync(configPath, 'utf8'));
-        }
-        catch {
-            // config broken, start fresh
-        }
-    }
+    const existingConfig = readConfigFile(configPath);
+    if (existingConfig)
+        config = existingConfig;
     if (organizationId)
         config.organizationId = organizationId;
     if (projectId)
@@ -40,9 +46,34 @@ export function writeConfigFile({ blueprintFilePath, organizationId, projectId,
     if (stackId)
         config.stackId = stackId;
     config.blueprintConfigVersion = BLUEPRINT_CONFIG_VERSION;
+    config.runtimeCliVersion = RUNTIME_CLI_VERSION;
     config.updatedAt = Date.now();
     writeFileSync(configPath, JSON.stringify(config, null, 2));
 }
+/**
+ * Update the config file with the given properties.
+ * Config file must already exist.
+ * Adds timestamp. No validation or transformation is performed.
+ * @param blueprintFilePath - the path to the blueprint file
+ * @param updateableProperties - the properties to update
+ * @param updateableProperties.organizationId - the organization ID
+ * @param updateableProperties.projectId - the project ID
+ * @param updateableProperties.stackId - the stack ID
+ */
+export function patchConfigFile(blueprintFilePath, updateableProperties) {
+    const existingConfig = readConfigFile(blueprintFilePath);
+    if (!existingConfig)
+        throw new Error('No config file found');
+    const { configPath, ...existingConfigProperties } = existingConfig;
+    const newConfig = {
+        blueprintConfigVersion: BLUEPRINT_CONFIG_VERSION, // don't overwrite the version
+        ...existingConfigProperties,
+        ...updateableProperties,
+        updatedAt: Date.now(),
+        runtimeCliVersion: RUNTIME_CLI_VERSION,
+    };
+    writeFileSync(configPath, JSON.stringify(newConfig, null, 2));
+}
 /**
  * Find and write an organizationId to the config file by getting it from the projectId
  * @throws {Error} if unable to fetch project
@@ -69,3 +100,25 @@ export async function backfillOrganizationId({ blueprintFilePath, projectId, })
     writeConfigFile({ blueprintFilePath, organizationId });
     return organizationId;
 }
+export async function backfillProjectBasedStackId({ blueprintFilePath, projectId, }) {
+    const token = config.token;
+    if (!token)
+        throw new Error('No token found');
+    const possibleStackId = `ST-${projectId}`;
+    // get stack count, if 1 and it's project-based, use it
+    const { ok, stacks, error } = await listStacks({
+        token,
+        scopeType: 'project',
+        scopeId: projectId,
+    });
+    if (!ok)
+        throw new Error(error || 'Failed to list stacks');
+    if (stacks.length === 1 &&
+        stacks[0].scopeType === 'project' &&
+        stacks[0].id === possibleStackId) {
+        // jackpot
+        writeConfigFile({ blueprintFilePath, projectId, stackId: possibleStackId });
+        return possibleStackId;
+    }
+    return undefined;
+}

package/dist/actions/blueprints/stacks.d.ts

@@ -25,12 +25,11 @@ export declare function createStack({ stackMutation, auth, }: {
     stackMutation: StackMutation;
     auth: AuthParams;
 }): Promise<CreateStackResponse>;
-export declare function createEmptyStack({ token, scopeType, scopeId, name, projectBased, }: {
+export declare function createEmptyStack({ token, scopeType, scopeId, name, }: {
     token: string;
     scopeType: ScopeType;
     scopeId: string;
     name: string;
-    projectBased?: boolean;
 }): Promise<Stack>;
 interface UpdateStackResponse {
     ok: boolean;

package/dist/actions/blueprints/stacks.js

@@ -57,7 +57,7 @@ export async function createStack({ stackMutation, auth, }) {
     const response = await fetch(stacksUrl, {
         method: 'POST',
         headers: getHeaders(auth),
-        body: JSON.stringify(stackMutation),
+        body: JSON.stringify({ ...stackMutation, useProjectBasedId: false }), // API defaults to true as of 2025-11-26
     });
     const data = await response.json();
     return {
@@ -66,12 +66,11 @@ export async function createStack({ stackMutation, auth, }) {
         stack: response.ok ? flattenStackResources(data) : data,
     };
 }
-export async function createEmptyStack({ token, scopeType, scopeId, name, projectBased = true, }) {
+export async function createEmptyStack({ token, scopeType, scopeId, name, }) {
     const stackMutation = {
         name,
         scopeType,
         scopeId,
-        useProjectBasedId: projectBased,
         document: { resources: [] },
     };
     const response = await createStack({

package/dist/commands/blueprints/config.d.ts

@@ -3,7 +3,6 @@ export default class ConfigCommand extends BlueprintCommand<typeof ConfigCommand
     static description: string;
     static examples: string[];
     static flags: {
-        'test-config': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         edit: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'project-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'organization-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/dist/commands/blueprints/config.js

@@ -5,36 +5,28 @@ export default class ConfigCommand extends BlueprintCommand {
     static description = 'View or edit Blueprint configuration';
     static examples = [
         '<%= config.bin %> <%= command.id %>',
-        '<%= config.bin %> <%= command.id %> --test-config',
         '<%= config.bin %> <%= command.id %> --edit',
         '<%= config.bin %> <%= command.id %> --edit --project-id <projectId>',
         '<%= config.bin %> <%= command.id %> --edit --project-id <projectId> --stack-id <stackId>',
     ];
     static flags = {
-        'test-config': Flags.boolean({
-            char: 't',
-            aliases: ['test', 'validate'],
-            description: 'Validate the configuration',
-            default: false,
-            deprecated: true,
-        }),
         edit: Flags.boolean({
             char: 'e',
-            description: 'Edit the configuration',
+            description: 'Modify the configuration interactively, or directly when combined with ID flags.',
             default: false,
         }),
         'project-id': Flags.string({
-            description: 'Update the Project ID in the configuration. Requires --edit flag',
+            description: 'Directly set the Project ID in the configuration. Requires --edit flag',
             aliases: ['project', 'projectId'],
             dependsOn: ['edit'],
         }),
         'organization-id': Flags.string({
-            description: 'Update the Organization ID in the configuration. Requires --edit flag',
+            description: 'Directly set the Organization ID in the configuration. Requires --edit flag',
             aliases: ['organization', 'organizationId', 'org'],
             dependsOn: ['edit'],
         }),
         'stack-id': Flags.string({
-            description: 'Update the Stack ID in the configuration. Requires --edit flag',
+            description: 'Directly set the Stack ID in the configuration. Requires --edit flag',
             aliases: ['stack', 'stackId'],
             dependsOn: ['edit'],
         }),

package/dist/commands/blueprints/deploy.js

@@ -9,7 +9,7 @@ export default class DeployCommand extends DeployedBlueprintCommand {
     ];
     static flags = {
         'no-wait': Flags.boolean({
-            description: 'Do not wait for deployment to complete',
+            description: 'Do not wait for Stack deployment to complete',
             default: false,
         }),
     };