@sanity/runtime-cli 8.0.3 → 8.1.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/8.0.3 linux-x64 node-v22.16.0
+@sanity/runtime-cli/8.1.0 linux-x64 node-v22.16.0
 $ sanity-run --help [COMMAND]
 USAGE
   $ sanity-run COMMAND
@@ -52,15 +52,16 @@ Add a Resource to a Blueprint
 
 ```
 USAGE
-  $ sanity-run blueprints add TYPE [--fn-type document-publish -n <value>] [--fn-language ts|js] [--javascript]
-    [--fn-helpers] [-i | --fn-installer skip|npm|pnpm|yarn]
+  $ sanity-run blueprints add TYPE [--example <value> | -n <value> | --fn-type document-publish | --fn-language
+    ts|js | --javascript | --fn-helpers | --fn-installer skip|npm|pnpm|yarn] [-i | ]
 
 ARGUMENTS
-  TYPE  (function) Type of resource to add (e.g. function)
+  TYPE  (function) Type of Resource to add (e.g. function)
 
 FLAGS
   -i, --install                Shortcut for --fn-installer npm
   -n, --name=<value>           Name of the Resource to add
+      --example=<value>        Example to use for the Resource
       --[no-]fn-helpers        Add helpers to the new Function
       --fn-installer=<option>  How to install the @sanity/functions helpers
                                <options: skip|npm|pnpm|yarn>
@@ -85,7 +86,7 @@ EXAMPLES
   $ sanity-run blueprints add function --name my-function --fn-type document-publish --lang js
 ```
 
-_See code: [src/commands/blueprints/add.ts](https://github.com/sanity-io/runtime-cli/blob/v8.0.3/src/commands/blueprints/add.ts)_
+_See code: [src/commands/blueprints/add.ts](https://github.com/sanity-io/runtime-cli/blob/v8.1.0/src/commands/blueprints/add.ts)_
 
 ## `sanity-run blueprints config`
 
@@ -116,7 +117,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/v8.0.3/src/commands/blueprints/config.ts)_
+_See code: [src/commands/blueprints/config.ts](https://github.com/sanity-io/runtime-cli/blob/v8.1.0/src/commands/blueprints/config.ts)_
 
 ## `sanity-run blueprints deploy`
 
@@ -138,7 +139,7 @@ EXAMPLES
   $ sanity-run blueprints deploy --no-wait
 ```
 
-_See code: [src/commands/blueprints/deploy.ts](https://github.com/sanity-io/runtime-cli/blob/v8.0.3/src/commands/blueprints/deploy.ts)_
+_See code: [src/commands/blueprints/deploy.ts](https://github.com/sanity-io/runtime-cli/blob/v8.1.0/src/commands/blueprints/deploy.ts)_
 
 ## `sanity-run blueprints destroy`
 
@@ -163,7 +164,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/v8.0.3/src/commands/blueprints/destroy.ts)_
+_See code: [src/commands/blueprints/destroy.ts](https://github.com/sanity-io/runtime-cli/blob/v8.1.0/src/commands/blueprints/destroy.ts)_
 
 ## `sanity-run blueprints info`
 
@@ -185,7 +186,7 @@ EXAMPLES
   $ sanity-run blueprints info --stack-id <stackId>
 ```
 
-_See code: [src/commands/blueprints/info.ts](https://github.com/sanity-io/runtime-cli/blob/v8.0.3/src/commands/blueprints/info.ts)_
+_See code: [src/commands/blueprints/info.ts](https://github.com/sanity-io/runtime-cli/blob/v8.1.0/src/commands/blueprints/info.ts)_
 
 ## `sanity-run blueprints init [DIR]`
 
@@ -193,8 +194,8 @@ Initialize a new Blueprint
 
 ```
 USAGE
-  $ sanity-run blueprints init [DIR] [--dir <value>] [--blueprint-type json|js|ts] [--stack-name <value> |
-    [--stack-id <value> --project-id <value>]]
+  $ sanity-run blueprints init [DIR] [--dir <value>] [--example <value> | --blueprint-type json|js|ts | --stack-id
+    <value> | --stack-name <value>] [--project-id <value>]
 
 ARGUMENTS
   DIR  Directory to create the Blueprint in
@@ -203,6 +204,7 @@ FLAGS
   --blueprint-type=<option>  Blueprint manifest type to use for the Blueprint
                              <options: json|js|ts>
   --dir=<value>              Directory to create the Blueprint in
+  --example=<value>          Example to use for the Blueprint
   --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
@@ -222,7 +224,7 @@ 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/v8.0.3/src/commands/blueprints/init.ts)_
+_See code: [src/commands/blueprints/init.ts](https://github.com/sanity-io/runtime-cli/blob/v8.1.0/src/commands/blueprints/init.ts)_
 
 ## `sanity-run blueprints logs`
 
@@ -244,7 +246,7 @@ EXAMPLES
   $ sanity-run blueprints logs --watch
 ```
 
-_See code: [src/commands/blueprints/logs.ts](https://github.com/sanity-io/runtime-cli/blob/v8.0.3/src/commands/blueprints/logs.ts)_
+_See code: [src/commands/blueprints/logs.ts](https://github.com/sanity-io/runtime-cli/blob/v8.1.0/src/commands/blueprints/logs.ts)_
 
 ## `sanity-run blueprints plan`
 
@@ -261,7 +263,7 @@ EXAMPLES
   $ sanity-run blueprints plan
 ```
 
-_See code: [src/commands/blueprints/plan.ts](https://github.com/sanity-io/runtime-cli/blob/v8.0.3/src/commands/blueprints/plan.ts)_
+_See code: [src/commands/blueprints/plan.ts](https://github.com/sanity-io/runtime-cli/blob/v8.1.0/src/commands/blueprints/plan.ts)_
 
 ## `sanity-run blueprints stacks`
 
@@ -283,7 +285,7 @@ EXAMPLES
   $ sanity-run blueprints stacks --project-id <projectId>
 ```
 
-_See code: [src/commands/blueprints/stacks.ts](https://github.com/sanity-io/runtime-cli/blob/v8.0.3/src/commands/blueprints/stacks.ts)_
+_See code: [src/commands/blueprints/stacks.ts](https://github.com/sanity-io/runtime-cli/blob/v8.1.0/src/commands/blueprints/stacks.ts)_
 
 ## `sanity-run functions dev`
 
@@ -303,7 +305,7 @@ EXAMPLES
   $ sanity-run functions dev --port 8974
 ```
 
-_See code: [src/commands/functions/dev.ts](https://github.com/sanity-io/runtime-cli/blob/v8.0.3/src/commands/functions/dev.ts)_
+_See code: [src/commands/functions/dev.ts](https://github.com/sanity-io/runtime-cli/blob/v8.1.0/src/commands/functions/dev.ts)_
 
 ## `sanity-run functions env add NAME KEY VALUE`
 
@@ -325,7 +327,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/v8.0.3/src/commands/functions/env/add.ts)_
+_See code: [src/commands/functions/env/add.ts](https://github.com/sanity-io/runtime-cli/blob/v8.1.0/src/commands/functions/env/add.ts)_
 
 ## `sanity-run functions env list NAME`
 
@@ -345,7 +347,7 @@ EXAMPLES
   $ sanity-run functions env list MyFunction
 ```
 
-_See code: [src/commands/functions/env/list.ts](https://github.com/sanity-io/runtime-cli/blob/v8.0.3/src/commands/functions/env/list.ts)_
+_See code: [src/commands/functions/env/list.ts](https://github.com/sanity-io/runtime-cli/blob/v8.1.0/src/commands/functions/env/list.ts)_
 
 ## `sanity-run functions env remove NAME KEY`
 
@@ -366,7 +368,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/v8.0.3/src/commands/functions/env/remove.ts)_
+_See code: [src/commands/functions/env/remove.ts](https://github.com/sanity-io/runtime-cli/blob/v8.1.0/src/commands/functions/env/remove.ts)_
 
 ## `sanity-run functions logs NAME`
 
@@ -400,7 +402,7 @@ EXAMPLES
   $ sanity-run functions logs <name> --delete
 ```
 
-_See code: [src/commands/functions/logs.ts](https://github.com/sanity-io/runtime-cli/blob/v8.0.3/src/commands/functions/logs.ts)_
+_See code: [src/commands/functions/logs.ts](https://github.com/sanity-io/runtime-cli/blob/v8.1.0/src/commands/functions/logs.ts)_
 
 ## `sanity-run functions test NAME`
 
@@ -433,7 +435,7 @@ EXAMPLES
   $ sanity-run functions test <name> --data '{ "id": 1 }' --timeout 60
 ```
 
-_See code: [src/commands/functions/test.ts](https://github.com/sanity-io/runtime-cli/blob/v8.0.3/src/commands/functions/test.ts)_
+_See code: [src/commands/functions/test.ts](https://github.com/sanity-io/runtime-cli/blob/v8.1.0/src/commands/functions/test.ts)_
 
 ## `sanity-run help [COMMAND]`
 

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

@@ -0,0 +1,26 @@
+export declare const EXAMPLES_CACHE_DIR: string;
+declare const EXAMPLE_TYPES: {
+    blueprint: string;
+    function: string;
+};
+export declare function verifyExampleExists({ type, name, }: {
+    type: keyof typeof EXAMPLE_TYPES;
+    name: string;
+}): Promise<boolean>;
+/**
+ * Downloads an example from the examples repo and writes it to disk.
+ * @sideEffect Creates the example directory and writes the example to disk.
+ * @returns The example files and directory and the function config if it exists.
+ */
+export declare function writeExample({ ownerRepo, exampleType, exampleName, dir, }: {
+    ownerRepo?: string;
+    exampleType: keyof typeof EXAMPLE_TYPES;
+    exampleName: string;
+    dir?: string;
+}): Promise<false | {
+    files: Record<string, string>;
+    dir: string;
+    instructions: string | null;
+    functionConfig: Record<string, unknown> | null;
+}>;
+export {};

package/dist/actions/sanity/examples.js

@@ -0,0 +1,176 @@
+import { createReadStream, createWriteStream, existsSync, mkdirSync, statSync, writeFileSync, } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import { createGunzip } from 'node:zlib';
+import { extract } from 'tar-stream';
+import { gitHubRequest } from '../../utils/other/github.js';
+export const EXAMPLES_CACHE_DIR = join(tmpdir(), 'sanity-examples');
+const EXAMPLES_REPO = 'sanity-io/sanity';
+const EXAMPLES_DIR = 'examples';
+const BLUEPRINTS_DIR = `${EXAMPLES_DIR}/blueprints`;
+const FUNCTIONS_DIR = `${EXAMPLES_DIR}/functions`;
+const EXAMPLE_TYPES = {
+    blueprint: BLUEPRINTS_DIR,
+    function: FUNCTIONS_DIR,
+};
+export async function verifyExampleExists({ type, name, }) {
+    const examplePath = `${EXAMPLE_TYPES[type]}/${name}`;
+    const path = `/repos/${EXAMPLES_REPO}/contents/${examplePath}`;
+    const response = await gitHubRequest(path);
+    return response.ok;
+}
+async function downloadRepoArchive(ownerRepo, ref = 'main') {
+    // cache the archive in a temp directory
+    const cacheKey = `${ownerRepo.replace('/', '-')}-${ref}.tar.gz`;
+    const cacheDir = EXAMPLES_CACHE_DIR;
+    const cachePath = join(cacheDir, cacheKey);
+    if (existsSync(cachePath)) {
+        const stats = statSync(cachePath);
+        const ageMinutes = (Date.now() - stats.mtime.getTime()) / (1000 * 60);
+        if (ageMinutes < 5)
+            return createReadStream(cachePath);
+    }
+    const path = `/repos/${ownerRepo}/tarball/${ref}`;
+    try {
+        const response = await gitHubRequest(path);
+        if (!response.ok)
+            throw new Error(`GitHub API error: ${response.status} ${response.statusText}`);
+        if (!response.body)
+            throw new Error('No response body received');
+        mkdirSync(cacheDir, { recursive: true });
+        const cacheWriteStream = createWriteStream(cachePath);
+        try {
+            // converting web streams to node streams is awkward
+            await pipeline(response.body, cacheWriteStream);
+        }
+        catch (error) {
+            console.debug(error);
+            return response.body;
+        }
+        return createReadStream(cachePath);
+    }
+    catch (error) {
+        console.error('❌ Error:', error instanceof Error ? error.message : 'Unknown error');
+        return null;
+    }
+}
+async function extractExampleFromArchive({ archiveStream, exampleType, exampleName, }) {
+    const fullPath = `${EXAMPLE_TYPES[exampleType]}/${exampleName}`;
+    const files = {};
+    let repoPrefix = null;
+    const extractStream = extract();
+    extractStream.on('entry', (header, stream, next) => {
+        const { name, type } = header;
+        // GitHub tarballs have a top-level directory like "repo-name-commit-hash/"
+        // detect it and strip it
+        if (!repoPrefix && name.includes('/'))
+            repoPrefix = name.split('/')[0];
+        // remove the repo prefix to get the actual file path
+        const cleanPath = repoPrefix ? name.replace(`${repoPrefix}/`, '') : name;
+        // check if this file is in our target example directory
+        if (cleanPath.startsWith(`${fullPath}/`) || cleanPath === fullPath) {
+            if (type === 'file') {
+                const chunks = [];
+                stream.on('data', (chunk) => chunks.push(chunk));
+                stream.on('end', () => {
+                    const content = Buffer.concat(chunks).toString('utf8');
+                    files[cleanPath.replace(`${fullPath}/`, '')] = content;
+                    next();
+                });
+            }
+            else {
+                stream.resume(); // skip directories
+                next();
+            }
+        }
+        else {
+            stream.resume();
+            next();
+        }
+    });
+    // pipes!
+    await pipeline(archiveStream, createGunzip(), extractStream);
+    if (Object.keys(files).length === 0)
+        return null;
+    return files;
+}
+function writeExampleToDisk(files, targetDir, exampleName) {
+    for (const [filePath, content] of Object.entries(files)) {
+        // Remove the example prefix from the file path for local storage
+        const localPath = filePath.startsWith(`${exampleName}/`)
+            ? filePath.replace(`${exampleName}/`, '')
+            : filePath;
+        const fullPath = join(targetDir, localPath);
+        const dir = dirname(fullPath);
+        // Create directory if it doesn't exist
+        mkdirSync(dir, { recursive: true });
+        // Write file
+        writeFileSync(fullPath, content);
+    }
+}
+/**
+ * @sideEffect Modifies the example files to remove the function config from the package.json.
+ * @returns The function config if it exists.
+ */
+function extractFunctionConfig(exampleFiles) {
+    const packageJson = exampleFiles['package.json'];
+    if (!packageJson)
+        return null;
+    let functionConfig = null;
+    try {
+        const packageJsonContent = JSON.parse(packageJson);
+        functionConfig = packageJsonContent.blueprintResourceItem;
+        packageJsonContent.blueprintResourceItem = undefined;
+        exampleFiles['package.json'] = JSON.stringify(packageJsonContent, null, 2);
+    }
+    catch (error) {
+        return null;
+    }
+    return functionConfig;
+}
+/**
+ * @sideEffect Modifies the example files to remove the instructions from the package.json.
+ * @returns The instructions if they exist.
+ */
+function extractInstructions(exampleFiles) {
+    const packageJson = exampleFiles['package.json'];
+    if (!packageJson)
+        return null;
+    let instructions = null;
+    try {
+        const packageJsonContent = JSON.parse(packageJson);
+        instructions = packageJsonContent.exampleInstructions;
+        packageJsonContent.exampleInstructions = undefined;
+        exampleFiles['package.json'] = JSON.stringify(packageJsonContent, null, 2);
+    }
+    catch (error) {
+        return null;
+    }
+    return instructions;
+}
+/**
+ * Downloads an example from the examples repo and writes it to disk.
+ * @sideEffect Creates the example directory and writes the example to disk.
+ * @returns The example files and directory and the function config if it exists.
+ */
+export async function writeExample({ ownerRepo = EXAMPLES_REPO, exampleType, exampleName, dir = './tmp', }) {
+    const archiveStream = await downloadRepoArchive(ownerRepo);
+    if (!archiveStream)
+        return false;
+    const exampleFiles = await extractExampleFromArchive({
+        archiveStream,
+        exampleType,
+        exampleName,
+    });
+    if (!exampleFiles)
+        return false;
+    let instructions = null;
+    instructions = extractInstructions(exampleFiles);
+    let functionConfig = null;
+    if (exampleType === 'function')
+        functionConfig = extractFunctionConfig(exampleFiles);
+    mkdirSync(dir, { recursive: true });
+    writeExampleToDisk(exampleFiles, dir, exampleName);
+    return { files: exampleFiles, dir, instructions, functionConfig };
+}

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

@@ -6,6 +6,7 @@ export default class AddCommand extends BlueprintCommand<typeof AddCommand> {
         type: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
     static flags: {
+        example: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         name: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'fn-type': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'fn-language': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;

package/dist/commands/blueprints/add.js

@@ -12,12 +12,17 @@ export default class AddCommand extends BlueprintCommand {
     ];
     static args = {
         type: Args.string({
-            description: 'Type of resource to add (e.g. function)',
+            description: 'Type of Resource to add (e.g. function)',
             options: ['function'],
             required: true,
         }),
     };
     static flags = {
+        example: Flags.string({
+            description: 'Example to use for the Resource',
+            aliases: ['recipe'],
+            exclusive: ['name', 'fn-type', 'fn-language', 'javascript', 'fn-helpers', 'fn-installer'], // set automatically
+        }),
         name: Flags.string({
             description: 'Name of the Resource to add',
             char: 'n',

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

@@ -7,6 +7,7 @@ export default class InitCommand extends Command {
     };
     static flags: {
         dir: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        example: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'blueprint-type': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'project-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'stack-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/dist/commands/blueprints/init.js

@@ -19,6 +19,11 @@ export default class InitCommand extends Command {
         dir: Flags.string({
             description: 'Directory to create the Blueprint in',
         }),
+        example: Flags.string({
+            description: 'Example to use for the Blueprint',
+            aliases: ['recipe'],
+            exclusive: ['blueprint-type', 'stack-id', 'stack-name'], // set automatically
+        }),
         'blueprint-type': Flags.string({
             description: 'Blueprint manifest type to use for the Blueprint',
             options: ['json', 'js', 'ts'],

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

@@ -6,6 +6,7 @@ export interface BlueprintAddOptions extends CoreConfig {
         type: string;
     };
     flags: {
+        example?: string;
         name?: string;
         'fn-type'?: string;
         language?: string;

package/dist/cores/blueprints/add.js

@@ -1,8 +1,12 @@
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
 import { cwd } from 'node:process';
 import { highlight } from 'cardinal';
 import chalk from 'chalk';
 import inquirer from 'inquirer';
 import { createFunctionResource } from '../../actions/blueprints/resources.js';
+import { verifyExampleExists, writeExample } from '../../actions/sanity/examples.js';
+import { check, indent, warn } from '../../utils/display/presenters.js';
 import { validateFunctionName } from '../../utils/validate/resource.js';
 const FUNCTION_BLUEPRINT_RESOURCE_TEMPLATE = `
   export default defineBlueprint({
@@ -14,9 +18,11 @@ const FUNCTION_BLUEPRINT_RESOURCE_TEMPLATE = `
   })
 `;
 export async function blueprintAddCore(options) {
+    const root = cwd();
     const { bin = 'sanity', log, blueprint, args, flags } = options;
+    const { blueprintFilePath } = blueprint.fileInfo;
     const { type: resourceType } = args;
-    const { name: flagResourceName, 'fn-type': flagFnType, javascript: flagJs, 'fn-helpers': flagFnHelpers, install: flagI, 'fn-installer': flagFnInstaller, // can be 'skip'!
+    const { example: flagExample, name: flagResourceName, 'fn-type': flagFnType, javascript: flagJs, 'fn-helpers': flagFnHelpers, install: flagI, 'fn-installer': flagFnInstaller, // can be 'skip'!
      } = flags;
     let { language: flagFnLang } = flags;
     flagFnLang = flagJs ? 'js' : flagFnLang;
@@ -26,6 +32,59 @@ export async function blueprintAddCore(options) {
             error: `Unsupported Resource type: ${resourceType}`,
         };
     }
+    if (flagExample) {
+        // ! short circuit for examples
+        log(warn(`Example feature is experimental. Setting up "${flagExample}"...`)); // we need to...
+        // * 1. verify example exists in the recipes repo
+        const exampleExists = await verifyExampleExists({ type: 'function', name: flagExample });
+        if (!exampleExists) {
+            return { success: false, error: `Function example "${flagExample}" does not exist.` };
+        }
+        // * 2. download and write example to disk
+        // TODO: revisit path string handling; differs for fs operations vs. display
+        const exampleDir = join(dirname(blueprintFilePath), 'functions', flagExample);
+        if (existsSync(exampleDir)) {
+            return {
+                success: false,
+                error: `Directory "${exampleDir.replace(root, '')}" already exists.`,
+            };
+        }
+        const addedExample = await writeExample({
+            exampleType: 'function',
+            exampleName: flagExample,
+            dir: exampleDir,
+        });
+        if (!addedExample) {
+            return { success: false, error: `Unable to download example "${flagExample}"` };
+        }
+        const { files, dir, instructions, functionConfig } = addedExample;
+        const newDir = dir.replace(root, '').replace(/^[/\\]+/, '');
+        for (const filePath of Object.keys(files)) {
+            log(check(`${chalk.bold('Created:')}  ${newDir}/${filePath}`));
+        }
+        // * 3. print instructions
+        if (functionConfig) {
+            log('');
+            log(chalk.bold(`Add the following to ${blueprint.fileInfo.fileName}:`));
+            const configString = JSON.stringify(functionConfig, null, 2);
+            if (blueprint.fileInfo.extension === '.json') {
+                log(indent(highlight(configString)));
+            }
+            else {
+                // modify configString so it doesn't have quoted keys
+                const objectLiteral = configString.replace(/^(\s*)"([a-zA-Z_$][a-zA-Z0-9_$]*)":/gm, '$1$2:');
+                log(indent(highlight(`defineDocumentFunction(${objectLiteral})`)));
+            }
+        }
+        else {
+            log(warn('No Function config found in example.'));
+        }
+        if (instructions) {
+            log('');
+            log(instructions);
+        }
+        return { success: true };
+    }
     if (flagI) {
         if (flagFnInstaller) {
             return {
@@ -90,13 +149,14 @@ export async function blueprintAddCore(options) {
         if (installCommand)
             log(`${chalk.magenta('Installing')} with ${installCommand}...`);
         const { filePath, resourceAdded, resource } = await createFunctionResource({
+            blueprintFilePath,
             name: fnName,
             type: fnType,
             lang: fnLang,
             addHelpers,
             installCommand,
         });
-        log(`\nCreated function: ${filePath.replace(cwd(), '')}`);
+        log(`\nCreated function: ${filePath.replace(root, '')}`);
         if (!resourceAdded) {
             // print the resource definition for manual addition
             log(`\n${chalk.bold('Add the Resource to your Blueprint:')}`);

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

@@ -6,6 +6,7 @@ export interface BlueprintInitOptions extends CoreConfig {
     };
     flags: {
         dir?: string;
+        example?: string;
         'blueprint-type'?: string;
         'project-id'?: string;
         'stack-id'?: string;

package/dist/cores/blueprints/init.js

@@ -1,9 +1,10 @@
+import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { cwd } from 'node:process';
 import chalk from 'chalk';
 import inquirer from 'inquirer';
 import { BLUEPRINT_CONFIG_FILE, BLUEPRINT_DIR, findBlueprintFile, writeBlueprintToDisk, writeConfigFile, writeGitignoreFile, writeOrUpdateNodeDependency, } from '../../actions/blueprints/blueprint.js';
 import { createEmptyStack, getStack } from '../../actions/blueprints/stacks.js';
+import { verifyExampleExists, writeExample } from '../../actions/sanity/examples.js';
 import { getProject } from '../../actions/sanity/projects.js';
 import { check, warn } from '../../utils/display/presenters.js';
 import { promptForProject, promptForStackId } from '../../utils/display/prompt.js';
@@ -11,15 +12,66 @@ const LAUNCH_LIMIT_STACK_PER_PROJECT = true;
 export async function blueprintInitCore(options) {
     const { bin = 'sanity', log, token, args, flags } = options;
     try {
-        const { 'blueprint-type': flagBlueprintType, 'project-id': flagProjectId, 'stack-id': flagStackId, 'stack-name': flagStackName, dir: flagDir, } = flags;
+        const { dir: flagDir, example: flagExample, 'blueprint-type': flagBlueprintType, 'project-id': flagProjectId, 'stack-id': flagStackId, 'stack-name': flagStackName, } = flags;
         const { dir: argDir } = args;
         const providedDir = argDir || flagDir;
-        const here = cwd();
-        const dir = argDir || flagDir || here;
+        const dir = providedDir || '.';
         const existingBlueprint = findBlueprintFile(dir);
         if (existingBlueprint) {
             return { success: false, error: 'Existing Blueprint found.' };
         }
+        if (flagExample) {
+            // ! short circuit for examples
+            log(warn(`Example feature is experimental. Setting up "${flagExample}"...`));
+            // we need to...
+            // * 1. verify example exists in the recipes repo
+            const exampleExists = await verifyExampleExists({ type: 'blueprint', name: flagExample });
+            if (!exampleExists) {
+                return { success: false, error: `Blueprint example "${flagExample}" does not exist.` };
+            }
+            // * 2. get a projectId from the user
+            const projectId = flagProjectId || (await promptForProject({ token })).projectId;
+            // * 3. create empty stack with name from example name
+            const stack = await createEmptyStack({
+                token,
+                projectId,
+                name: `example-${flagExample}`,
+                projectBased: false,
+            });
+            // * 4. download and write example to disk
+            // take into account optional providedDir
+            const exampleDir = join(dir, providedDir ? '' : flagExample);
+            if (existsSync(exampleDir)) {
+                return { success: false, error: `Example directory "${exampleDir}" already exists.` };
+            }
+            const addedExample = await writeExample({
+                exampleType: 'blueprint',
+                exampleName: flagExample,
+                dir: exampleDir,
+            });
+            if (!addedExample) {
+                return { success: false, error: `Unable to download example "${flagExample}"` };
+            }
+            const { files, dir: newDir, instructions } = addedExample;
+            for (const filePath of Object.keys(files)) {
+                log(check(`${chalk.bold('Created:')}    ${newDir}/${filePath}`));
+            }
+            const discoveredBlueprint = findBlueprintFile(exampleDir);
+            if (!discoveredBlueprint) {
+                return { success: false, error: 'Failed to find blueprint file.' };
+            }
+            const { blueprintFilePath } = discoveredBlueprint;
+            // * 5. write config file
+            writeConfigFile({ blueprintFilePath, projectId, stackId: stack.id });
+            log(check(`${chalk.bold('Configured:')} ${exampleDir}/${BLUEPRINT_DIR}/${BLUEPRINT_CONFIG_FILE}`));
+            // * 6. print next step
+            log(`\n  Run "${chalk.bold.magenta(`cd ${exampleDir} && npm i`)}" and check out the README`);
+            if (instructions) {
+                log('');
+                log(instructions);
+            }
+            return { success: true };
+        }
         const blueprintExtension = flagBlueprintType || (await promptForBlueprintType());
         if (!blueprintExtension) {
             return { success: false, error: 'Blueprint type is required.' };
@@ -77,12 +129,11 @@ export async function blueprintInitCore(options) {
         }
         const nextStepParts = [];
         if (providedDir)
-            nextStepParts.push(`cd ./${providedDir}`);
+            nextStepParts.push(`cd ${providedDir}`);
         if (blueprintExtension !== 'json')
             nextStepParts.push('npm install');
         nextStepParts.push(`${bin} blueprints --help`);
-        const nextStep = `Run ${chalk.bold.magenta(nextStepParts.join(' && '))}`;
-        log(`\n  ${nextStep} to get started`);
+        log(`\n  Run "${chalk.bold.magenta(nextStepParts.join(' && '))}" to get started`);
         return { success: true };
     }
     catch (error) {

package/dist/cores/blueprints/plan.js

@@ -19,6 +19,6 @@ export async function blueprintPlanCore(options) {
                 log(chalk.dim('No changes detected to live deployment'));
         }
     }
-    log(chalk.dim(`Run "${bin} blueprints deploy" to deploy these changes`));
+    log(`\n  Run "${chalk.bold.magenta(`${bin} blueprints deploy`)}" to deploy these changes`);
     return { success: true };
 }

package/dist/utils/display/presenters.d.ts

@@ -3,3 +3,4 @@ export declare function info(str: string): string;
 export declare function warn(str: string): string;
 export declare function severe(str: string): string;
 export declare function niceId(id: string | undefined): string;
+export declare function indent(str: string, spaces?: number): string;

package/dist/utils/display/presenters.js

@@ -16,3 +16,10 @@ export function niceId(id) {
         return '';
     return `<${chalk.yellow(id)}>`;
 }
+export function indent(str, spaces = 2) {
+    const pad = ' '.repeat(spaces);
+    return str
+        .split('\n')
+        .map((line) => (line.length > 0 ? pad + line : line))
+        .join('\n');
+}

package/dist/utils/other/github.d.ts

@@ -0,0 +1,2 @@
+export declare const GITHUB_API_URL = "https://api.github.com";
+export declare function gitHubRequest(path: string): Promise<Response>;

package/dist/utils/other/github.js

@@ -0,0 +1,30 @@
+// ! Making requests to the GitHub API will be rate limited at 60 requests per hour per IP address
+// https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api?apiVersion=2022-11-28#primary-rate-limit-for-unauthenticated-users
+export const GITHUB_API_URL = 'https://api.github.com';
+export async function gitHubRequest(path) {
+    const response = await fetch(`${GITHUB_API_URL}${path}`, {
+        headers: { Accept: 'application/vnd.github.v3+json' },
+    });
+    if (response.ok) {
+        const remaining = Number(response.headers.get('X-RateLimit-Remaining'));
+        const limit = Number(response.headers.get('X-RateLimit-Limit'));
+        const reset = Number(response.headers.get('X-RateLimit-Reset'));
+        if (remaining && limit && reset) {
+            const percentRemaining = (remaining / limit) * 100;
+            const percentUsed = 100 - percentRemaining;
+            if (percentUsed > 85) {
+                // warn if near rate limit
+                console.warn(`Warning: You have used ${percentUsed.toFixed(2)}% of your GitHub API requests.`);
+                const resetTime = new Date(reset * 1000);
+                console.log(`Reset in ${Math.floor((resetTime.getTime() - Date.now()) / 60000)} minutes`);
+            }
+        }
+    }
+    else {
+        // check for rate limit error
+        if (response.status === 403 || response.status === 429) {
+            console.error('GitHub API rate limit exceeded');
+        }
+    }
+    return response; // always return the response
+}

package/oclif.manifest.json

@@ -4,7 +4,7 @@
       "aliases": [],
       "args": {
         "type": {
-          "description": "Type of resource to add (e.g. function)",
+          "description": "Type of Resource to add (e.g. function)",
           "name": "type",
           "options": [
             "function"
@@ -21,6 +21,24 @@
         "<%= config.bin %> <%= command.id %> function --name my-function --fn-type document-publish --lang js"
       ],
       "flags": {
+        "example": {
+          "aliases": [
+            "recipe"
+          ],
+          "description": "Example to use for the Resource",
+          "exclusive": [
+            "name",
+            "fn-type",
+            "fn-language",
+            "javascript",
+            "fn-helpers",
+            "fn-installer"
+          ],
+          "name": "example",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "name": {
           "char": "n",
           "description": "Name of the Resource to add",
@@ -351,6 +369,21 @@
           "multiple": false,
           "type": "option"
         },
+        "example": {
+          "aliases": [
+            "recipe"
+          ],
+          "description": "Example to use for the Blueprint",
+          "exclusive": [
+            "blueprint-type",
+            "stack-id",
+            "stack-name"
+          ],
+          "name": "example",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "blueprint-type": {
           "aliases": [
             "type"
@@ -838,5 +871,5 @@
       ]
     }
   },
-  "version": "8.0.3"
+  "version": "8.1.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sanity/runtime-cli",
   "description": "Sanity's Runtime CLI for Blueprints and Functions",
-  "version": "8.0.3",
+  "version": "8.1.0",
   "author": "Sanity Runtime Team",
   "type": "module",
   "license": "MIT",
@@ -70,7 +70,8 @@
     "pretest": "cd test/integration && npm install",
     "test": "vitest run",
     "posttest": "npm run lint",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "watch": "tsc --watch"
   },
   "dependencies": {
     "@oclif/core": "^4.3.0",
@@ -86,6 +87,7 @@
     "jiti": "^2.4.2",
     "mime-types": "^3.0.1",
     "ora": "^8.2.0",
+    "tar-stream": "^3.1.7",
     "vite": "^6.3.5",
     "vite-tsconfig-paths": "^5.1.4",
     "ws": "^8.18.2",
@@ -105,6 +107,7 @@
     "@types/cardinal": "^2.1.1",
     "@types/mime-types": "^2.1.4",
     "@types/node": "20",
+    "@types/tar-stream": "^3.1.4",
     "@types/ws": "^8.18.1",
     "codemirror": "^6.0.1",
     "mentoss": "^0.11.0",