@sanity/runtime-cli 14.11.0 → 14.12.1

package/dist/actions/blueprints/blueprint.js

@@ -1,13 +1,14 @@
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { basename, dirname, extname } from 'node:path';
-import { cwd, env } from 'node:process';
+import { cwd } from 'node:process';
 import { pathToFileURL } from 'node:url';
 import blueprintParserValidator from '@sanity/blueprints-parser';
 import * as find from 'empathic/find';
 import { createJiti } from 'jiti';
 import { SANITY_FUNCTION_DOCUMENT, SANITY_FUNCTION_MEDIA_LIBRARY_ASSET, SANITY_FUNCTION_SCHEDULED, } from '../../constants.js';
 import { validateResources } from '../../utils/validate/index.js';
-import { backfillOrganizationId, backfillProjectBasedStackId, readConfigFile, } from './config.js';
+import { backfillProjectBasedStackId, readConfigFile, } from './config.js';
+import { resolveIds } from './resolve.js';
 const SUPPORTED_FILE_EXTENSIONS = ['.json', '.js', '.mjs', '.ts'];
 let SUPPORTED_FILE_NAMES = SUPPORTED_FILE_EXTENSIONS.map((ext) => `blueprint${ext}`);
 SUPPORTED_FILE_NAMES = [
@@ -29,7 +30,6 @@ export default defineBlueprint({
 `.trim();
 /**
  * Finds the blueprint file in the given path or current working directory
- * @param blueprintPath - The path of the blueprint file or directory
  * @returns The path, file name, and extension of the blueprint file
  */
 export function findBlueprintFile(blueprintPath) {
@@ -60,38 +60,29 @@ export function findBlueprintFile(blueprintPath) {
     };
 }
 /**
- * Reads the blueprint file from disk and parses it.
- * Overrides config file values with shell environment variables.
- * Can infer stackId from projectId if no stackId is provided and legacy ST-<projectId> stacks from launch are used.
- *
- * @param logger The logger instance
- * @param validate Validation options
- * @param blueprintPath - The path of the blueprint file or directory- will search up the directory tree!
- * @returns Known information about the Blueprint, config, and Stack
+ * Load a blueprint file from disk: read JSON or import+execute a JS/TS module.
+ * Returns the raw blueprint data and the module reference (if dynamic).
  */
-export async function readLocalBlueprint(logger, validate, blueprintPath) {
-    const blueprintFile = findBlueprintFile(blueprintPath);
-    if (!blueprintFile)
-        throw Error('Could not find Blueprint file! Use the `blueprints init` command.');
-    const { blueprintFilePath: foundFilePath, fileName, extension } = blueprintFile;
+export async function loadBlueprintFile(fileInfo) {
+    const { blueprintFilePath, fileName, extension } = fileInfo;
     let rawBlueprint;
     let blueprintModule;
     try {
         switch (extension) {
             case '.json': {
-                const blueprintString = readFileSync(foundFilePath, 'utf8').toString();
+                const blueprintString = readFileSync(blueprintFilePath, 'utf8').toString();
                 rawBlueprint = JSON.parse(blueprintString);
                 break;
             }
             case '.js':
             case '.mjs': {
-                const module = await import(foundFilePath);
-                blueprintModule = module.default;
+                const mod = await import(blueprintFilePath);
+                blueprintModule = mod.default;
                 break;
             }
             case '.ts': {
-                const jiti = createJiti(dirname(foundFilePath));
-                const modDefault = await jiti.import(pathToFileURL(foundFilePath).href, { default: true });
+                const jiti = createJiti(dirname(blueprintFilePath));
+                const modDefault = await jiti.import(pathToFileURL(blueprintFilePath).href, { default: true });
                 blueprintModule = modDefault;
                 break;
             }
@@ -102,22 +93,10 @@ export async function readLocalBlueprint(logger, validate, blueprintPath) {
     catch (err) {
         throw Error(`Unable to parse Blueprint file: ${fileName}\n${err}`);
     }
-    /**
-     * Org, Project, Stack IDs can be set...
-     * - in the environment,
-     * - on the blueprint module,
-     * - and in the config file.
-     * The precedence is: environment > blueprint module > config file
-     */
-    let moduleOrganizationId;
-    let moduleProjectId;
-    let moduleStackId;
+    // Dynamic modules: extract attached properties, then execute to get raw blueprint
     if (blueprintModule) {
         if (typeof blueprintModule === 'function') {
             try {
-                moduleOrganizationId = blueprintModule.organizationId;
-                moduleProjectId = blueprintModule.projectId;
-                moduleStackId = blueprintModule.stackId;
                 rawBlueprint = blueprintModule();
             }
             catch {
@@ -131,89 +110,14 @@ export async function readLocalBlueprint(logger, validate, blueprintPath) {
     if (typeof rawBlueprint === 'undefined') {
         throw Error('Unable to read Blueprint');
     }
-    const { SANITY_ORGANIZATION_ID: envOrganizationId, SANITY_PROJECT_ID: envProjectId, SANITY_BLUEPRINT_STACK_ID: envStackId, } = env;
-    const blueprintConfig = readConfigFile(foundFilePath);
-    // passively heal config on disk by getting organizationId from projectId
-    if (blueprintConfig?.projectId && !blueprintConfig.organizationId) {
-        try {
-            await backfillOrganizationId({
-                projectId: blueprintConfig.projectId,
-                blueprintFilePath: foundFilePath,
-                logger,
-            });
-        }
-        catch { }
-    }
-    const sources = {};
-    let organizationId;
-    if (envOrganizationId) {
-        organizationId = envOrganizationId;
-        sources.organizationId = 'env';
-    }
-    else if (moduleOrganizationId) {
-        organizationId = moduleOrganizationId;
-        sources.organizationId = 'module';
-    }
-    else if (blueprintConfig?.organizationId) {
-        organizationId = blueprintConfig.organizationId;
-        sources.organizationId = 'config';
-    }
-    let projectId;
-    if (envProjectId) {
-        projectId = envProjectId;
-        sources.projectId = 'env';
-    }
-    else if (moduleProjectId) {
-        projectId = moduleProjectId;
-        sources.projectId = 'module';
-    }
-    else if (blueprintConfig?.projectId) {
-        projectId = blueprintConfig.projectId;
-        sources.projectId = 'config';
-    }
-    let stackId;
-    if (envStackId) {
-        stackId = envStackId;
-        sources.stackId = 'env';
-    }
-    else if (moduleStackId) {
-        stackId = moduleStackId;
-        sources.stackId = 'module';
-    }
-    else if (blueprintConfig?.stackId) {
-        stackId = blueprintConfig.stackId;
-        sources.stackId = 'config';
-    }
-    // LAUNCH LIMIT: 1 Stack per Project - infer stackId from 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,
-                logger,
-            });
-            if (stackId)
-                sources.stackId = 'inferred';
-        }
-        catch {
-            // our assumption was wrong, so we'll leave stackId undefined
-        }
-    }
-    let scopeType;
-    let scopeId;
-    // Scope is as specific as possible; project > organization
-    if (projectId) {
-        scopeType = 'project';
-        scopeId = projectId;
-    }
-    else if (organizationId) {
-        scopeType = 'organization';
-        scopeId = organizationId;
-    }
+    return { rawBlueprint, module: blueprintModule };
+}
+/**
+ * Run the blueprint parser/validator on raw blueprint data.
+ * Optionally validates function resources.
+ */
+export function parseBlueprintContent(rawBlueprint, options) {
     const parserResult = blueprintParserValidator(rawBlueprint, {
-        // Prevents the following resources from being referenced.
         invalidReferenceTypes: [
             SANITY_FUNCTION_DOCUMENT,
             SANITY_FUNCTION_MEDIA_LIBRARY_ASSET,
@@ -222,34 +126,88 @@ export async function readLocalBlueprint(logger, validate, blueprintPath) {
     });
     const parsedBlueprint = parserResult.result === 'valid' ? parserResult.blueprint : undefined;
     const errors = parserResult.result !== 'valid' ? parserResult.errors : [];
-    // resource validation
-    if (parsedBlueprint?.resources) {
-        if (validate?.resources) {
-            // validate function resources
-            errors.push(...validateResources(parsedBlueprint.resources));
-        }
+    if (parsedBlueprint?.resources && options.validateResources) {
+        errors.push(...validateResources(parsedBlueprint.resources));
     }
-    // Ceremony to cross from parser's Resource type to BlueprintResource
-    // widen from the parser's Resource type assignable to BlueprintResource
+    // Widen from the parser's Resource type to BlueprintResource
     const parserResources = parsedBlueprint?.resources ?? [];
-    // filter to valid resources typed as BlueprintResource
-    const validResources = parserResources.filter((r) => !!r.type);
+    const resources = parserResources.filter((r) => !!r.type);
     return {
-        fileInfo: { blueprintFilePath: foundFilePath, fileName, extension },
+        parsedBlueprint: parsedBlueprint || rawBlueprint,
+        errors,
+        resources,
+    };
+}
+/**
+ * Find, load, and parse a local blueprint file in one step.
+ * Does not read the config file or resolve IDs -- callers that need
+ * scope/stack information should use `readConfigFile` + `resolveIds` separately.
+ *
+ * @param blueprintPath Path to a blueprint file or directory containing one
+ * @param options.validateResources Whether to validate function resources
+ */
+export async function loadAndParseBlueprint(blueprintPath, options = { validateResources: true }) {
+    const fileInfo = findBlueprintFile(blueprintPath);
+    if (!fileInfo)
+        throw Error('Could not find Blueprint file! Use the `blueprints init` command.');
+    const loaded = await loadBlueprintFile(fileInfo);
+    const parsed = parseBlueprintContent(loaded.rawBlueprint, options);
+    return {
+        fileInfo,
+        rawBlueprint: loaded.rawBlueprint,
+        module: loaded.module,
+        ...parsed,
+    };
+}
+/**
+ * Reads the blueprint file from disk and parses it.
+ * Resolves IDs from environment > blueprint module > config file.
+ * Can infer stackId from projectId for legacy ST-<projectId> stacks.
+ * @see {@link loadBlueprintFile} {@link readConfigFile} {@link resolveIds} {@link parseBlueprintContent}
+ * @todo deprecate in favor of decomposed functions
+ * @returns Known information about the Blueprint, config, and Stack
+ */
+export async function readLocalBlueprint(logger, validate, blueprintPath) {
+    const fileInfo = findBlueprintFile(blueprintPath);
+    if (!fileInfo)
+        throw Error('Could not find Blueprint file! Use the `blueprints init` command.');
+    // 1. Load blueprint from disk
+    const loaded = await loadBlueprintFile(fileInfo);
+    const { rawBlueprint } = loaded;
+    // 2. Read the config file
+    const blueprintConfig = readConfigFile(fileInfo.blueprintFilePath);
+    // 3. Resolve IDs: env > module > config
+    const resolved = resolveIds({
+        module: loaded.module,
+        config: blueprintConfig,
+    });
+    // 4. Legacy stack ID inference: ST-<projectId>
+    let { stackId } = resolved;
+    if (!stackId && resolved.projectId) {
+        try {
+            stackId = await backfillProjectBasedStackId({
+                blueprintFilePath: fileInfo.blueprintFilePath,
+                projectId: resolved.projectId,
+                logger,
+            });
+            if (stackId)
+                resolved.sources.stackId = 'inferred';
+        }
+        catch {
+            // assumption was wrong; leave stackId undefined
+        }
+    }
+    // 5. Parse + validate blueprint content
+    const parsed = parseBlueprintContent(rawBlueprint, {
+        validateResources: validate.resources,
+    });
+    return {
+        fileInfo,
         blueprintConfig,
         rawBlueprint,
-        resources: validResources,
-        errors,
-        scopeType,
-        scopeId,
-        organizationId,
-        projectId,
-        stackId,
-        sources,
-        /** @deprecated */
-        configPath: blueprintConfig?.configPath,
-        // fallback to the raw blueprint if the parser found errors
-        parsedBlueprint: parsedBlueprint || rawBlueprint,
+        ...parsed,
+        ...resolved,
+        stackId: stackId ?? resolved.stackId,
     };
 }
 export function writeBlueprintToDisk({ blueprintFilePath, jsonContent = JSON_BLUEPRINT_CONTENT, }) {

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

@@ -0,0 +1,51 @@
+import type { ScopeType } from '../../utils/types.js';
+/**
+ * Source of a resolved config value.
+ * - flags: from CLI flags like `--project-id`
+ * - env: from the environment - usually CLI var like `SANITY_ORGANIZATION_ID`
+ * - module: from the blueprint module - undocumented escape hatch
+ * - config: from the config file - .sanity/blueprint.config.json most common
+ * - inferred: legacy `ST-<projectId>` stacks from launch
+ */
+export type ConfigSource = 'flags' | 'env' | 'module' | 'config' | 'inferred';
+/** A set of optional IDs from a single source. */
+export interface IdValues {
+    organizationId?: string;
+    projectId?: string;
+    stackId?: string;
+}
+/**
+ * Sources to resolve IDs from, in descending priority.
+ * Each key maps to a source; the first non-empty value wins.
+ *
+ * - `env` defaults to reading SANITY_* process.env vars
+ * - `module` and `config` accept any object with `{organizationId?, projectId?, stackId?}`
+ */
+export interface IdSources {
+    flags?: IdValues | null;
+    env?: IdValues | null;
+    module?: IdValues | null;
+    config?: IdValues | null;
+}
+export interface ResolvedIds {
+    organizationId?: string;
+    projectId?: string;
+    stackId?: string;
+    scopeType?: ScopeType;
+    scopeId?: string;
+    sources: {
+        organizationId?: ConfigSource;
+        projectId?: ConfigSource;
+        stackId?: ConfigSource;
+    };
+}
+/**
+ * Resolve organization, project, and stack IDs from a prioritized set of sources.
+ * Precedence: flags > env > module > config.
+ * Derives scopeType/scopeId from the resolved IDs (project > organization).
+ *
+ * Env vars are read from process.env by default (SANITY_ORGANIZATION_ID,
+ * SANITY_PROJECT_ID, SANITY_BLUEPRINT_STACK_ID). Pass `env` explicitly to
+ * override, or `null` to skip.
+ */
+export declare function resolveIds(sources?: IdSources): ResolvedIds;

package/dist/actions/blueprints/resolve.js

@@ -0,0 +1,52 @@
+import { env as processEnv } from 'node:process';
+/**
+ * Resolve organization, project, and stack IDs from a prioritized set of sources.
+ * Precedence: flags > env > module > config.
+ * Derives scopeType/scopeId from the resolved IDs (project > organization).
+ *
+ * Env vars are read from process.env by default (SANITY_ORGANIZATION_ID,
+ * SANITY_PROJECT_ID, SANITY_BLUEPRINT_STACK_ID). Pass `env` explicitly to
+ * override, or `null` to skip.
+ */
+export function resolveIds(sources = {}) {
+    const envValues = sources.env !== undefined
+        ? sources.env
+        : {
+            organizationId: processEnv.SANITY_ORGANIZATION_ID,
+            projectId: processEnv.SANITY_PROJECT_ID,
+            stackId: processEnv.SANITY_BLUEPRINT_STACK_ID,
+        };
+    const ordered = [
+        { source: 'flags', values: sources.flags },
+        { source: 'env', values: envValues },
+        { source: 'module', values: sources.module },
+        { source: 'config', values: sources.config },
+    ];
+    const result = { sources: {} };
+    for (const { source, values } of ordered) {
+        if (values === null || values === undefined)
+            continue;
+        if (!result.organizationId && values.organizationId) {
+            result.organizationId = values.organizationId;
+            result.sources.organizationId = source;
+        }
+        if (!result.projectId && values.projectId) {
+            result.projectId = values.projectId;
+            result.sources.projectId = source;
+        }
+        if (!result.stackId && values.stackId) {
+            result.stackId = values.stackId;
+            result.sources.stackId = source;
+        }
+    }
+    // Scope is as specific as possible; project > organization
+    if (result.projectId) {
+        result.scopeType = 'project';
+        result.scopeId = result.projectId;
+    }
+    else if (result.organizationId) {
+        result.scopeType = 'organization';
+        result.scopeId = result.organizationId;
+    }
+    return result;
+}

package/dist/actions/blueprints/resources.js

@@ -2,6 +2,7 @@ import { spawn } from 'node:child_process';
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { cwd } from 'node:process';
+import { MAP_EVENT_TO_FUNCTION_TYPE, SANITY_FUNCTION_DOCUMENT, SANITY_FUNCTION_MEDIA_LIBRARY_ASSET, SANITY_FUNCTION_SCHEDULED, SANITY_FUNCTION_SYNC_TAG_INVALIDATE, } from '../../constants.js';
 import { styleText } from '../../utils/style-text.js';
 import { writeOrUpdateNodeDependency } from '../node.js';
 import { addResourceToBlueprint } from './blueprint.js';
@@ -21,6 +22,20 @@ export const handler = scheduledEventHandler(async ({ context }) => {
   const time = new Date().toLocaleTimeString()
   console.log(\`Your scheduled Sanity Function was called at \${time}\`)
 })`;
+const DEFAULT_SYNC_TAG_HELPER_FUNCTION_TEMPLATE = /*ts*/ `import { syncTagInvalidateEventHandler } from '@sanity/functions'
+
+export const handler = syncTagInvalidateEventHandler(async ({ context, event, done }) => {
+  const time = new Date().toLocaleTimeString()
+  console.log(\`Your sync tag invalidate Sanity Function was called at \${time}\`)
+  // TODO: add code to do something with the invalidated sync tags provided to you in \`event.data.syncTags\`
+  try {
+    // notify Sanity that you have completed invalidation
+    const response = await done(event.data.syncTags)
+    console.log('Invalidation complete, Sanity responded with an HTTP', response.status)
+  } catch (e) {
+    console.error('Error invoking Sanity invalidation done endpoint!', e)
+  }
+})`;
 /**
  * Creates a new function resource file and adds it to the blueprint
  */
@@ -47,16 +62,18 @@ export async function createFunctionResource(options, logger) {
         throw Error(`Unsupported language: ${lang}`);
     // type looks like 'document-publish', 'media-library-asset-delete' or 'scheduled-function'
     // and we are guaranteed to have the same leading words (typeName below) for all provided type strings (via guards in the call site for this method).
-    // TODO: this substring convention is brittle - consider mapping EVENT_* constants to typeName values explicitly instead of relying on string splitting.
-    const typeName = type[0].substring(0, type[0].lastIndexOf('-'));
+    const functionType = MAP_EVENT_TO_FUNCTION_TYPE[type[0]];
     // Create index.<lang> with default template
     const indexPath = join(functionDir, `index.${lang}`);
     let template = DEFAULT_FUNCTION_TEMPLATE;
     if (addHelpers) {
-        switch (typeName) {
-            case 'scheduled':
+        switch (functionType) {
+            case SANITY_FUNCTION_SCHEDULED:
                 template = DEFAULT_SCHEDULED_HELPER_FUNCTION_TEMPLATE;
                 break;
+            case SANITY_FUNCTION_SYNC_TAG_INVALIDATE:
+                template = DEFAULT_SYNC_TAG_HELPER_FUNCTION_TEMPLATE;
+                break;
             default:
                 template = DEFAULT_HELPER_FUNCTION_TEMPLATE;
                 break;
@@ -80,39 +97,45 @@ export async function createFunctionResource(options, logger) {
     const eventsOn = type.map((t) => t.substring(t.lastIndexOf('-') + 1));
     // Create resource definition
     let resourceJson;
-    switch (typeName) {
-        case 'document':
+    switch (functionType) {
+        case SANITY_FUNCTION_DOCUMENT:
             resourceJson = {
                 name,
                 src: `functions/${name}`,
-                type: 'sanity.function.document',
+                type: SANITY_FUNCTION_DOCUMENT,
                 event: {
                     on: eventsOn,
                 },
             };
             break;
-        case 'media-library-asset':
+        case SANITY_FUNCTION_MEDIA_LIBRARY_ASSET:
             resourceJson = {
                 name,
                 src: `functions/${name}`,
-                type: 'sanity.function.media-library.asset',
+                type: SANITY_FUNCTION_MEDIA_LIBRARY_ASSET,
                 event: {
                     on: eventsOn,
                     resource: { type: 'media-library', id: 'my-media-library-id' },
                 },
             };
             break;
-        case 'scheduled':
+        case SANITY_FUNCTION_SCHEDULED:
             resourceJson = {
                 name,
                 src: `functions/${name}`,
-                type: 'sanity.function.cron',
+                type: SANITY_FUNCTION_SCHEDULED,
                 event: {
                     expression: '0 0 * * *',
                 },
             };
             break;
-        // TODO: add sync tag invalidate funx
+        case SANITY_FUNCTION_SYNC_TAG_INVALIDATE:
+            resourceJson = {
+                name,
+                src: `functions/${name}`,
+                type: SANITY_FUNCTION_SYNC_TAG_INVALIDATE,
+            };
+            break;
     }
     if (!resourceJson) {
         throw new Error('Could not create function resource based on selections');

package/dist/actions/functions/dev.d.ts

@@ -1,3 +1,2 @@
-import type { Logger } from '../../utils/logger.js';
 import type { InvokeExecutionOptions } from '../../utils/types.js';
-export declare function dev(host: string, port: number, logger: Logger, validateResources: boolean, executionOptions?: Partial<InvokeExecutionOptions>): Promise<void>;
+export declare function dev(host: string, port: number, validateResources: boolean, executionOptions?: Partial<InvokeExecutionOptions>): Promise<void>;

package/dist/actions/functions/dev.js

@@ -1,4 +1,4 @@
 import { app } from '../../server/app.js';
-export async function dev(host, port, logger, validateResources, executionOptions) {
-    app(host, Number(port), logger, validateResources, executionOptions);
+export async function dev(host, port, validateResources, executionOptions) {
+    app(host, Number(port), validateResources, executionOptions);
 }

package/dist/baseCommands.d.ts

@@ -1,10 +1,16 @@
 import type { Interfaces } from '@oclif/core';
 import { Command } from '@oclif/core';
-import type { ReadBlueprintResult } from './actions/blueprints/blueprint.js';
+import { type ReadBlueprintResult } from './actions/blueprints/blueprint.js';
 import type { CoreResult } from './cores/index.js';
 import type { AuthParams, ScopeType, Stack } from './utils/types.js';
 export type Flags<T extends typeof Command> = Interfaces.InferredFlags<(typeof RuntimeCommand)['baseFlags'] & T['flags']>;
 export type Args<T extends typeof Command> = Interfaces.InferredArgs<T['args']>;
+export declare const pathFlagConfig: {
+    description: string;
+    env: string;
+    aliases: string[];
+    char: "p";
+};
 export declare const baseFlags: {
     json: Interfaces.BooleanFlag<boolean>;
     path: Interfaces.OptionFlag<string | undefined, Interfaces.CustomOptions>;
@@ -12,7 +18,9 @@ export declare const baseFlags: {
     'validate-resources': Interfaces.BooleanFlag<boolean>;
     verbose: Interfaces.BooleanFlag<boolean>;
 };
-export declare const stackFlag: Interfaces.OptionFlag<string | undefined, Interfaces.CustomOptions>;
+export declare const stackFlagConfig: {
+    description: string;
+};
 export declare const projectIdFlagConfig: {
     description: string;
     aliases: string[];
@@ -21,11 +29,6 @@ export declare const organizationIdFlagConfig: {
     description: string;
     aliases: string[];
 };
-/**
- * Unhides a flag by setting its hidden property to false
- * Also makes oclif's types happy when destructuring the flag
- */
-export declare function unhide<T>(flag: T): T;
 /**
  * Guarantees flags and args.
  * Also centralizes baseFlags and enables oclif's built-in --json for all subclasses.
@@ -69,40 +72,54 @@ export declare abstract class RuntimeCommand<T extends typeof Command> extends C
     }): Promise<unknown>;
 }
 /**
- * Guarantees flags, args, sanityToken, and blueprint.
- * Blueprint parser errors are logged and the command exits with an error
+ * Context a command can declare it needs.
+ * The base class resolves each from the best available source during init().
+ * Dependencies are resolved implicitly -- declaring 'deployedStack' implies
+ * token, scope, and stackId without listing them.
+ *
+ * - token:         Authenticated API token
+ * - blueprint:     Parsed local blueprint file (filesystem)
+ * - scope:         scopeType + scopeId (from flags, env, config file, or blueprint)
+ * - stackId:       stackId (from flags, env, config file, blueprint, or inferred)
+ * - deployedStack: Remote Stack object fetched from the API (implies token, scope, stackId)
+ */
+export type Need = 'token' | 'blueprint' | 'scope' | 'stackId' | 'deployedStack';
+/**
+ * Base command that resolves context declaratively from a `static needs` array.
+ * Commands declare what they *directly use*; the base class resolves transitive
+ * dependencies automatically (e.g. 'deployedStack' implies token, scope, stackId).
+ *
+ * When a command needs only remote context (e.g. `['deployedStack']`),
+ * no local blueprint file is required -- flags and config are sufficient.
+ *
+ * @example
+ * ```ts
+ * class InfoCommand extends ResolvedCommand<typeof InfoCommand> {
+ *   static needs = ['deployedStack'] as const
+ *   // token, scope, stackId resolved automatically
+ * }
+ * ```
+ *
  * @extends RuntimeCommand
  */
-export declare abstract class LocalBlueprintCommand<T extends typeof Command> extends RuntimeCommand<T> {
-    protected sanityToken: string;
-    protected blueprint: ReadBlueprintResult;
+export declare abstract class ResolvedCommand<T extends typeof Command> extends RuntimeCommand<T> {
+    static needs: readonly Need[];
     static baseFlags: {
+        stack: Interfaces.OptionFlag<string | undefined, Interfaces.CustomOptions>;
+        'project-id': Interfaces.OptionFlag<string | undefined, Interfaces.CustomOptions>;
+        'organization-id': Interfaces.OptionFlag<string | undefined, Interfaces.CustomOptions>;
         json: Interfaces.BooleanFlag<boolean>;
         path: Interfaces.OptionFlag<string | undefined, Interfaces.CustomOptions>;
         trace: Interfaces.BooleanFlag<boolean>;
         'validate-resources': Interfaces.BooleanFlag<boolean>;
         verbose: Interfaces.BooleanFlag<boolean>;
     };
-    init(): Promise<void>;
-}
-/**
- * Guarantees flags, args, sanityToken, blueprint, scopeType, scopeId, stackId, auth, and deployedStack.
- * If scope or stack is missing, the command exits with an error
- * @extends LocalBlueprintCommand
- */
-export declare abstract class DeployedStackCommand<T extends typeof Command> extends LocalBlueprintCommand<T> {
-    protected auth: AuthParams;
-    protected deployedStack: Stack;
+    protected sanityToken: string;
+    protected blueprint: ReadBlueprintResult;
     protected scopeType: ScopeType;
     protected scopeId: string;
     protected stackId: string;
-    static baseFlags: {
-        stack: Interfaces.OptionFlag<string | undefined, Interfaces.CustomOptions>;
-        json: Interfaces.BooleanFlag<boolean>;
-        path: Interfaces.OptionFlag<string | undefined, Interfaces.CustomOptions>;
-        trace: Interfaces.BooleanFlag<boolean>;
-        'validate-resources': Interfaces.BooleanFlag<boolean>;
-        verbose: Interfaces.BooleanFlag<boolean>;
-    };
+    protected auth: AuthParams;
+    protected deployedStack: Stack;
     init(): Promise<void>;
 }