@sanity/runtime-cli 17.1.0-next.gcfbd613 → 17.2.0-blueprinit.g62f8017

package/dist/actions/blueprinit/templates.d.ts

@@ -0,0 +1,34 @@
+export declare function renderStudioConfig(options: {
+    displayName: string;
+    projectId: string;
+    datasetName: string;
+}): string;
+export declare const STUDIO_SCHEMA_TYPES = "import {post} from './post'\n\nexport const schemaTypes = [post]\n";
+export declare const STUDIO_POST_TYPE = "import {defineField, defineType} from 'sanity'\n\nexport const post = defineType({\n  name: 'post',\n  title: 'Post',\n  type: 'document',\n  fields: [\n    defineField({name: 'title', type: 'string', validation: (rule) => rule.required()}),\n    // The set-slug function fills this when it is empty.\n    defineField({name: 'slug', type: 'slug', options: {source: 'title'}}),\n    defineField({name: 'publishedAt', title: 'Published at', type: 'datetime'}),\n    defineField({name: 'body', type: 'text'}),\n  ],\n})\n";
+export declare const FUNCTION_SET_SLUG = "import {createClient} from '@sanity/client'\nimport {documentEventHandler} from '@sanity/functions'\n\nconst slugify = (title: string) =>\n  title\n    .toLowerCase()\n    .replace(/[^a-z0-9]+/g, '-')\n    .replace(/^-+|-+$/g, '')\n    .slice(0, 96)\n\nexport const handler = documentEventHandler(async ({context, event}) => {\n  const {_id, title, slug} = event.data\n  if (!title || slug?.current) return\n\n  const client = createClient({apiVersion: '2025-05-01', ...context.clientOptions})\n  const current = slugify(title)\n  await client.patch(_id).set({slug: {_type: 'slug', current}}).commit()\n\n  console.log(`Set slug for ${_id}: ${current}`)\n})\n";
+export declare const studioPackageJson: (name: string) => {
+    name: string;
+    version: string;
+    private: boolean;
+    scripts: {
+        dev: string;
+        build: string;
+        deploy: string;
+    };
+    dependencies: {
+        react: string;
+        'react-dom': string;
+        sanity: string;
+        'styled-components': string;
+    };
+};
+export declare const functionPackageJson: (name: string) => {
+    name: string;
+    version: string;
+    private: boolean;
+    type: string;
+    dependencies: {
+        '@sanity/client': string;
+        '@sanity/functions': string;
+    };
+};

package/dist/actions/blueprinit/templates.js

@@ -0,0 +1,83 @@
+import { STARTER_DOCUMENT_TYPE, STARTER_FUNCTION_NAME } from './manifest.js';
+const quote = (value) => `'${value.replaceAll('\\', '\\\\').replaceAll("'", "\\'")}'`;
+export function renderStudioConfig(options) {
+    return `import {defineConfig} from 'sanity'
+import {structureTool} from 'sanity/structure'
+import {schemaTypes} from './schemaTypes'
+
+export default defineConfig({
+  name: 'default',
+  title: ${quote(options.displayName)},
+  projectId: ${quote(options.projectId)},
+  dataset: ${quote(options.datasetName)},
+  plugins: [structureTool()],
+  schema: {types: schemaTypes},
+})
+`;
+}
+export const STUDIO_SCHEMA_TYPES = `import {post} from './post'
+
+export const schemaTypes = [post]
+`;
+export const STUDIO_POST_TYPE = `import {defineField, defineType} from 'sanity'
+
+export const post = defineType({
+  name: '${STARTER_DOCUMENT_TYPE}',
+  title: 'Post',
+  type: 'document',
+  fields: [
+    defineField({name: 'title', type: 'string', validation: (rule) => rule.required()}),
+    // The ${STARTER_FUNCTION_NAME} function fills this when it is empty.
+    defineField({name: 'slug', type: 'slug', options: {source: 'title'}}),
+    defineField({name: 'publishedAt', title: 'Published at', type: 'datetime'}),
+    defineField({name: 'body', type: 'text'}),
+  ],
+})
+`;
+export const FUNCTION_SET_SLUG = `import {createClient} from '@sanity/client'
+import {documentEventHandler} from '@sanity/functions'
+
+const slugify = (title: string) =>
+  title
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 96)
+
+export const handler = documentEventHandler(async ({context, event}) => {
+  const {_id, title, slug} = event.data
+  if (!title || slug?.current) return
+
+  const client = createClient({apiVersion: '2025-05-01', ...context.clientOptions})
+  const current = slugify(title)
+  await client.patch(_id).set({slug: {_type: 'slug', current}}).commit()
+
+  console.log(\`Set slug for \${_id}: \${current}\`)
+})
+`;
+export const studioPackageJson = (name) => ({
+    name,
+    version: '0.1.0',
+    private: true,
+    scripts: {
+        dev: 'sanity dev',
+        build: 'sanity build',
+        deploy: 'sanity deploy',
+    },
+    dependencies: {
+        react: '^19',
+        'react-dom': '^19',
+        sanity: '^4',
+        'styled-components': '^6',
+    },
+});
+export const functionPackageJson = (name) => ({
+    name,
+    version: '0.1.0',
+    private: true,
+    type: 'module',
+    dependencies: {
+        '@sanity/client': '^7',
+        '@sanity/functions': '^1',
+    },
+});

package/dist/actions/blueprinit/workspace.d.ts

@@ -0,0 +1,15 @@
+export interface WorkspaceOptions {
+    dir: string;
+    projectId: string;
+    displayName: string;
+    datasetName: string;
+    stackName: string;
+    studioName: string;
+    blueprintsVersion: string;
+}
+export interface WorkspaceResult {
+    blueprintFilePath: string;
+    files: string[];
+}
+export declare function scaffoldWorkspace(options: WorkspaceOptions): WorkspaceResult;
+export declare function adoptWorkspace(options: WorkspaceOptions): WorkspaceResult;

package/dist/actions/blueprinit/workspace.js

@@ -0,0 +1,142 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, posix } from 'node:path';
+import { renderBlueprint, STARTER_FUNCTION_NAME } from './manifest.js';
+import { FUNCTION_SET_SLUG, functionPackageJson, renderStudioConfig, STUDIO_POST_TYPE, STUDIO_SCHEMA_TYPES, studioPackageJson, } from './templates.js';
+const GITIGNORE_ENTRY = '# Sanity Blueprints\n.sanity/';
+const DEFAULT_GITIGNORE = `node_modules
+.env
+
+${GITIGNORE_ENTRY}
+`;
+export function scaffoldWorkspace(options) {
+    const { dir, studioName } = options;
+    assertTargetsAvailable(dir, [
+        posix.join('studios', studioName),
+        posix.join('functions', STARTER_FUNCTION_NAME),
+    ]);
+    const packageJson = preparePackageJson(options, ['studios/*', 'functions/*']);
+    const files = [];
+    const write = createWriter(dir, files);
+    const blueprintFilePath = write('sanity.blueprint.ts', renderBlueprint({
+        ...manifestOptions(options),
+        studioSrc: `./studios/${studioName}`,
+        withFunction: true,
+    }));
+    write(posix.join('studios', studioName, 'package.json'), formatJson(studioPackageJson(studioName)));
+    write(posix.join('studios', studioName, 'sanity.config.ts'), renderStudioConfig(options));
+    write(posix.join('studios', studioName, 'schemaTypes', 'index.ts'), STUDIO_SCHEMA_TYPES);
+    write(posix.join('studios', studioName, 'schemaTypes', 'post.ts'), STUDIO_POST_TYPE);
+    write(posix.join('studios', studioName, 'static', '.gitkeep'), '');
+    write(posix.join('functions', STARTER_FUNCTION_NAME, 'package.json'), formatJson(functionPackageJson(STARTER_FUNCTION_NAME)));
+    write(posix.join('functions', STARTER_FUNCTION_NAME, 'index.ts'), FUNCTION_SET_SLUG);
+    writePreparedRootFiles(dir, packageJson, files);
+    return { blueprintFilePath, files };
+}
+export function adoptWorkspace(options) {
+    const { dir } = options;
+    const packageJson = preparePackageJson(options, []);
+    const files = [];
+    const write = createWriter(dir, files);
+    const blueprintFilePath = write('sanity.blueprint.ts', renderBlueprint({ ...manifestOptions(options), studioSrc: '.', withFunction: false }));
+    writePreparedRootFiles(dir, packageJson, files);
+    return { blueprintFilePath, files };
+}
+function manifestOptions(options) {
+    return {
+        projectName: options.stackName,
+        displayName: options.displayName,
+        projectId: options.projectId,
+        datasetName: options.datasetName,
+        studioName: options.studioName,
+    };
+}
+function assertTargetsAvailable(dir, paths) {
+    const conflicts = paths.filter((path) => existsSync(join(dir, path)));
+    if (conflicts.length > 0) {
+        throw new Error(`Refusing to overwrite existing paths: ${conflicts.join(', ')}`);
+    }
+}
+function createWriter(dir, files) {
+    return (relativePath, content) => {
+        const filePath = join(dir, relativePath);
+        mkdirSync(dirname(filePath), { recursive: true });
+        writeFileSync(filePath, content);
+        files.push(relativePath);
+        return filePath;
+    };
+}
+function writePreparedRootFiles(dir, packageJson, files) {
+    if (writeGitignore(dir))
+        files.push('.gitignore');
+    writeFileSync(join(dir, 'package.json'), formatJson(packageJson));
+    files.push('package.json');
+}
+function writeGitignore(dir) {
+    const filePath = join(dir, '.gitignore');
+    if (!existsSync(filePath)) {
+        writeFileSync(filePath, DEFAULT_GITIGNORE);
+        return true;
+    }
+    const existing = readFileSync(filePath, 'utf8');
+    if (existing.split(/\r?\n/).some((line) => line.trim() === '.sanity/'))
+        return false;
+    writeFileSync(filePath, `${existing.trimEnd()}\n\n${GITIGNORE_ENTRY}\n`);
+    return true;
+}
+function preparePackageJson(options, requiredWorkspaces) {
+    const filePath = join(options.dir, 'package.json');
+    const parsed = existsSync(filePath)
+        ? JSON.parse(readFileSync(filePath, 'utf8'))
+        : {
+            name: options.stackName,
+            version: '0.1.0',
+            private: true,
+            type: 'module',
+        };
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('The existing package.json must contain a JSON object.');
+    }
+    const packageJson = parsed;
+    addWorkspaces(packageJson, requiredWorkspaces);
+    addBlueprintsDependency(packageJson, options.blueprintsVersion);
+    return packageJson;
+}
+function addWorkspaces(packageJson, required) {
+    if (required.length === 0)
+        return;
+    if (!packageJson.workspaces) {
+        packageJson.workspaces = required;
+        return;
+    }
+    if (Array.isArray(packageJson.workspaces)) {
+        packageJson.workspaces = [...new Set([...packageJson.workspaces, ...required])];
+        return;
+    }
+    if (!packageJson.workspaces || typeof packageJson.workspaces !== 'object') {
+        throw new Error('Cannot add generated packages to the existing package.json workspaces.');
+    }
+    const workspaces = packageJson.workspaces;
+    if (Array.isArray(workspaces.packages)) {
+        workspaces.packages = [...new Set([...workspaces.packages, ...required])];
+        return;
+    }
+    throw new Error('Cannot add generated packages to the existing package.json workspaces.');
+}
+function addBlueprintsDependency(packageJson, blueprintsVersion) {
+    const dependencies = recordOrEmpty(packageJson.dependencies);
+    const devDependencies = recordOrEmpty(packageJson.devDependencies);
+    if (dependencies['@sanity/blueprints'] || devDependencies['@sanity/blueprints'])
+        return;
+    packageJson.devDependencies = {
+        ...devDependencies,
+        '@sanity/blueprints': blueprintsVersion,
+    };
+}
+function recordOrEmpty(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function formatJson(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}

package/dist/actions/blueprints/assets.js

@@ -1,48 +1,52 @@
 import crypto from 'node:crypto';
 import fs from 'node:fs';
+import { readFile } from 'node:fs/promises';
 import AdmZip from 'adm-zip';
 import { blueprintsUrl } from '../../config.js';
 import { CONVERT_BYTES_TO_MB, MAX_ASSET_SIZE } from '../../constants.js';
 import { prepareAsset as prepareFunctionAsset } from '../../utils/functions/prepare-asset.js';
 import getHeaders from '../../utils/get-headers.js';
+import { prepareStudioAsset } from '../../utils/studios/prepare-asset.js';
 import { createTracedFetch } from '../../utils/traced-fetch.js';
 import { isLocalFunctionResource, isStudioResource } from '../../utils/types.js';
 const assetsUrl = blueprintsUrl('assets');
 export const assetCheckUrl = `${assetsUrl}/check`;
 export const assetStashUrl = `${assetsUrl}/stash`;
 export async function stashAsset({ resource, auth, blueprintFileDir, logger, installer, }) {
+    let cleanup = async () => { };
     try {
         let b64;
         let hash;
         let extension;
-        let cleanup;
         if (isLocalFunctionResource(resource)) {
             const prepResult = await prepareFunctionAsset({ resource, blueprintFileDir, installer });
             if (prepResult.success === false) {
+                await prepResult.cleanup();
                 return {
                     success: false,
                     error: prepResult.error,
                 };
             }
+            cleanup = prepResult.cleanup;
             const zipResult = await pathToB64ZipHash(prepResult.outputPath);
             b64 = zipResult.b64;
             hash = zipResult.hash;
             extension = 'zip';
-            cleanup = prepResult.cleanup;
         }
         else if (isStudioResource(resource)) {
-            const prepResult = await prepareStudioAsset({ resource });
+            const prepResult = await prepareStudioAsset({ resource, blueprintFileDir });
             if (prepResult.success === false) {
+                await prepResult.cleanup();
                 return {
                     success: false,
                     error: prepResult.error,
                 };
             }
-            const buffer = await fs.promises.readFile(prepResult.outputPath);
+            cleanup = prepResult.cleanup;
+            const buffer = await readFile(prepResult.outputPath);
             b64 = buffer.toString('base64');
             hash = hashBuffer(buffer);
             extension = 'tar.gz';
-            cleanup = prepResult.cleanup;
         }
         else {
             return {
@@ -61,28 +65,15 @@ export async function stashAsset({ resource, auth, blueprintFileDir, logger, ins
         });
     }
     catch (err) {
+        try {
+            await cleanup();
+        }
+        catch {
+            // ignore clean up errors
+        }
         return { success: false, error: err instanceof Error ? err.message : `${err}` };
     }
 }
-async function prepareStudioAsset({ resource, }) {
-    if (!fs.existsSync(resource.src)) {
-        return {
-            success: false,
-            async cleanup() {
-                // no op
-            },
-            error: `Property 'src' on resource with type '${resource.type}' must be a directory`,
-        };
-    }
-    return {
-        success: true,
-        async cleanup() {
-            // no op
-        },
-        // studio must be pre built (e.g. with `npm run build`) and tarred/gzipped
-        outputPath: resource.src,
-    };
-}
 async function stashSingleAsset({ b64, hash, cleanup, resource, auth, logger, extension = 'zip', }) {
     const fetchFn = createTracedFetch(logger);
     try {

package/dist/actions/blueprints/pre-deploy.d.ts

@@ -0,0 +1,29 @@
+import type { BlueprintResource } from '@sanity/blueprints';
+import type { Logger } from '../../utils/logger.js';
+import { type AuthParams, type InstallerType, type ScopeType } from '../../utils/types.js';
+type PreDeployResult = {
+    success: false;
+    error: string;
+    code?: string;
+    exitCode?: number;
+    suggestions?: string[];
+} | {
+    success: true;
+};
+type PreDeployResourceOptions = {
+    auth: AuthParams;
+    blueprintFileDir: string;
+    installer: InstallerType;
+    log: Logger;
+};
+type PreDeployOptions = {
+    scopeType: ScopeType;
+    scopeId: string;
+    resources: BlueprintResource[];
+    stackId: string;
+    stackName: string;
+    bin: string;
+    verbose: boolean | undefined;
+} & PreDeployResourceOptions;
+export declare function preDeploy(options: PreDeployOptions): Promise<PreDeployResult>;
+export {};

package/dist/actions/blueprints/pre-deploy.js

@@ -0,0 +1,164 @@
+import { env } from 'node:process';
+import { resolveDeployedResources } from '../../utils/blueprints/resolve-deployed-resources.js';
+import { niceId } from '../../utils/display/presenters.js';
+import { CODE_OPERATION_UNCONFIRMED, EXIT_OPERATION_UNCONFIRMED } from '../../utils/exit-codes.js';
+import { styleText } from '../../utils/style-text.js';
+import { isAssetResource, } from '../../utils/types.js';
+import { stashAsset } from './assets.js';
+import { updateStack } from './stacks.js';
+import { waitForOperation } from './wait-for-operation.js';
+const DEFAULT_ASSET_TIMEOUT = 180;
+const assetTimeoutS = Number(process.env.SANITY_ASSET_TIMEOUT) || DEFAULT_ASSET_TIMEOUT;
+const assetTimeoutMs = assetTimeoutS * 1000;
+const warnTimeoutMs = assetTimeoutMs / 3;
+export async function preDeploy(options) {
+    const { resources, stackId, auth, blueprintFileDir, installer, log } = options;
+    const hasAssetResources = resources.some(isAssetResource);
+    if (hasAssetResources) {
+        let assetResources;
+        if (env.SANITY_BLUEPRINTS_PRE_DEPLOY_ENABLED === 'true') {
+            const preDeployStackResult = await preDeployStack(options);
+            if (!preDeployStackResult.success) {
+                return preDeployStackResult;
+            }
+            /** Look up resources from the back-end and attach the externalId if possible */
+            const resolvedResources = await resolveDeployedResources({
+                resources,
+                stackId,
+                auth,
+                logger: log,
+            });
+            assetResources = resolvedResources.filter(isAssetResource);
+        }
+        else {
+            assetResources = resources.filter(isAssetResource);
+        }
+        log('Processing assets...');
+        for (const resource of assetResources) {
+            const preDeployResult = await preDeployResource(resource, {
+                auth,
+                blueprintFileDir,
+                installer,
+                log,
+            });
+            if (!preDeployResult.success)
+                return preDeployResult;
+            const idx = resources.findIndex((r) => r.name === resource.name);
+            if (idx === -1)
+                throw new Error('Unable to update resource asset');
+            resources[idx] = preDeployResult.resource;
+        }
+    }
+    return { success: true };
+}
+async function preDeployStack(options) {
+    const { scopeType, scopeId, stackId, stackName, resources, auth, log, bin, verbose } = options;
+    const spinner = log.ora('Starting pre-deploy...').start();
+    const stackMutation = {
+        scopeType,
+        scopeId,
+        name: stackName,
+        preDeploy: true,
+        document: { resources },
+    };
+    const { ok: deployOk, stack, error: deployError, } = await updateStack({ stackId, stackMutation, auth, logger: log });
+    if (!deployOk) {
+        spinner.fail(`${styleText('red', 'Failed')} to complete Stack pre-deployment`);
+        return {
+            success: false,
+            error: deployError || 'Failed to complete Stack pre-deployment',
+            suggestions: [
+                `Run \`npx ${bin} blueprints plan\` to preview changes before deploying.`,
+                `Run \`npx ${bin} blueprints doctor\` to check your configuration.`,
+            ],
+        };
+    }
+    spinner.stop().clear();
+    log(styleText('dim', 'Stack deployment progress:'));
+    log('');
+    const outcome = await waitForOperation({
+        stackId,
+        operationId: stack.operationId,
+        auth,
+        log,
+        bin,
+        verbose,
+        progressNoun: 'pre-deployment',
+    });
+    if (outcome.type === 'completed') {
+        log(styleText(['bold', 'green'], 'Stack pre-deployment completed!'));
+    }
+    else if (outcome.type === 'unconfirmed') {
+        return {
+            success: false,
+            error: `Stack pre-deployment was accepted but completion could not be confirmed${outcome.error ? ` (${outcome.error})` : ''}.`,
+            code: CODE_OPERATION_UNCONFIRMED,
+            exitCode: EXIT_OPERATION_UNCONFIRMED,
+            suggestions: [
+                'The pre-deployment may or may not have finished on Sanity servers.',
+                `Run \`npx ${bin} blueprints info\` to check status.`,
+                `Run \`npx ${bin} blueprints logs --watch\` to keep streaming logs.`,
+            ],
+        };
+    }
+    else {
+        return {
+            success: false,
+            error: 'Stack pre-deployment failed',
+            suggestions: [
+                ...outcome.logHints,
+                'Review the pre-deployment output above for error details.',
+                `Run \`npx ${bin} blueprints logs --verbose\` for more context.`,
+                `Run \`npx ${bin} blueprints plan\` to identify issues with your Blueprint.`,
+            ],
+        };
+    }
+    return { success: true };
+}
+async function preDeployResource(resource, options) {
+    const { auth, blueprintFileDir, installer, log } = options;
+    const fnSpinner = log.ora({ text: `Processing ${resource.name}...`, prefixText: ' ' }).start();
+    const warnTimer = setTimeout(() => {
+        fnSpinner.text = `Still processing ${resource.name}, this can take a moment...`;
+    }, warnTimeoutMs);
+    let assetTimeoutTimer;
+    let result;
+    try {
+        result = await Promise.race([
+            stashAsset({ resource, blueprintFileDir, auth, logger: log, installer }),
+            new Promise((_, reject) => {
+                assetTimeoutTimer = setTimeout(() => {
+                    reject(new Error(`Processing ${resource.name} timed out after ${assetTimeoutS}s`));
+                }, assetTimeoutMs);
+            }),
+        ]);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        fnSpinner.fail(msg);
+        return { success: false, error: msg };
+    }
+    finally {
+        clearTimeout(warnTimer);
+        clearTimeout(assetTimeoutTimer);
+    }
+    if (result.success && result.assetId) {
+        const updatedResource = { ...resource, src: result.assetId };
+        fnSpinner.succeed(`${updatedResource.name} ${niceId(result.assetId)}`);
+        log(`   Source: ${updatedResource.src}`);
+        if (result.hash) {
+            if (result.hash.length > 24) {
+                log.verbose(`   Hash: ${result.hash.slice(0, 8)}...${result.hash.slice(-12)}`);
+            }
+            else {
+                log.verbose(`   Hash: ${result.hash}`);
+            }
+        }
+        if (result.exists)
+            log.verbose('   Asset unchanged');
+        return { success: true, resource: updatedResource };
+    }
+    const errorMsg = `Failed uploading ${resource.name} asset, deploy has stopped`;
+    fnSpinner.fail(errorMsg);
+    return { success: false, error: result.error || 'Failed to process asset' };
+}

package/dist/actions/sanity/datasets.d.ts

@@ -0,0 +1,15 @@
+import type { Logger } from '../../utils/logger.js';
+import type { ActionResponse } from '../../utils/types.js';
+export interface Dataset {
+    name: string;
+    aclMode: string;
+}
+interface ListDatasetsResponse extends ActionResponse {
+    datasets: Dataset[];
+}
+export declare function listDatasets({ token, projectId, logger, }: {
+    token: string;
+    projectId: string;
+    logger: Logger;
+}): Promise<ListDatasetsResponse>;
+export {};

package/dist/actions/sanity/datasets.js

@@ -0,0 +1,26 @@
+import { createTracedFetch } from '../../utils/traced-fetch.js';
+import { projectsApiPath } from './projects.js';
+export async function listDatasets({ token, projectId, logger, }) {
+    const fetchFn = createTracedFetch(logger);
+    const url = `${projectsApiPath}/${encodeURIComponent(projectId)}/datasets`;
+    const response = await fetchFn(url, {
+        method: 'GET',
+        headers: {
+            Authorization: `Bearer ${token}`,
+            'Content-Type': 'application/json',
+        },
+    });
+    const body = await response.json();
+    if (!response.ok) {
+        return {
+            ok: false,
+            error: body.error?.message ?? response.statusText,
+            datasets: [],
+        };
+    }
+    return {
+        ok: true,
+        error: null,
+        datasets: body,
+    };
+}

package/dist/baseCommands.d.ts

@@ -14,6 +14,7 @@ export declare const pathFlagConfig: {
 };
 export declare const baseFlags: {
     json: Interfaces.BooleanFlag<boolean>;
+    llms: Interfaces.BooleanFlag<boolean>;
     path: Interfaces.OptionFlag<string | undefined, Interfaces.CustomOptions>;
     trace: Interfaces.BooleanFlag<boolean>;
     'validate-resources': Interfaces.BooleanFlag<boolean>;
@@ -42,6 +43,7 @@ export declare abstract class RuntimeCommand<T extends typeof Command> extends C
     protected args: Args<T>;
     static baseFlags: {
         json: Interfaces.BooleanFlag<boolean>;
+        llms: Interfaces.BooleanFlag<boolean>;
         path: Interfaces.OptionFlag<string | undefined, Interfaces.CustomOptions>;
         trace: Interfaces.BooleanFlag<boolean>;
         'validate-resources': Interfaces.BooleanFlag<boolean>;
@@ -113,6 +115,7 @@ export declare abstract class ResolvedCommand<T extends typeof Command> extends
     static needs: readonly Need[];
     static baseFlags: {
         json: Interfaces.BooleanFlag<boolean>;
+        llms: Interfaces.BooleanFlag<boolean>;
         path: Interfaces.OptionFlag<string | undefined, Interfaces.CustomOptions>;
         trace: Interfaces.BooleanFlag<boolean>;
         'validate-resources': Interfaces.BooleanFlag<boolean>;

package/dist/baseCommands.js

@@ -6,6 +6,7 @@ import { resolveIds } from './actions/blueprints/resolve.js';
 import { getStack, resolveStackIdByNameOrId } from './actions/blueprints/stacks.js';
 import config from './config.js';
 import { CI_SETUP_DOCS_URL } from './constants.js';
+import { commandSkillFilename, readCommandSkill } from './utils/command-skills.js';
 import { presentBlueprintParserErrors } from './utils/display/errors.js';
 import { Logger } from './utils/logger.js';
 import { styleText } from './utils/style-text.js';
@@ -30,6 +31,10 @@ export const baseFlags = {
         // override defaults from oclif's built-in --json flag
         description: 'Format output as json',
     }),
+    llms: OclifFlags.boolean({
+        description: 'Show agent-oriented guidance for this command',
+        aliases: ['skill'],
+    }),
     path: OclifFlags.string({
         ...pathFlagConfig,
         hidden: true,
@@ -118,6 +123,18 @@ export class RuntimeCommand extends Command {
         return commandHelp.generate();
     }
     async init() {
+        if (this.argv.some((arg) => arg === '--llms' || arg === '--skill')) {
+            const commandId = this.id ?? this.ctor.id;
+            const skill = await readCommandSkill(commandId);
+            if (!skill) {
+                const commandName = commandId.replaceAll(':', ' ');
+                this.error(`No agent guidance is available for \`${commandName}\`.`, {
+                    suggestions: [`Add it at skills/${commandSkillFilename(commandId)}.`],
+                });
+            }
+            process.stdout.write(skill.endsWith('\n') ? skill : `${skill}\n`);
+            this.exit();
+        }
         const { args, flags } = await this.parse({
             flags: this.ctor.flags,
             baseFlags: super.ctor.baseFlags,