@sanity/runtime-cli 6.2.1 → 7.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/6.2.1 linux-x64 node-v22.15.0
+@sanity/runtime-cli/7.0.0 linux-x64 node-v22.15.0
 $ sanity-run --help [COMMAND]
 USAGE
   $ sanity-run COMMAND
@@ -52,17 +52,22 @@ Add a Resource to a Blueprint
 ```
 USAGE
   $ sanity-run blueprints add TYPE [--fn-type document-publish -n <value>] [--language ts|js] [--javascript]
+    [--fn-helpers] [-i | --fn-installer skip|npm|pnpm|yarn]
 
 ARGUMENTS
   TYPE  (function) Type of resource to add (e.g. function)
 
 FLAGS
-  -n, --name=<value>       Name of the Resource to add
-      --fn-type=<option>   Type of new Function
-                           <options: document-publish>
-      --javascript         Use JavaScript instead of TypeScript
-      --language=<option>  [default: ts] Language of the new Function
-                           <options: ts|js>
+  -i, --install                Shortcut for --fn-installer npm
+  -n, --name=<value>           Name of the Resource to add
+      --[no-]fn-helpers        Add helpers to the new Function
+      --fn-installer=<option>  How to install the @sanity/functions helpers
+                               <options: skip|npm|pnpm|yarn>
+      --fn-type=<option>       Type of new Function
+                               <options: document-publish>
+      --javascript             Use JavaScript instead of TypeScript
+      --language=<option>      [default: ts] Language of the new Function
+                               <options: ts|js>
 
 DESCRIPTION
   Add a Resource to a Blueprint
@@ -70,6 +75,8 @@ DESCRIPTION
 EXAMPLES
   $ sanity-run blueprints add function
 
+  $ sanity-run blueprints add function --helpers
+
   $ sanity-run blueprints add function --name my-function
 
   $ sanity-run blueprints add function --name my-function --fn-type document-publish
@@ -77,7 +84,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/v6.2.1/src/commands/blueprints/add.ts)_
+_See code: [src/commands/blueprints/add.ts](https://github.com/sanity-io/runtime-cli/blob/v7.0.0/src/commands/blueprints/add.ts)_
 
 ## `sanity-run blueprints config`
 
@@ -105,7 +112,7 @@ EXAMPLES
   $ sanity-run blueprints config --edit --project-id <projectId>
 ```
 
-_See code: [src/commands/blueprints/config.ts](https://github.com/sanity-io/runtime-cli/blob/v6.2.1/src/commands/blueprints/config.ts)_
+_See code: [src/commands/blueprints/config.ts](https://github.com/sanity-io/runtime-cli/blob/v7.0.0/src/commands/blueprints/config.ts)_
 
 ## `sanity-run blueprints deploy`
 
@@ -127,7 +134,7 @@ EXAMPLES
   $ sanity-run blueprints deploy --no-wait
 ```
 
-_See code: [src/commands/blueprints/deploy.ts](https://github.com/sanity-io/runtime-cli/blob/v6.2.1/src/commands/blueprints/deploy.ts)_
+_See code: [src/commands/blueprints/deploy.ts](https://github.com/sanity-io/runtime-cli/blob/v7.0.0/src/commands/blueprints/deploy.ts)_
 
 ## `sanity-run blueprints destroy`
 
@@ -148,7 +155,7 @@ EXAMPLES
   $ sanity-run blueprints destroy
 ```
 
-_See code: [src/commands/blueprints/destroy.ts](https://github.com/sanity-io/runtime-cli/blob/v6.2.1/src/commands/blueprints/destroy.ts)_
+_See code: [src/commands/blueprints/destroy.ts](https://github.com/sanity-io/runtime-cli/blob/v7.0.0/src/commands/blueprints/destroy.ts)_
 
 ## `sanity-run blueprints info`
 
@@ -165,7 +172,7 @@ EXAMPLES
   $ sanity-run blueprints info
 ```
 
-_See code: [src/commands/blueprints/info.ts](https://github.com/sanity-io/runtime-cli/blob/v6.2.1/src/commands/blueprints/info.ts)_
+_See code: [src/commands/blueprints/info.ts](https://github.com/sanity-io/runtime-cli/blob/v7.0.0/src/commands/blueprints/info.ts)_
 
 ## `sanity-run blueprints init [DIR]`
 
@@ -197,7 +204,7 @@ EXAMPLES
   $ sanity-run blueprints init --blueprint-type <json|js|ts> --project-id <projectId>
 ```
 
-_See code: [src/commands/blueprints/init.ts](https://github.com/sanity-io/runtime-cli/blob/v6.2.1/src/commands/blueprints/init.ts)_
+_See code: [src/commands/blueprints/init.ts](https://github.com/sanity-io/runtime-cli/blob/v7.0.0/src/commands/blueprints/init.ts)_
 
 ## `sanity-run blueprints logs`
 
@@ -219,7 +226,7 @@ EXAMPLES
   $ sanity-run blueprints logs --watch
 ```
 
-_See code: [src/commands/blueprints/logs.ts](https://github.com/sanity-io/runtime-cli/blob/v6.2.1/src/commands/blueprints/logs.ts)_
+_See code: [src/commands/blueprints/logs.ts](https://github.com/sanity-io/runtime-cli/blob/v7.0.0/src/commands/blueprints/logs.ts)_
 
 ## `sanity-run blueprints plan`
 
@@ -236,7 +243,7 @@ EXAMPLES
   $ sanity-run blueprints plan
 ```
 
-_See code: [src/commands/blueprints/plan.ts](https://github.com/sanity-io/runtime-cli/blob/v6.2.1/src/commands/blueprints/plan.ts)_
+_See code: [src/commands/blueprints/plan.ts](https://github.com/sanity-io/runtime-cli/blob/v7.0.0/src/commands/blueprints/plan.ts)_
 
 ## `sanity-run functions dev`
 
@@ -256,7 +263,7 @@ EXAMPLES
   $ sanity-run functions dev --port 8974
 ```
 
-_See code: [src/commands/functions/dev.ts](https://github.com/sanity-io/runtime-cli/blob/v6.2.1/src/commands/functions/dev.ts)_
+_See code: [src/commands/functions/dev.ts](https://github.com/sanity-io/runtime-cli/blob/v7.0.0/src/commands/functions/dev.ts)_
 
 ## `sanity-run functions env add NAME KEY VALUE`
 
@@ -278,7 +285,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/v6.2.1/src/commands/functions/env/add.ts)_
+_See code: [src/commands/functions/env/add.ts](https://github.com/sanity-io/runtime-cli/blob/v7.0.0/src/commands/functions/env/add.ts)_
 
 ## `sanity-run functions env list NAME`
 
@@ -298,7 +305,7 @@ EXAMPLES
   $ sanity-run functions env list MyFunction
 ```
 
-_See code: [src/commands/functions/env/list.ts](https://github.com/sanity-io/runtime-cli/blob/v6.2.1/src/commands/functions/env/list.ts)_
+_See code: [src/commands/functions/env/list.ts](https://github.com/sanity-io/runtime-cli/blob/v7.0.0/src/commands/functions/env/list.ts)_
 
 ## `sanity-run functions env remove NAME KEY`
 
@@ -319,7 +326,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/v6.2.1/src/commands/functions/env/remove.ts)_
+_See code: [src/commands/functions/env/remove.ts](https://github.com/sanity-io/runtime-cli/blob/v7.0.0/src/commands/functions/env/remove.ts)_
 
 ## `sanity-run functions logs NAME`
 
@@ -352,7 +359,7 @@ EXAMPLES
   $ sanity-run functions logs <name> --delete
 ```
 
-_See code: [src/commands/functions/logs.ts](https://github.com/sanity-io/runtime-cli/blob/v6.2.1/src/commands/functions/logs.ts)_
+_See code: [src/commands/functions/logs.ts](https://github.com/sanity-io/runtime-cli/blob/v7.0.0/src/commands/functions/logs.ts)_
 
 ## `sanity-run functions test NAME`
 
@@ -385,7 +392,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/v6.2.1/src/commands/functions/test.ts)_
+_See code: [src/commands/functions/test.ts](https://github.com/sanity-io/runtime-cli/blob/v7.0.0/src/commands/functions/test.ts)_
 
 ## `sanity-run help [COMMAND]`
 

package/dist/actions/blueprints/blueprint.js

@@ -59,31 +59,31 @@ export async function readLocalBlueprint(blueprintPath) {
     const blueprintFile = findBlueprintFile(blueprintPath);
     if (!blueprintFile)
         throw Error('Could not find Blueprint file! Use the init command.');
-    const { blueprintFilePath: foundPath, fileName, extension } = blueprintFile;
+    const { blueprintFilePath: foundFilePath, fileName, extension } = blueprintFile;
     let rawBlueprint;
     let blueprintModule;
     try {
         switch (extension) {
             case '.json': {
-                const blueprintString = readFileSync(foundPath, 'utf8').toString();
+                const blueprintString = readFileSync(foundFilePath, 'utf8').toString();
                 rawBlueprint = JSON.parse(blueprintString);
                 break;
             }
             case '.js':
             case '.mjs': {
-                const module = await import(foundPath);
+                const module = await import(foundFilePath);
                 blueprintModule = module.default;
                 break;
             }
             case '.cjs': {
                 const require = createRequire(import.meta.url);
-                blueprintModule = require(foundPath);
+                blueprintModule = require(foundFilePath);
                 break;
             }
             case '.ts': {
                 try {
                     const { tsImport } = await import('tsx/esm/api');
-                    const module = await tsImport(foundPath, dirname(foundPath));
+                    const module = await tsImport(`file://${foundFilePath}`, dirname(foundFilePath));
                     blueprintModule = module.default;
                 }
                 catch (err) {
@@ -98,7 +98,7 @@ export async function readLocalBlueprint(blueprintPath) {
                 throw Error(`Unsupported blueprint file extension: ${extension}`);
         }
     }
-    catch {
+    catch (err) {
         throw Error(`Error parsing Blueprint file: ${fileName}`);
     }
     if (blueprintModule) {
@@ -107,7 +107,7 @@ export async function readLocalBlueprint(blueprintPath) {
         try {
             rawBlueprint = blueprintModule();
         }
-        catch (err) {
+        catch {
             throw Error(`Error executing Blueprint file: ${fileName}`);
         }
     }
@@ -121,7 +121,7 @@ export async function readLocalBlueprint(blueprintPath) {
         const fnErrors = functionResources.map((r) => validateFunctionResource(r));
         errors.push(...fnErrors.flat());
     }
-    const configIds = readConfigFile(foundPath);
+    const configIds = readConfigFile(foundFilePath);
     const configPath = configIds?.configPath;
     let projectId;
     if (configIds?.projectId)
@@ -133,7 +133,7 @@ export async function readLocalBlueprint(blueprintPath) {
     if (!stackId && projectId)
         stackId = `ST-${projectId}`;
     return {
-        fileInfo: { blueprintFilePath: foundPath, fileName, extension },
+        fileInfo: { blueprintFilePath: foundFilePath, fileName, extension },
         rawBlueprint: rawBlueprint,
         errors,
         projectId,

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

@@ -30,6 +30,7 @@ type BlueprintFailure = {
 type BlueprintResult = BlueprintSuccess | BlueprintFailure;
 /**
  * Get the local Blueprint and deployed Stack
+ * @deprecated Use initBlueprintConfig or initDeployedBlueprintConfig instead
  * @param blueprintPath - The path of the Blueprint file or directory- will search up the directory tree if not provided
  * @param token - The Sanity API token
  * @returns The local Blueprint, issues, and maybe a deployed Stack

package/dist/actions/blueprints/index.js

@@ -9,6 +9,7 @@ import { readLocalBlueprint } from './blueprint.js';
 import { getStack } from './stacks.js';
 /**
  * Get the local Blueprint and deployed Stack
+ * @deprecated Use initBlueprintConfig or initDeployedBlueprintConfig instead
  * @param blueprintPath - The path of the Blueprint file or directory- will search up the directory tree if not provided
  * @param token - The Sanity API token
  * @returns The local Blueprint, issues, and maybe a deployed Stack

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

@@ -3,15 +3,16 @@ interface FunctionResourceOptions {
     name: string;
     type: string;
     lang: string;
-    displayName?: string;
     blueprintFilePath?: string;
+    addHelpers?: boolean;
+    installCommand?: string | null;
 }
 /**
  * Creates a new function resource file and adds it to the blueprint
  */
-export declare function createFunctionResource(options: FunctionResourceOptions): {
+export declare function createFunctionResource(options: FunctionResourceOptions): Promise<{
     filePath: string;
     resourceAdded: boolean;
     resource: LocalFunctionResource;
-};
+}>;
 export {};

package/dist/actions/blueprints/resources.js

@@ -1,12 +1,20 @@
+import { spawn } from 'node:child_process';
 import { mkdirSync, writeFileSync } from 'node:fs';
 import { existsSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { cwd } from 'node:process';
+import chalk from 'chalk';
 import { addResourceToBlueprint } from './blueprint.js';
 const DEFAULT_FUNCTION_TEMPLATE = /*js*/ `export async function handler({context, event}) {
   const time = new Date().toLocaleTimeString()
   console.log(\`👋 Your Sanity Function was called at \${time}\`)
 }`;
+const DEFAULT_HELPER_FUNCTION_TEMPLATE = /*ts*/ `import { documentEventHandler } from '@sanity/functions'
+
+export const handler = documentEventHandler(async ({ context, event }) => {
+  const time = new Date().toLocaleTimeString()
+  console.log(\`👋 Your Sanity Function was called at \${time}\`)
+})`;
 const DEFAULT_PACKAGE_JSON = {
     name: '',
     type: 'module',
@@ -15,8 +23,8 @@ const DEFAULT_PACKAGE_JSON = {
 /**
  * Creates a new function resource file and adds it to the blueprint
  */
-export function createFunctionResource(options) {
-    const { name, type, lang, displayName = name, blueprintFilePath } = options;
+export async function createFunctionResource(options) {
+    const { name, type, lang, blueprintFilePath, addHelpers = false, installCommand } = options;
     let workingDir = cwd();
     if (blueprintFilePath) {
         if (!existsSync(blueprintFilePath)) {
@@ -31,29 +39,41 @@ export function createFunctionResource(options) {
     }
     // Create function directory
     const functionDir = join(functionsDir, name);
-    if (!existsSync(functionDir)) {
-        mkdirSync(functionDir, { recursive: true });
-    }
+    if (existsSync(functionDir))
+        throw Error(`${functionDir} already exists`);
+    mkdirSync(functionDir, { recursive: true });
     if (!['ts', 'js'].includes(lang))
         throw Error(`Unsupported language: ${lang}`);
     // Create index.<lang> with default template
     const indexPath = join(functionDir, `index.${lang}`);
-    writeFileSync(indexPath, DEFAULT_FUNCTION_TEMPLATE);
+    writeFileSync(indexPath, addHelpers ? DEFAULT_HELPER_FUNCTION_TEMPLATE : DEFAULT_FUNCTION_TEMPLATE);
     // Create package.json
     const packagePath = join(functionDir, 'package.json');
     const packageContent = {
         ...DEFAULT_PACKAGE_JSON,
         name,
         main: `index.${lang}`,
+        dependencies: {},
     };
+    if (addHelpers) {
+        const helpersVersion = await getLatestNpmVersion('@sanity/functions');
+        packageContent.dependencies = {
+            '@sanity/functions': helpersVersion,
+        };
+    }
     writeFileSync(packagePath, JSON.stringify(packageContent, null, 2));
+    if (installCommand) {
+        const success = await runPackageInstall(functionDir, installCommand);
+        if (!success) {
+            throw new Error(`Failed to install dependencies using \`${installCommand}\``);
+        }
+    }
     // type looks like 'document-publish'
     const typeParts = type.split('-');
     const typeName = typeParts[0];
     const eventOn = typeParts[1];
     // Create resource definition
     const resourceJson = {
-        displayName,
         name,
         src: `functions/${name}`,
         type: `sanity.function.${typeName}`,
@@ -69,3 +89,37 @@ export function createFunctionResource(options) {
         resource: resource || resourceJson,
     };
 }
+async function getLatestNpmVersion(pkg) {
+    const url = `https://registry.npmjs.org/${pkg}/latest`;
+    try {
+        const res = await fetch(url);
+        if (!res.ok)
+            throw new Error(`Failed to fetch version for ${pkg}`);
+        const data = await res.json();
+        return data.version;
+    }
+    catch (error) {
+        return 'latest';
+    }
+}
+async function runPackageInstall(cwd, command) {
+    return new Promise((resolve) => {
+        const install = spawn(command, ['install'], { cwd });
+        const formatOutput = (data) => {
+            const lines = data.toString().split('\n');
+            return lines
+                .filter(Boolean)
+                .map((line) => `  ${chalk.magenta('│')} ${chalk.dim(line)}`)
+                .join('\n');
+        };
+        install.stdout?.on('data', (data) => {
+            console.log(formatOutput(data));
+        });
+        install.stderr?.on('data', (data) => {
+            console.error(formatOutput(data));
+        });
+        install.on('close', (code) => {
+            resolve(code === 0);
+        });
+    });
+}

package/dist/baseCommands.d.ts

@@ -1,6 +1,6 @@
 import { Command } from '@oclif/core';
 import type { Interfaces } from '@oclif/core';
-import { readLocalBlueprint } from './actions/blueprints/blueprint.js';
+import type { readLocalBlueprint } from './actions/blueprints/blueprint.js';
 import type { AuthParams, Stack } from './utils/types.js';
 export type Flags<T extends typeof Command> = Interfaces.InferredFlags<(typeof BlueprintCommand)['baseFlags'] & T['flags']>;
 export type Args<T extends typeof Command> = Interfaces.InferredArgs<T['args']>;

package/dist/baseCommands.js

@@ -1,9 +1,6 @@
 // * https://oclif.io/docs/base_class
 import { Command } from '@oclif/core';
-import { readLocalBlueprint } from './actions/blueprints/blueprint.js';
-import { getStack } from './actions/blueprints/stacks.js';
-import { presentBlueprintParserErrors } from './utils/display/errors.js';
-import { niceId } from './utils/display/presenters.js';
+import { initBlueprintConfig, initDeployedBlueprintConfig } from './cores/index.js';
 import { validTokenOrErrorMessage } from './utils/validated-token.js';
 /**
  * @description Guarantees flags, args, sanityToken, and blueprint.
@@ -30,12 +27,12 @@ export class BlueprintCommand extends Command {
         if (tokenErr)
             this.error(tokenErr.message);
         this.sanityToken = token;
-        const blueprint = await readLocalBlueprint();
-        if (blueprint.errors.length > 0) {
-            this.log(presentBlueprintParserErrors(blueprint.errors));
-            this.error('Unable to parse Blueprint file.');
+        const result = await initBlueprintConfig(this.config.bin, (msg) => this.log(msg), token);
+        if (!result.ok) {
+            this.error(result.error);
         }
-        this.blueprint = blueprint;
+        this.sanityToken = result.value.sanityToken;
+        this.blueprint = result.value.blueprint;
     }
     async catch(err) {
         // add any custom logic to handle errors from the command
@@ -59,23 +56,18 @@ export class DeployedBlueprintCommand extends BlueprintCommand {
     stackId;
     async init() {
         await super.init();
-        const { projectId, stackId } = this.blueprint;
-        if (!(projectId && stackId)) {
-            this.log(`Run \`${this.config.bin} blueprints config --edit --test\` to update your config`);
-            if (!projectId)
-                this.error('Missing Project configuration for Blueprint');
-            if (!stackId)
-                this.error('Missing deployment configuration for Blueprint');
-        }
-        this.projectId = projectId;
-        this.stackId = stackId;
-        this.auth = { token: this.sanityToken, projectId };
-        const stackResponse = await getStack({ stackId, auth: this.auth });
-        if (!stackResponse.ok) {
-            this.log(`Could not retrieve deployment info for ${niceId(stackId)}. Was it destroyed?`);
-            this.log(`Run \`${this.config.bin} blueprints config --edit --test\` to update your config`);
-            this.error('Missing deployment');
+        const result = await initDeployedBlueprintConfig({
+            bin: this.config.bin,
+            blueprint: this.blueprint,
+            log: (msg) => this.log(msg),
+            sanityToken: this.sanityToken,
+        });
+        if (!result.ok) {
+            this.error(result.error);
         }
-        this.deployedStack = stackResponse.stack;
+        this.projectId = result.value.projectId;
+        this.stackId = result.value.stackId;
+        this.auth = result.value.auth;
+        this.deployedStack = result.value.deployedStack;
     }
 }

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

@@ -1,5 +1,5 @@
-import { Command } from '@oclif/core';
-export default class AddCommand extends Command {
+import { BlueprintCommand } from '../../baseCommands.js';
+export default class AddCommand extends BlueprintCommand<typeof AddCommand> {
     static description: string;
     static examples: string[];
     static args: {
@@ -10,6 +10,9 @@ export default class AddCommand extends Command {
         'fn-type': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         language: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         javascript: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'fn-helpers': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'fn-installer': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        install: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;
 }

package/dist/commands/blueprints/add.js

@@ -1,9 +1,11 @@
-import { Args, Command, Flags } from '@oclif/core';
+import { Args, Flags } from '@oclif/core';
+import { BlueprintCommand } from '../../baseCommands.js';
 import { blueprintAddCore } from '../../cores/blueprints/index.js';
-export default class AddCommand extends Command {
+export default class AddCommand extends BlueprintCommand {
     static description = 'Add a Resource to a Blueprint';
     static examples = [
         '<%= config.bin %> <%= command.id %> function',
+        '<%= config.bin %> <%= command.id %> function --helpers',
         '<%= config.bin %> <%= command.id %> function --name my-function',
         '<%= config.bin %> <%= command.id %> function --name my-function --fn-type document-publish',
         '<%= config.bin %> <%= command.id %> function --name my-function --fn-type document-publish --lang js',
@@ -37,14 +39,30 @@ export default class AddCommand extends Command {
             description: 'Use JavaScript instead of TypeScript',
             aliases: ['js'],
         }),
+        'fn-helpers': Flags.boolean({
+            description: 'Add helpers to the new Function',
+            aliases: ['function-helpers', 'helpers'],
+            default: true,
+            allowNo: true,
+        }),
+        'fn-installer': Flags.string({
+            description: 'How to install the @sanity/functions helpers',
+            aliases: ['function-installer', 'installer'],
+            options: ['skip', 'npm', 'pnpm', 'yarn'],
+        }),
+        install: Flags.boolean({
+            description: 'Shortcut for --fn-installer npm',
+            char: 'i',
+            exclusive: ['fn-installer'],
+        }),
     };
     async run() {
-        const { args, flags } = await this.parse(AddCommand);
         const { success, error } = await blueprintAddCore({
             bin: this.config.bin,
             log: (msg) => this.log(msg),
-            args,
-            flags,
+            blueprint: this.blueprint,
+            args: this.args,
+            flags: this.flags,
         });
         if (!success)
             this.error(error);

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

@@ -1,9 +1,6 @@
 import { Args } from '@oclif/core';
-import chalk from 'chalk';
-import ora from 'ora';
-import { update } from '../../../actions/functions/env/update.js';
 import { DeployedBlueprintCommand } from '../../../baseCommands.js';
-import { findFunctionByName } from '../../../utils/find-function.js';
+import { envAddCore } from '../../../cores/functions/env/add.js';
 export default class EnvAddCommand extends DeployedBlueprintCommand {
     static args = {
         name: Args.string({ description: 'The name of the Sanity Function', required: true }),
@@ -15,16 +12,18 @@ export default class EnvAddCommand extends DeployedBlueprintCommand {
         '<%= config.bin %> <%= command.id %> MyFunction API_URL https://api.example.com/',
     ];
     async run() {
-        const args = this.args;
-        const spinner = ora(`Updating "${args.key}" environment variable in "${args.name}"`).start();
-        const { externalId } = findFunctionByName(this.deployedStack, args.name);
-        const result = await update(externalId, args.key, args.value, this.auth);
-        if (result.ok) {
-            spinner.succeed(`Update of ${args.key} succeeded`);
-        }
-        else {
-            spinner.fail(`${chalk.red('Failed')} to update ${args.key}`);
-            this.log(`Error: ${result.error || 'Unknown error'}`);
-        }
+        const { success, error } = await envAddCore({
+            bin: this.config.bin,
+            log: (msg) => this.log(msg),
+            args: this.args,
+            auth: this.auth,
+            blueprint: this.blueprint,
+            deployedStack: this.deployedStack,
+            projectId: this.projectId,
+            sanityToken: this.sanityToken,
+            stackId: this.stackId,
+        });
+        if (!success)
+            this.error(error);
     }
 }

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

@@ -1,8 +1,6 @@
 import { Args } from '@oclif/core';
-import ora from 'ora';
-import { list } from '../../../actions/functions/env/list.js';
 import { DeployedBlueprintCommand } from '../../../baseCommands.js';
-import { findFunctionByName } from '../../../utils/find-function.js';
+import { envListCore } from '../../../cores/functions/env/list.js';
 export default class EnvListCommand extends DeployedBlueprintCommand {
     static args = {
         name: Args.string({ description: 'The name of the Sanity Function', required: true }),
@@ -10,17 +8,18 @@ export default class EnvListCommand extends DeployedBlueprintCommand {
     static description = 'List the environment variables for a Sanity function';
     static examples = ['<%= config.bin %> <%= command.id %> MyFunction'];
     async run() {
-        const args = this.args;
-        const spinner = ora(`Listing environment variables for "${args.name}"`).start();
-        const { externalId } = findFunctionByName(this.deployedStack, args.name);
-        const result = await list(externalId, this.auth);
-        if (!result.ok) {
-            spinner.stop();
-            this.error(`Error: ${result.error || 'Unknown error'}`);
-        }
-        spinner.succeed(`Environment variables for "${args.name}"`);
-        for (const key of result.envvars) {
-            this.log(key);
-        }
+        const { success, error } = await envListCore({
+            bin: this.config.bin,
+            log: (msg) => this.log(msg),
+            args: this.args,
+            auth: this.auth,
+            blueprint: this.blueprint,
+            deployedStack: this.deployedStack,
+            projectId: this.projectId,
+            sanityToken: this.sanityToken,
+            stackId: this.stackId,
+        });
+        if (!success)
+            this.error(error);
     }
 }

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

@@ -1,9 +1,6 @@
 import { Args } from '@oclif/core';
-import chalk from 'chalk';
-import ora from 'ora';
-import { remove } from '../../../actions/functions/env/remove.js';
 import { DeployedBlueprintCommand } from '../../../baseCommands.js';
-import { findFunctionByName } from '../../../utils/find-function.js';
+import { envRemoveCore } from '../../../cores/functions/env/remove.js';
 export default class EnvRemoveCommand extends DeployedBlueprintCommand {
     static args = {
         name: Args.string({ description: 'The name of the Sanity Function', required: true }),
@@ -12,16 +9,18 @@ export default class EnvRemoveCommand extends DeployedBlueprintCommand {
     static description = 'Remove an environment variable for a Sanity function';
     static examples = ['<%= config.bin %> <%= command.id %> MyFunction API_URL'];
     async run() {
-        const args = this.args;
-        const spinner = ora(`Removing "${args.key}" environment variable in "${args.name}"`).start();
-        const { externalId } = findFunctionByName(this.deployedStack, args.name);
-        const result = await remove(externalId, args.key, this.auth);
-        if (result.ok) {
-            spinner.succeed(`Removal of ${args.key} succeeded`);
-        }
-        else {
-            spinner.fail(`${chalk.red('Failed')} to remove ${args.key}`);
-            this.log(`Error: ${result.error || 'Unknown error'}`);
-        }
+        const { success, error } = await envRemoveCore({
+            bin: this.config.bin,
+            log: (msg) => this.log(msg),
+            args: this.args,
+            auth: this.auth,
+            blueprint: this.blueprint,
+            deployedStack: this.deployedStack,
+            projectId: this.projectId,
+            sanityToken: this.sanityToken,
+            stackId: this.stackId,
+        });
+        if (!success)
+            this.error(error);
     }
 }

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

@@ -1,5 +1,7 @@
+import type { ReadBlueprintResult } from '../../actions/blueprints/blueprint.js';
 import type { CoreConfig, CoreResult } from '../index.js';
 export interface BlueprintAddOptions extends CoreConfig {
+    blueprint: ReadBlueprintResult;
     args: {
         type: string;
     };
@@ -8,6 +10,9 @@ export interface BlueprintAddOptions extends CoreConfig {
         'fn-type'?: string;
         language?: string;
         javascript?: boolean;
+        'fn-helpers'?: boolean;
+        'fn-installer'?: string;
+        install?: boolean;
     };
 }
 export declare function blueprintAddCore(options: BlueprintAddOptions): Promise<CoreResult>;

package/dist/cores/blueprints/add.js

@@ -2,15 +2,28 @@ import { cwd } from 'node:process';
 import chalk from 'chalk';
 import highlight from 'color-json';
 import inquirer from 'inquirer';
-import { findBlueprintFile } from '../../actions/blueprints/blueprint.js';
 import { createFunctionResource } from '../../actions/blueprints/resources.js';
 import { validateFunctionName } from '../../utils/validate/resource.js';
 export async function blueprintAddCore(options) {
-    const { bin = 'sanity', log, args, flags } = options;
+    const { bin = 'sanity', log, blueprint, args, flags } = options;
     const { type: resourceType } = args;
-    const { name: flagResourceName, 'fn-type': flagFnType, javascript: flagJs } = flags;
-    let { language: flagFnLang } = flags;
+    const { name: flagResourceName, 'fn-type': flagFnType, javascript: flagJs, 'fn-helpers': flagFnHelpers, install: flagI, } = flags;
+    let { language: flagFnLang, 'fn-installer': flagFnInstaller, // can be 'skip'!
+     } = flags;
     flagFnLang = flagJs ? 'js' : flagFnLang;
+    flagFnInstaller = flagFnInstaller === 'skip' ? undefined : flagFnInstaller;
+    if (flagI && flagFnInstaller) {
+        return {
+            success: false,
+            error: 'Cannot use -i flag with the --fn-installer flag',
+        };
+    }
+    if (flagI && !flagFnHelpers) {
+        return {
+            success: false,
+            error: 'Cannot use -i flag with the --no-fn-helpers flag',
+        };
+    }
     try {
         if (resourceType !== 'function') {
             return {
@@ -18,37 +31,71 @@ export async function blueprintAddCore(options) {
                 error: `Unsupported Resource type: ${resourceType}`,
             };
         }
-        const existingBlueprint = findBlueprintFile();
-        if (!existingBlueprint) {
+        if (flagResourceName && !validateFunctionName(flagResourceName)) {
+            // if provided && invalid, return error
             return {
                 success: false,
-                error: `No Blueprint file found. Run \`${bin} blueprints init\` first.`,
+                error: `Invalid function name: ${flagResourceName}`,
             };
         }
         const fnName = flagResourceName || (await promptForFunctionName());
-        if (!validateFunctionName(fnName)) {
-            throw new Error('Invalid function name. Must be 6+ characters, no special characters, no spaces');
+        // look for existing function with same name
+        if (blueprint.parsedBlueprint.resources?.some((r) => r.name === fnName)) {
+            return {
+                success: false,
+                error: `Function "${chalk.bold(fnName)}" already exists.`,
+            };
         }
         const fnType = flagFnType || (await promptForFunctionType());
         const fnLang = flagFnLang || (await promptForFunctionLang());
         if (!['document-publish', 'document-create', 'document-delete'].includes(fnType)) {
             throw new Error('Invalid function type. Must be one of: document-publish, document-create, document-delete');
         }
-        const { filePath, resourceAdded, resource } = createFunctionResource({
+        let addHelpers;
+        let installCommand;
+        if (!['ts', 'js'].includes(fnLang)) {
+            // language is not supported
+            addHelpers = false;
+            installCommand = null;
+        }
+        else if (!flagFnHelpers) {
+            // user does not want helpers: "--no-fn-helpers"
+            addHelpers = false;
+            installCommand = null;
+        }
+        else if (flagI) {
+            // user wants to install helpers with npm
+            addHelpers = true;
+            installCommand = 'npm';
+        }
+        else if (flagFnInstaller) {
+            // user wants to install helpers using a specific command
+            addHelpers = true;
+            installCommand = flagFnInstaller;
+        }
+        else {
+            // unsure; ask...
+            addHelpers = flagFnHelpers || (await promptForAddHelpers());
+            installCommand = addHelpers ? await promptForInstallCommand() : null;
+        }
+        if (installCommand)
+            log(`${chalk.magenta('Installing')} with ${installCommand}...`);
+        const { filePath, resourceAdded, resource } = await createFunctionResource({
             name: fnName,
             type: fnType,
             lang: fnLang,
-            displayName: fnName,
+            addHelpers,
+            installCommand,
         });
         log(`\nCreated function: ${filePath.replace(cwd(), '')}`);
         if (!resourceAdded) {
             // print the resource JSON for manual addition
             log('\nAdd this Function resource to your blueprint:');
-            log(highlight(JSON.stringify(resource, null, 2)));
+            log(highlight(JSON.stringify(resource, null, 2), undefined, undefined, 2));
         }
         else {
             // added to blueprint.json
-            log(`Function "${chalk.bold(fnName)}" added to blueprint file.`);
+            log(`Function "${chalk.bold(fnName)}" added to Blueprint file.`);
         }
         if (fnLang === 'ts') {
             log(chalk.dim('Add "functions/**/.build/**" to your .gitignore.'));
@@ -69,7 +116,8 @@ async function promptForFunctionName() {
             type: 'input',
             name: 'functionName',
             message: 'Enter function name:',
-            validate: (input) => input.length > 0 || 'Function name is required',
+            validate: (input) => validateFunctionName(input) ||
+                'Invalid function name. Must be 6+ characters, no special characters, no spaces',
         },
     ]);
     return functionName;
@@ -105,3 +153,31 @@ async function promptForFunctionLang() {
     ]);
     return functionLang;
 }
+async function promptForAddHelpers() {
+    const { addHelpers } = await inquirer.prompt([
+        {
+            type: 'confirm',
+            name: 'addHelpers',
+            message: 'Add @sanity/functions helpers to the new Function?',
+            default: true,
+        },
+    ]);
+    return addHelpers;
+}
+async function promptForInstallCommand() {
+    const { command } = await inquirer.prompt([
+        {
+            type: 'list',
+            name: 'command',
+            message: 'How to install the @sanity/functions helpers:',
+            choices: [
+                { name: 'npm', value: 'npm' },
+                { name: 'pnpm', value: 'pnpm' },
+                { name: 'yarn', value: 'yarn' },
+                { name: 'Skip install', value: null },
+            ],
+            default: 'npm',
+        },
+    ]);
+    return command;
+}

package/dist/cores/functions/env/add.d.ts

@@ -0,0 +1,9 @@
+import type { CoreResult, DeployedBlueprintConfig } from '../../index.js';
+export interface EnvAddOptions extends DeployedBlueprintConfig {
+    args: {
+        name: string;
+        key: string;
+        value: string;
+    };
+}
+export declare function envAddCore(options: EnvAddOptions): Promise<CoreResult>;

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

@@ -0,0 +1,19 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import { update } from '../../../actions/functions/env/update.js';
+import { findFunctionByName } from '../../../utils/find-function.js';
+export async function envAddCore(options) {
+    const args = options.args;
+    const spinner = ora(`Updating "${args.key}" environment variable in "${args.name}"`).start();
+    const { externalId } = findFunctionByName(options.deployedStack, args.name);
+    const result = await update(externalId, args.key, args.value, options.auth);
+    if (!result.ok) {
+        spinner.fail(`${chalk.red('Failed')} to update ${args.key}`);
+        return {
+            success: false,
+            error: result.error || 'Unknown error',
+        };
+    }
+    spinner.succeed(`Update of ${args.key} succeeded`);
+    return { success: true };
+}

package/dist/cores/functions/env/list.d.ts

@@ -0,0 +1,7 @@
+import type { CoreResult, DeployedBlueprintConfig } from '../../index.js';
+export interface EnvListOptions extends DeployedBlueprintConfig {
+    args: {
+        name: string;
+    };
+}
+export declare function envListCore(options: EnvListOptions): Promise<CoreResult>;

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

@@ -0,0 +1,18 @@
+import ora from 'ora';
+import { list } from '../../../actions/functions/env/list.js';
+import { findFunctionByName } from '../../../utils/find-function.js';
+export async function envListCore(options) {
+    const args = options.args;
+    const spinner = ora(`Listing environment variables for "${args.name}"`).start();
+    const { externalId } = findFunctionByName(options.deployedStack, args.name);
+    const result = await list(externalId, options.auth);
+    if (!result.ok) {
+        spinner.stop();
+        return { success: false, error: result.error || 'Unknown error' };
+    }
+    spinner.succeed(`Environment variables for "${args.name}"`);
+    for (const key of result.envvars) {
+        options.log(key);
+    }
+    return { success: true };
+}

package/dist/cores/functions/env/remove.d.ts

@@ -0,0 +1,8 @@
+import type { CoreResult, DeployedBlueprintConfig } from '../../index.js';
+export interface EnvRemoveOptions extends DeployedBlueprintConfig {
+    args: {
+        name: string;
+        key: string;
+    };
+}
+export declare function envRemoveCore(options: EnvRemoveOptions): Promise<CoreResult>;

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

@@ -0,0 +1,16 @@
+import chalk from 'chalk';
+import ora from 'ora';
+import { remove } from '../../../actions/functions/env/remove.js';
+import { findFunctionByName } from '../../../utils/find-function.js';
+export async function envRemoveCore(options) {
+    const args = options.args;
+    const spinner = ora(`Removing "${args.key}" environment variable in "${args.name}"`).start();
+    const { externalId } = findFunctionByName(options.deployedStack, args.name);
+    const result = await remove(externalId, args.key, options.auth);
+    if (!result.ok) {
+        spinner.fail(`${chalk.red('Failed')} to remove ${args.key}`);
+        return { success: false, error: result.error || 'Unknown error' };
+    }
+    spinner.succeed(`Removal of ${args.key} succeeded`);
+    return { success: true };
+}

package/dist/cores/functions/index.d.ts

@@ -0,0 +1,6 @@
+export { envAddCore } from './env/add.js';
+export type { EnvAddOptions } from './env/add.js';
+export { envListCore } from './env/list.js';
+export type { EnvListOptions } from './env/list.js';
+export { envRemoveCore } from './env/remove.js';
+export type { EnvRemoveOptions } from './env/remove.js';

package/dist/cores/functions/index.js

@@ -0,0 +1,3 @@
+export { envAddCore } from './env/add.js';
+export { envListCore } from './env/list.js';
+export { envRemoveCore } from './env/remove.js';

package/dist/cores/index.d.ts

@@ -1,10 +1,23 @@
+import { type ReadBlueprintResult } from '../actions/blueprints/blueprint.js';
+import type { AuthParams, Result, Stack } from '../utils/types.js';
 export * as blueprintsCores from './blueprints/index.js';
+export * as functionsCores from './functions/index.js';
 export interface CoreConfig {
     /** The CLI binary name. */
     bin: string;
     /** The log output function. */
     log: (message: string) => void;
 }
+export interface BlueprintConfig extends CoreConfig {
+    sanityToken: string;
+    blueprint: ReadBlueprintResult;
+}
+export interface DeployedBlueprintConfig extends BlueprintConfig {
+    stackId: string;
+    projectId: string;
+    auth: AuthParams;
+    deployedStack: Stack;
+}
 export type CoreResult = {
     /** Something went wrong. */
     success: false;
@@ -18,3 +31,5 @@ export type CoreResult = {
     streaming?: Promise<void>;
     error?: never;
 };
+export declare function initBlueprintConfig(bin: string, log: (msg: string) => void, token: string): Promise<Result<BlueprintConfig>>;
+export declare function initDeployedBlueprintConfig(config: Partial<BlueprintConfig> & Pick<BlueprintConfig, 'bin' | 'log' | 'sanityToken'>): Promise<Result<DeployedBlueprintConfig>>;

package/dist/cores/index.js

@@ -1 +1,60 @@
+import { readLocalBlueprint } from '../actions/blueprints/blueprint.js';
+import { getStack } from '../actions/blueprints/stacks.js';
+import { presentBlueprintParserErrors } from '../utils/display/errors.js';
+import { niceId } from '../utils/display/presenters.js';
 export * as blueprintsCores from './blueprints/index.js';
+export * as functionsCores from './functions/index.js';
+export async function initBlueprintConfig(bin, log, token) {
+    const blueprint = await readLocalBlueprint();
+    if (blueprint.errors.length > 0) {
+        log(presentBlueprintParserErrors(blueprint.errors));
+        return { ok: false, error: 'Unable to parse Blueprint file.' };
+    }
+    return {
+        ok: true,
+        value: {
+            bin,
+            blueprint,
+            log,
+            sanityToken: token,
+        },
+    };
+}
+export async function initDeployedBlueprintConfig(config) {
+    if (!config.blueprint) {
+        const blueprintResult = await initBlueprintConfig(config.bin, config.log, config.sanityToken);
+        if (!blueprintResult.ok) {
+            return blueprintResult;
+        }
+        config.blueprint = blueprintResult.value.blueprint;
+        config.sanityToken = blueprintResult.value.sanityToken;
+    }
+    const { projectId, stackId } = config.blueprint;
+    if (!(projectId && stackId)) {
+        config.log(`Run \`${config.bin} blueprints config --edit --test\` to update your config`);
+        if (!projectId)
+            return { ok: false, error: 'Missing Project configuration for Blueprint' };
+        if (!stackId)
+            return { ok: false, error: 'Missing deployment configuration for Blueprint' };
+    }
+    const auth = { token: config.sanityToken, projectId };
+    const stackResponse = await getStack({ stackId, auth });
+    if (!stackResponse.ok) {
+        config.log(`Could not retrieve deployment info for ${niceId(stackId)}. Was it destroyed?`);
+        config.log(`Run \`${config.bin} blueprints config --edit --test\` to update your config`);
+        return { ok: false, error: 'Missing deployment' };
+    }
+    return {
+        ok: true,
+        value: {
+            bin: config.bin,
+            log: config.log,
+            blueprint: config.blueprint,
+            sanityToken: config.sanityToken,
+            projectId,
+            stackId,
+            auth,
+            deployedStack: stackResponse.stack,
+        },
+    };
+}

package/dist/utils/child-process-wrapper.d.ts

@@ -1 +1 @@
-export function getFunctionSource(src: any): any;
+export function getFunctionSource(src: any): string;

package/dist/utils/child-process-wrapper.js

@@ -10,9 +10,9 @@ export function getFunctionSource(src) {
     if (!existsSync(indexPath)) {
       throw Error(`Function directory ${pathToCheck} has no index.js`)
     }
-    return indexPath
+    return `file://${indexPath}`
   }
-  return pathToCheck
+  return `file://${pathToCheck}`
 }
 
 // Start when payload data arrives from parent process

package/dist/utils/invoke-local.js

@@ -2,12 +2,13 @@ import { spawn } from 'node:child_process';
 import { performance } from 'node:perf_hooks';
 import { cwd } from 'node:process';
 import { setTimeout } from 'node:timers';
+import { fileURLToPath } from 'node:url';
 import config from '../config.js';
 import { bundleFunction } from './bundle/bundle-function.js';
 import { findFunctionEntryPoint } from './functions/find-entry-point.js';
 import { shouldBundleFunction } from './functions/should-bundle.js';
 function getChildProcessWrapperPath() {
-    return new URL('./child-process-wrapper.js', import.meta.url).pathname;
+    return fileURLToPath(new URL('./child-process-wrapper.js', import.meta.url));
 }
 export function sanitizeLogs(logs) {
     return logs.replace(/([a-zA-Z0-9]{10})[a-zA-Z0-9]{65,}/g, '$1**********');

package/dist/utils/types.d.ts

@@ -1,3 +1,11 @@
+/** Result utility type */
+export type Result<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: string;
+};
 /** @internal */
 export interface AuthParams {
     token: string;

package/oclif.manifest.json

@@ -15,6 +15,7 @@
       "description": "Add a Resource to a Blueprint",
       "examples": [
         "<%= config.bin %> <%= command.id %> function",
+        "<%= config.bin %> <%= command.id %> function --helpers",
         "<%= config.bin %> <%= command.id %> function --name my-function",
         "<%= config.bin %> <%= command.id %> function --name my-function --fn-type document-publish",
         "<%= config.bin %> <%= command.id %> function --name my-function --fn-type document-publish --lang js"
@@ -68,6 +69,43 @@
           "name": "javascript",
           "allowNo": false,
           "type": "boolean"
+        },
+        "fn-helpers": {
+          "aliases": [
+            "function-helpers",
+            "helpers"
+          ],
+          "description": "Add helpers to the new Function",
+          "name": "fn-helpers",
+          "allowNo": true,
+          "type": "boolean"
+        },
+        "fn-installer": {
+          "aliases": [
+            "function-installer",
+            "installer"
+          ],
+          "description": "How to install the @sanity/functions helpers",
+          "name": "fn-installer",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "skip",
+            "npm",
+            "pnpm",
+            "yarn"
+          ],
+          "type": "option"
+        },
+        "install": {
+          "char": "i",
+          "description": "Shortcut for --fn-installer npm",
+          "exclusive": [
+            "fn-installer"
+          ],
+          "name": "install",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
@@ -77,7 +115,6 @@
       "pluginName": "@sanity/runtime-cli",
       "pluginType": "core",
       "strict": true,
-      "enableJsonFlag": false,
       "isESM": true,
       "relativePath": [
         "dist",
@@ -790,5 +827,5 @@
       ]
     }
   },
-  "version": "6.2.1"
+  "version": "7.0.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sanity/runtime-cli",
   "description": "Sanity's Runtime CLI for Blueprints and Functions",
-  "version": "6.2.1",
+  "version": "7.0.0",
   "author": "Sanity Runtime Team",
   "type": "module",
   "license": "MIT",
@@ -23,10 +23,18 @@
       "types": "./dist/actions/functions/index.d.ts",
       "import": "./dist/actions/functions/index.js"
     },
+    "./cores": {
+      "types": "./dist/cores/index.d.ts",
+      "import": "./dist/cores/index.js"
+    },
     "./cores/blueprints": {
       "types": "./dist/cores/blueprints/index.d.ts",
       "import": "./dist/cores/blueprints/index.js"
     },
+    "./cores/functions": {
+      "types": "./dist/cores/functions/index.d.ts",
+      "import": "./dist/cores/functions/index.js"
+    },
     "./utils": {
       "types": "./dist/utils/index.d.ts",
       "import": "./dist/utils/index.js"