@sanity/runtime-cli 17.8.0-next.g5972da4 → 17.9.0-blueprinit.g14aaebd

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

@@ -41,7 +41,7 @@ process.on('message', async (data) => {
 
   // Otherwise this is the initial start message. Support the legacy untyped
   // `{srcPath, payload}` shape as well as the new `{type: 'start', ...}`.
-  const {srcPath, payload, isDurable} = jsonData
+  const {srcPath, payload, isDurable, noWait} = jsonData
   const {context, ...event} = payload
 
   let logs = ''
@@ -83,9 +83,10 @@ process.on('message', async (data) => {
     if (isDurable) {
       json = await runDurable(
         handler,
-        {context, event, logger: console},
+        {context, event},
         {
           emit: (e) => process.send(JSON.stringify({type: 'step-event', event: e})),
+          wait: (ms) => new Promise((resolve) => setTimeout(resolve, noWait ? 0 : ms)),
         },
       )
     } else {

package/dist/utils/functions/child-runtime/durable.d.ts

@@ -1,5 +1,5 @@
 import type {DurableContext, DurableHandler, DurableLogger, GenericEvent} from '@sanity/functions'
-import type {DurableStepEvent} from '../../types.js'
+import type {DurableRuntimeEvent} from '../../types.js'
 
 type RunDurableArgs = {
   context: DurableContext
@@ -8,7 +8,7 @@ type RunDurableArgs = {
 }
 
 type DurableIO = {
-  emit: (event: DurableStepEvent) => void
+  emit: (event: DurableRuntimeEvent) => void
 }
 
 export function runDurable(

package/dist/utils/functions/child-runtime/durable.js

@@ -1,17 +1,60 @@
 import {performance} from 'node:perf_hooks'
+import {inspect} from 'node:util'
+
+/**
+ *
+ * @param duration
+ * @return {number}
+ */
+const durationToMs = (duration = {}) => {
+  const {days = 0, hours = 0, minutes = 0, seconds = 0} = duration
+  return (((days * 24 + hours) * 60 + minutes) * 60 + seconds) * 1000
+}
+
+/**
+ *
+ * @param args
+ */
+const formatArgs = (args) =>
+  args.map((a) => (typeof a === 'string' ? a : inspect(a, {depth: null}))).join(' ')
 
 /**
  * Runs a durable function handler
  * @param handler - callback being run
  * @param context - data to send to the operation
  * @param event - the step being run
- * @param logger
  * @param io
  */
-export async function runDurable(handler, {context, event, logger}, io) {
+export async function runDurable(handler, {context, event}, io) {
+  let currentStep = null
+  const streamLog = (level, args) => {
+    const date = new Date()
+    const timestamp = `${date.toLocaleDateString()} ${date.toLocaleTimeString()}`
+
+    return io.emit({
+      timestamp,
+      kind: 'log',
+      phase: 'log',
+      step: currentStep,
+      level,
+      message: formatArgs(args),
+    })
+  }
+
+  // @todo: need to throw error for use of `console.log` in a durable function
+  const logger = {
+    log: (...a) => streamLog('info', a),
+    info: (...a) => streamLog('info', a),
+    warn: (...a) => streamLog('warn', a),
+    error: (...a) => streamLog('error', a),
+  }
+
   const track = async (name, kind, produce) => {
     io.emit({name, kind, phase: 'start'})
     const startedAt = performance.now()
+    const prev = currentStep
+    currentStep = name
+
     try {
       const value = await produce()
       io.emit({
@@ -35,11 +78,18 @@ export async function runDurable(handler, {context, event, logger}, io) {
         durationMs: performance.now() - startedAt,
       })
       throw err
+    } finally {
+      currentStep = prev
     }
   }
 
   const step = {
     run: ({name, handler: fn}) => track(name || 'step-run', 'run', () => fn({logger, attempt: 1})),
+    wait: ({name, duration}) =>
+      track(name, 'wait', async () => {
+        await io.wait(durationToMs(duration))
+        return undefined
+      }),
   }
 
   return handler({context, event, step, logger})

package/dist/utils/functions/durable-logs.d.ts

@@ -0,0 +1,16 @@
+import type { DurableLogEvent, DurableRuntimeEvent, DurableStepEvent } from '../types.js';
+type DurableLogLine = Pick<DurableLogEvent, 'level' | 'message'>;
+type DurableJsonStep = DurableStepEvent & {
+    logs: DurableLogLine[];
+};
+/**
+ * Records a durable log event
+ */
+export declare const createDurableJsonCollector: () => {
+    record: (event: DurableRuntimeEvent) => void;
+    result: () => {
+        steps: DurableJsonStep[];
+        logs: DurableLogLine[];
+    };
+};
+export {};

package/dist/utils/functions/durable-logs.js

@@ -0,0 +1,52 @@
+/**
+ * Records a durable log event
+ */
+export const createDurableJsonCollector = () => {
+    const steps = [];
+    const logLines = [];
+    const activeSteps = new Map();
+    function record(event) {
+        if (event.kind === 'log') {
+            const logLine = {
+                level: event.level,
+                message: event.message,
+            };
+            if (event.step === null) {
+                logLines.push(logLine);
+                return;
+            }
+            const step = activeSteps.get(event.step);
+            if (step) {
+                step.logs.push(logLine);
+                return;
+            }
+            logLines.push(logLine);
+            return;
+        }
+        if (event.phase === 'start') {
+            const step = {
+                ...event,
+                logs: [],
+            };
+            steps.push(step);
+            activeSteps.set(event.name, step);
+            return;
+        }
+        const step = activeSteps.get(event.name);
+        if (!step)
+            return;
+        step.phase = event.phase;
+        step.durationMs = event.durationMs;
+        if (event.phase === 'complete') {
+            step.output = event.output;
+        }
+        if (event.phase === 'error') {
+            step.error = event.error;
+        }
+        activeSteps.delete(event.name);
+    }
+    return {
+        record,
+        result: () => ({ steps, logs: logLines }),
+    };
+};

package/dist/utils/functions/invoke/local.js

@@ -47,7 +47,7 @@ export default async function invoke(resource, payload, context, options) {
     if (!resource.src) {
         throw new Error(`Function resource "${resource.name}" is missing the 'src' property.`);
     }
-    const { forceColor = true, timeout = 10, onNestedInvoke, depth = 0, callStack = [], onStepEvent = () => { }, } = options;
+    const { forceColor = true, timeout = 10, onNestedInvoke, depth = 0, callStack = [], onStepEvent = () => { }, noWait = false, } = options;
     // `payload.payload` is the event body for every function type: the document for
     // GROQ-based events, whatever the producer sent for the rest. The handler always
     // receives it as `event.data` (see the `payload` built in `start()` below).
@@ -306,6 +306,7 @@ export default async function invoke(resource, payload, context, options) {
                 srcPath: functionPath,
                 payload,
                 isDurable: resource.type === SANITY_FUNCTION_DURABLE,
+                noWait,
             };
             child.send(JSON.stringify(startMessage));
         }

package/dist/utils/types.d.ts

@@ -162,7 +162,9 @@ export interface InvokeExecutionOptions {
     /** Function names already on the invoke call stack (innermost last), used to detect cycles. @internal */
     callStack?: string[];
     /** Stream a durable step transition to the caller. @internal */
-    onStepEvent?: (event: DurableStepEvent) => void;
+    onStepEvent?: (event: DurableRuntimeEvent) => void;
+    /** Don't wait the full duration during a wait durable event @internal */
+    noWait?: boolean;
 }
 /**
  * Re-entrant callback that executes a named function from the blueprint on behalf
@@ -181,6 +183,7 @@ export type ParentToChildMessage = {
     srcPath: string;
     payload: unknown;
     isDurable?: boolean;
+    noWait?: boolean;
 } | {
     type: 'invoke-response';
     id: string;
@@ -195,7 +198,7 @@ export type ParentToChildMessage = {
     error: InvocationError;
 } | {
     type: 'step-event';
-    event: DurableStepEvent;
+    event: DurableRuntimeEvent;
 };
 /**
  * IPC messages sent from a function child process back up to the parent.
@@ -217,7 +220,7 @@ export type ChildToParentMessage = {
     error?: InvocationError;
 } | {
     type: 'step-event';
-    event: DurableStepEvent;
+    event: DurableRuntimeEvent;
 };
 /** @internal */
 export interface InvocationResponse {
@@ -301,7 +304,7 @@ export type Warning = {
     suggestions: string[];
 };
 /** @internal */
-export type DurableOperationSteps = 'run';
+export type DurableOperationSteps = 'run' | 'wait';
 /** @internal */
 export type DurableStepPhase = 'start' | 'complete' | 'error';
 /**
@@ -315,6 +318,15 @@ export interface DurableStepEvent {
     error?: InvocationError;
     durationMs?: number;
 }
+export interface DurableLogEvent {
+    kind: 'log';
+    phase: 'log';
+    step: string | null;
+    level: 'info' | 'warn' | 'error';
+    message: string;
+    timestamp?: string;
+}
+export type DurableRuntimeEvent = DurableStepEvent | DurableLogEvent;
 export interface FunctionTestFlags {
     data?: string;
     event?: string;
@@ -333,5 +345,7 @@ export interface FunctionTestFlags {
     'document-id-before'?: string;
     'document-id-after'?: string;
     'media-library-id'?: string;
+    'no-wait'?: boolean;
+    json?: boolean;
 }
 export {};

package/oclif.manifest.json

@@ -1,5 +1,156 @@
 {
   "commands": {
+    "init": {
+      "aliases": [],
+      "args": {
+        "directory": {
+          "description": "Directory to initialize. Interactive runs are asked for one instead.",
+          "name": "directory",
+          "required": false
+        }
+      },
+      "description": "Scaffolds a Blueprint, Studio, and starter function around a Sanity project.\n\nUse a project you already have, or create one with --create-project. A new project has no\ndatasets, so the Blueprint creates the dataset rather than attaching it.\n\nPass a directory to scaffold into it. Without one, an interactive run asks where the files go.\n\nThis hidden command is an experiment; its interface and generated files are not stable.",
+      "examples": [
+        "<%= config.bin %> <%= command.id %>",
+        "<%= config.bin %> <%= command.id %> ./my-workspace",
+        "<%= config.bin %> <%= command.id %> --yes",
+        "<%= config.bin %> <%= command.id %> --project-id <id> --dataset <name> --yes",
+        "<%= config.bin %> <%= command.id %> --create-project \"My Shop\" --yes"
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "path": {
+          "aliases": [
+            "blueprint-path"
+          ],
+          "char": "p",
+          "description": "Path to a Blueprint file or directory containing one",
+          "env": "SANITY_BLUEPRINT_PATH",
+          "hidden": true,
+          "name": "path",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "trace": {
+          "description": "Trace output",
+          "hidden": true,
+          "name": "trace",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "validate-resources": {
+          "description": "Validate resources",
+          "hidden": true,
+          "name": "validate-resources",
+          "allowNo": true,
+          "type": "boolean"
+        },
+        "verbose": {
+          "description": "Verbose output",
+          "hidden": true,
+          "name": "verbose",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "llms": {
+          "aliases": [
+            "skill"
+          ],
+          "description": "Show agent-oriented guidance for this command",
+          "hidden": true,
+          "name": "llms",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "yes": {
+          "char": "y",
+          "description": "Skip confirmation prompts",
+          "name": "yes",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "organization-id": {
+          "aliases": [
+            "organization",
+            "organizationId",
+            "org"
+          ],
+          "description": "Organization to use when the account has several",
+          "name": "organization-id",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "project-id": {
+          "aliases": [
+            "project",
+            "projectId"
+          ],
+          "description": "Project to use when the organization has several",
+          "name": "project-id",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "create-project": {
+          "aliases": [
+            "createProject",
+            "new-project"
+          ],
+          "description": "Create a project with this display name instead of using an existing one",
+          "exclusive": [
+            "project-id"
+          ],
+          "name": "create-project",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "dataset": {
+          "description": "Dataset to attach, or to create alongside a new project",
+          "name": "dataset",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "stack-name": {
+          "description": "Name for the new organization-scoped Stack, and the hosted Studio slug",
+          "name": "stack-name",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "studio-name": {
+          "description": "Blueprint-local name for the Studio resource and its directory",
+          "name": "studio-name",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hidden": true,
+      "hiddenAliases": [],
+      "id": "init",
+      "pluginAlias": "@sanity/runtime-cli",
+      "pluginName": "@sanity/runtime-cli",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Experimental blueprints-first project init",
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "init.js"
+      ]
+    },
     "blueprints:add": {
       "aliases": [],
       "args": {
@@ -2755,6 +2906,13 @@
           "hasDynamicHelp": false,
           "multiple": false,
           "type": "option"
+        },
+        "no-wait": {
+          "description": "Skip durable wait delays instead of sleeping",
+          "name": "no-wait",
+          "required": false,
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
@@ -3141,5 +3299,5 @@
       ]
     }
   },
-  "version": "17.8.0-next.g5972da4"
+  "version": "17.9.0-blueprinit.g14aaebd"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sanity/runtime-cli",
   "description": "Sanity's Runtime CLI for Blueprints and Functions",
-  "version": "17.8.0-next.g5972da4",
+  "version": "17.9.0-blueprinit.g14aaebd",
   "author": "Sanity Runtime Team",
   "type": "module",
   "license": "MIT",

package/skills/init.md

@@ -0,0 +1,199 @@
+# init
+
+Use `init` to scaffold a Blueprint around an existing Sanity project. The command is
+experimental, hidden from root help, and available from the `blueprinit` npm dist-tag.
+
+Use it for demos and evaluation, not as a stable project initializer. Its flags, generated files,
+and resource model may change.
+
+## Know what it does
+
+`init` uses an existing Sanity organization. It uses a project that exists, or creates one with
+`--create-project`. It writes local Blueprint files, then creates an empty organization-scoped
+Stack. The generated Blueprint attaches the project and declares resources for a later deployment.
+
+The dataset works one of two ways:
+
+- **Existing project:** the user picks one of its datasets, and the Blueprint attaches it.
+- **New project:** a new project has no datasets, so the Blueprint creates one. Its name comes from
+  `--dataset` and defaults to `production`. It does not exist until `blueprints deploy` runs.
+
+It does not create an organization. It does not deploy the attached resources, CORS origin, Studio,
+or Function. Those changes happen only if `blueprints deploy` is run later.
+
+## Inspect the target directory
+
+Pass the directory as an argument, or run the command from the directory that should contain the
+Blueprint. Without an argument an interactive run asks where the files go; an unattended run keeps
+the current directory.
+
+Before running:
+
+1. Check the working tree and existing files. Do not discard unrelated user changes.
+2. Look for a root `sanity.blueprint.*` file. If one exists, use the existing Blueprint instead of
+   initializing again.
+3. Look for a root `sanity.config.*` file. Its presence selects the Studio adoption flow.
+4. Confirm the user asked to initialize this directory. The command writes files and creates a
+   remote Stack.
+5. Confirm the user is signed in. If needed, have them run:
+
+```sh
+npx sanity login
+```
+
+The account must have at least one organization. A run against an existing project also needs one
+project in the selected organization and one dataset in that project. A run with `--create-project`
+needs neither.
+
+Interactive runs show the Blueprint resources, hosted Studio URL, local changes, and remote actions
+before the confirmation prompt. Everything the Blueprint declares stays pending until a later
+deployment.
+
+A run that creates a project makes two remote changes rather than one: the project, then the Stack.
+Both happen after the confirmation, so a cancelled run creates nothing. The project is created
+before any file is written, because the generated Studio config needs its ID.
+
+## Choose the flow
+
+- **Existing Blueprint with a configured Stack:** Exit without changes and use
+  `blueprints config --edit` or `blueprints doctor`.
+- **Existing Blueprint without a configured Stack:** Finish setup with `blueprints init`; it can
+  connect the existing manifest without rewriting it.
+- **Root Studio config:** Adopt the Studio in place. Read literal `projectId` and `dataset` strings
+  from `sanity.config.*`, falling back to `sanity.cli.*`. Do not move the Studio.
+- **Fresh workspace:** Create a Blueprint, an npm-workspace Studio, and a starter `set-slug`
+  document function.
+
+Do not rewrite a Studio config merely to make adoption work unless the user asks. Dynamic
+`projectId` or `dataset` values built from environment variables or imports cannot be detected.
+
+For an existing Blueprint, inspect it with:
+
+```sh
+npx @sanity/runtime-cli@blueprinit blueprints doctor
+```
+
+## Run unattended
+
+When the organization and project IDs are known, run this from the target directory:
+
+```sh
+npx @sanity/runtime-cli@blueprinit init --yes \
+  --organization-id <organization-id> \
+  --project-id <project-id> \
+  --dataset <dataset-name>
+```
+
+To create the project instead, replace `--project-id` with `--create-project`:
+
+```sh
+npx @sanity/runtime-cli@blueprinit init --yes \
+  --organization-id <organization-id> \
+  --create-project "<project display name>" \
+  --dataset <dataset-name>
+```
+
+`--create-project` and `--project-id` cannot both be passed. With `--create-project`, `--dataset`
+names a dataset to create and defaults to `production`.
+
+Replace all placeholders with real values. The project must belong to the organization, and the
+dataset must belong to the project. Do not guess any value.
+
+`--yes` skips confirmation. Without explicit values, an unattended run stops when the account has
+several organizations, projects, or datasets. Ask the user for the missing value or have them run
+the command interactively.
+
+Use `--stack-name <name>` and `--studio-name <name>` when those generated names need to be stable.
+The command normalizes both names to lowercase kebab case.
+
+The Stack name defaults to `<project>-<dataset>` and is also the hosted Studio slug, so it must be
+available across every Sanity organization. No API reports whether a slug is free, so a taken one
+fails during `blueprints deploy`.
+
+The Studio name is a Blueprint-local resource name and its directory under `studios/`. It defaults
+to `studio`. Every other generated name carries its resource type, so the defaults cannot collide.
+A dataset named `studio`, or `--studio-name production` against a `production` dataset, does
+collide; the command names the repeated value and writes nothing.
+
+When `SANITY_INTERNAL_ENV=staging`, the generated Studio URL and CORS origin use
+`https://<stack-name>.studio.sanity.work`. Other environments use
+`https://<stack-name>.sanity.studio`.
+
+For interactive organization, project, dataset, Stack-name, and confirmation prompts, have the
+user run:
+
+```sh
+npx @sanity/runtime-cli@blueprinit init
+```
+
+When the project has several datasets, the interactive command prompts for one and lists
+`production` first. Report the selected dataset from the command output.
+
+## Review the result
+
+A successful fresh run creates or updates:
+
+```text
+.
+├── .sanity/blueprint.config.json
+├── sanity.blueprint.ts
+├── package.json
+├── functions/
+│   └── set-slug/
+└── studios/
+    └── studio/
+```
+
+The command also creates or updates `.gitignore`. It preserves existing package metadata and adds
+the required npm workspaces and `@sanity/blueprints` dependency.
+
+The generated Studio matches `sanity init`: the same `sanity`, `@sanity/vision`, `react`,
+`react-dom`, `styled-components`, `@types/react`, and `typescript` versions, the same
+`tsconfig.json`, and `visionTool()` beside `structureTool()`. `sanity` and `@sanity/vision` are
+resolved from the registry at scaffold time, so no version is written into this repository.
+The Studio has no `deploy` script, because the Blueprint deploys it.
+
+An adopted Studio stays at the repository root. The command adds the Blueprint, Blueprint config,
+dependency, and `.gitignore` entry, but does not generate the starter Function.
+
+After the command exits:
+
+1. Confirm the output names the expected organization, project, and dataset.
+2. Confirm `.sanity/blueprint.config.json` exists. Its presence means Stack creation completed.
+3. Review `sanity.blueprint.ts`, including the Studio slug and credentialed CORS origin, plus
+   `package.json`, `.gitignore`, and the working-tree diff.
+4. Report the Stack ID and every created or modified path.
+
+Do not deploy as part of initialization unless the user separately asks for deployment. To continue
+after reviewing the scaffold, install dependencies and preview the deployment:
+
+```sh
+npm install
+npx @sanity/runtime-cli@blueprinit blueprints plan
+```
+
+Treat dependency installation and planning as separate follow-up actions when they were not part of
+the user's request.
+
+## Handle failures
+
+- **`No Sanity session found.`** Stop and ask the user to run `npx sanity login`. Authentication
+  fails before files are written.
+- **Multiple organizations or projects found.** Rerun with the matching `--organization-id` and
+  `--project-id`. Selection fails before files are written.
+- **No datasets found.** Ask the user to choose a project with a dataset, or to create a project
+  with `--create-project`, which makes the Blueprint create the dataset too.
+- **No projects found in an organization.** In an unattended run, pass `--create-project <name>`.
+- **Dataset name is not valid.** The projects API allows 2 to 64 characters from `a-z`, `0-9`, `-`,
+  and `_`, starting with a letter or a digit. Report the rule and ask for another name. Do not
+  rewrite the name the user gave.
+- **Could not create project.** Nothing was written. Report the API message. A quota error needs a
+  plan change or another organization.
+- **Could not read `projectId` and `dataset`.** The detected Studio config does not contain both
+  values as string literals. Pass explicit `--project-id` and `--dataset` values or report the config
+  file and let the user decide whether to change it.
+- **Refusing to overwrite an existing path.** Inspect the reported Studio or Function directory.
+  Do not delete or replace it without the user's direction.
+- **Stack quota or duplicate-name error.** Local scaffold files may already exist while
+  `.sanity/blueprint.config.json` does not. Resolve the Stack error, then run the recovery command
+  printed by `init`, which is `blueprints init`. It connects the existing manifest without rewriting it.