@sanity/runtime-cli 17.7.1-next.g09b9981 → 17.8.0-blueprinit.g0993fa5

package/dist/server/app.js

@@ -28,7 +28,7 @@ const app = (host, port, validateResources, executionOptions) => {
      */
     const nestedInvoke = async (name, payload, ctx, depth, callStack) => {
         const order = ++nestedOrder;
-        const result = await handleInvokeRequest(name, { data: payload }, { event: 'nested' }, ctx, validateResources, executionOptions, depth, callStack, nestedInvoke);
+        const result = await handleInvokeRequest(name, payload, { event: 'nested' }, ctx, validateResources, executionOptions, depth, callStack, nestedInvoke);
         broadcast({
             type: 'nested-invoke',
             name,
@@ -372,13 +372,13 @@ function parseInvokeRequest(body, blueprintFileDir) {
     }
     const metadataEvent = metadata.event;
     if (typeof metadataEvent !== 'string' ||
-        (!isEventType(metadataEvent) && metadataEvent !== 'scheduled')) {
+        (!isEventType(metadataEvent) && metadataEvent !== 'plain')) {
         throw new Error('Request body is not valid, `metadata.event` field is not one of `create`, `update`, `delete`, or `scheduled`');
     }
     let before = null;
     let after = null;
     // Only GROQ-based events (create, update, delete) have before and after fields
-    if (metadataEvent !== 'scheduled') {
+    if (metadataEvent !== 'plain') {
         if (!('before' in metadata)) {
             throw new Error('Request body is not valid, `metadata.before` field is missing');
         }
@@ -418,9 +418,7 @@ function parseInvokeRequest(body, blueprintFileDir) {
             },
             event,
         },
-        metadata: metadataEvent === 'scheduled'
-            ? { event: metadataEvent }
-            : { event: metadataEvent, before, after },
+        metadata: metadataEvent === 'plain' ? { event: metadataEvent } : { event: metadataEvent, before, after },
     };
 }
 export { app, buildApiUrl, parseDocumentUrl };

package/dist/server/static/components/payload-panel.js

@@ -127,7 +127,7 @@ class PayloadPanel extends ApiBaseElement {
     // for certain other specific function types, set the payload to something specific, or reload whatever was loaded into its document payload before
     switch (selectedFunction.type) {
       case this.SANITY_FUNCTION_SYNC_TAG_INVALIDATE:
-        this.#updateCodeView(this.api.store.payload, {data: {syncTags: ['s1:1234', 's2:5678']}})
+        this.#updateCodeView(this.api.store.payload, {syncTags: ['s1:1234', 's2:5678']})
         break
       default:
         this.#updateCodeView(this.api.store.payload, this.documentCacheByFunction[selectedIndex])

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

@@ -0,0 +1,6 @@
+/** A left-to-right reveal of the wordmark; the last frame is the finished line. */
+export declare function introFrames(): string[];
+/** Print the intro, animated when the terminal can show it and static when it cannot. */
+export declare function playIntro({ json }?: {
+    json?: boolean;
+}): Promise<void>;

package/dist/utils/display/intro.js

@@ -0,0 +1,63 @@
+import { env, stdout } from 'node:process';
+import { onExit } from 'signal-exit';
+import { isInteractive } from '../interactive.js';
+import { styleText } from '../style-text.js';
+const INDENT = '  ';
+const WORDMARK = 'sanity';
+const TAIL = ' with blueprints';
+/** The leading edge of the reveal, densest first. */
+const GRADIENT = ['▓', '▒', '░'];
+const REVEAL_PER_FRAME = 1;
+const FRAME_MS = 45;
+/** Time the finished wordmark holds before the command's own output follows. */
+const HOLD_MS = 250;
+const HIDE_CURSOR = '\x1b[?25l';
+const SHOW_CURSOR = '\x1b[?25h';
+const CLEAR_LINE = '\x1b[2K';
+function style(revealed, edge) {
+    const wordmark = revealed.slice(0, WORDMARK.length);
+    const tail = revealed.slice(WORDMARK.length);
+    return INDENT + styleText(['bold', 'red'], wordmark) + styleText('dim', tail + edge);
+}
+/** A left-to-right reveal of the wordmark; the last frame is the finished line. */
+export function introFrames() {
+    const full = WORDMARK + TAIL;
+    const frames = [];
+    for (let revealed = REVEAL_PER_FRAME; revealed < full.length; revealed += REVEAL_PER_FRAME) {
+        const edge = GRADIENT.slice(0, Math.min(GRADIENT.length, full.length - revealed)).join('');
+        frames.push(style(full.slice(0, revealed), edge));
+    }
+    frames.push(style(full, ''));
+    return frames;
+}
+function animates() {
+    return isInteractive && env.TERM !== 'dumb' && !env.CI;
+}
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** Print the intro, animated when the terminal can show it and static when it cannot. */
+export async function playIntro({ json = false } = {}) {
+    if (json)
+        return;
+    const frames = introFrames();
+    const finished = frames.at(-1) ?? '';
+    if (!animates()) {
+        stdout.write(`\n${finished}\n\n`);
+        return;
+    }
+    stdout.write(`\n${HIDE_CURSOR}`);
+    const cancelExitHook = onExit(() => {
+        stdout.write(SHOW_CURSOR);
+    });
+    try {
+        for (const frame of frames) {
+            stdout.write(`\r${CLEAR_LINE}${frame}`);
+            await sleep(FRAME_MS);
+        }
+        await sleep(HOLD_MS);
+        stdout.write('\n\n');
+    }
+    finally {
+        stdout.write(SHOW_CURSOR);
+        cancelExitHook();
+    }
+}

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

@@ -24,10 +24,13 @@ export declare function promptForOrganization({ token, knownOrganizationId, logg
 /**
  * Asks the user whether to scope a Blueprint to an organization or a project.
  */
-export declare function promptForScope({ allowBack, hasProjects, }?: {
+export declare function promptForScope({ allowBack, hasProjects, message, }?: {
     allowBack?: boolean;
     hasProjects?: boolean;
+    message?: string;
 }): Promise<ScopeType | Back>;
+/** Offers a recovery path after the selected scope cannot be read. */
+export declare function promptForScopeRecovery(): Promise<'exit' | 'retry'>;
 /**
  * Prompts the user to pick a project from a pre-fetched list of projects.
  * Use after promptForOrganization when the user chose project scope.

package/dist/utils/display/prompt.js

@@ -121,7 +121,7 @@ export async function promptForOrganization({ token, knownOrganizationId, logger
 /**
  * Asks the user whether to scope a Blueprint to an organization or a project.
  */
-export async function promptForScope({ allowBack = false, hasProjects = true, } = {}) {
+export async function promptForScope({ allowBack = false, hasProjects = true, message = 'How would you like to scope your Blueprint?', } = {}) {
     const choices = [
         {
             name: 'Organization',
@@ -136,12 +136,26 @@ export async function promptForScope({ allowBack = false, hasProjects = true, }
         },
     ];
     const answer = await select({
-        message: 'How would you like to scope your Blueprint?',
+        message,
         choices: withBackChoice(choices, allowBack),
         default: 'organization',
     });
     return answer;
 }
+/** Offers a recovery path after the selected scope cannot be read. */
+export async function promptForScopeRecovery() {
+    return await select({
+        message: 'What would you like to do?',
+        choices: [
+            {
+                name: 'Choose another organization or project',
+                value: 'retry',
+            },
+            { name: 'Exit', value: 'exit' },
+        ],
+        default: 'retry',
+    });
+}
 /**
  * Prompts the user to pick a project from a pre-fetched list of projects.
  * Use after promptForOrganization when the user chose project scope.

package/dist/utils/external/npmjs.d.ts

@@ -1,2 +1,9 @@
 import type { Logger } from '../logger.js';
 export declare function getLatestNpmVersion(pkg: string, logger: Logger): Promise<string>;
+/**
+ * The latest version as a caret range, the form `sanity init` writes.
+ *
+ * `getLatestNpmVersion` answers `latest` when the registry cannot be read, and `^latest`
+ * is not a range, so that answer passes through unchanged.
+ */
+export declare function getLatestNpmRange(pkg: string, logger: Logger): Promise<string>;

package/dist/utils/external/npmjs.js

@@ -16,3 +16,13 @@ export async function getLatestNpmVersion(pkg, logger) {
         return 'latest';
     }
 }
+/**
+ * The latest version as a caret range, the form `sanity init` writes.
+ *
+ * `getLatestNpmVersion` answers `latest` when the registry cannot be read, and `^latest`
+ * is not a range, so that answer passes through unchanged.
+ */
+export async function getLatestNpmRange(pkg, logger) {
+    const version = await getLatestNpmVersion(pkg, logger);
+    return version === 'latest' ? version : `^${version}`;
+}

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

@@ -3,6 +3,7 @@ import {isAbsolute, join} from 'node:path'
 import process from 'node:process'
 import {pathToFileURL} from 'node:url'
 import {installConsole} from './child-runtime/console.js'
+import {runDurable} from './child-runtime/durable.js'
 import {createInvoker} from './child-runtime/invoke.js'
 import {createResourcesApi} from './child-runtime/resources.js'
 
@@ -40,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} = jsonData
+  const {srcPath, payload, isDurable} = jsonData
   const {context, ...event} = payload
 
   let logs = ''
@@ -78,11 +79,22 @@ process.on('message', async (data) => {
 
     // Allow the handler to invoke other blueprint functions by name.
     context.invoke = invoker.invoke
-    json = await handler({
-      context,
-      event,
-      done: async () => new Response(null, {status: 204}),
-    })
+
+    if (isDurable) {
+      json = await runDurable(
+        handler,
+        {context, event, logger: console},
+        {
+          emit: (e) => process.send(JSON.stringify({type: 'step-event', event: e})),
+        },
+      )
+    } else {
+      json = await handler({
+        context,
+        event,
+        done: async () => new Response(null, {status: 204}),
+      })
+    }
 
     // Restore streams
     process.stdout.write = originalStdoutWrite

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

@@ -0,0 +1,18 @@
+import type {DurableContext, DurableHandler, DurableLogger, GenericEvent} from '@sanity/functions'
+import type {DurableStepEvent} from '../../types.js'
+
+type RunDurableArgs = {
+  context: DurableContext
+  event: GenericEvent
+  logger: DurableLogger
+}
+
+type DurableIO = {
+  emit: (event: DurableStepEvent) => void
+}
+
+export function runDurable(
+  handler: DurableHandler,
+  args: RunDurableArgs,
+  io: DurableIO,
+): Promise<unknown>

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

@@ -0,0 +1,46 @@
+import {performance} from 'node:perf_hooks'
+
+/**
+ * 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) {
+  const track = async (name, kind, produce) => {
+    io.emit({name, kind, phase: 'start'})
+    const startedAt = performance.now()
+    try {
+      const value = await produce()
+      io.emit({
+        name,
+        kind,
+        phase: 'complete',
+        output: value,
+        durationMs: performance.now() - startedAt,
+      })
+      return value
+    } catch (err) {
+      io.emit({
+        name,
+        kind,
+        phase: 'error',
+        error: {
+          name: err?.name ?? 'Error',
+          message: err?.message ?? String(err),
+          stack: err?.stack ?? '',
+        },
+        durationMs: performance.now() - startedAt,
+      })
+      throw err
+    }
+  }
+
+  const step = {
+    run: ({name, handler: fn}) => track(name || 'step-run', 'run', () => fn({logger, attempt: 1})),
+  }
+
+  return handler({context, event, step, logger})
+}

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

@@ -5,9 +5,11 @@ import { setTimeout } from 'node:timers';
 import { fileURLToPath } from 'node:url';
 import * as groq from 'groq-js';
 import config from '../../../config.js';
+import { SANITY_FUNCTION_DURABLE } from '../../../constants.js';
 import { groupBlueprintResources } from '../../blueprints/group-resources.js';
 import { isGroqContextOptions, } from '../../types.js';
 import { acquireFunctionBuild } from './prepare.js';
+import { isGroqInvocation } from './resolve-invoke-type.js';
 function getChildProcessWrapperPath() {
     return fileURLToPath(new URL('../child-process-wrapper.js', import.meta.url));
 }
@@ -16,13 +18,16 @@ export function sanitizeLogs(logs) {
 }
 export async function applyGroqRule(resource, payload, projectId, dataset) {
     const { before, after, payload: data = null } = payload;
+    const event = resource.event;
     // If there is no rule set return everything
-    if (!resource.event)
+    if (!event)
         return data;
     // default groq rule is: gimme full doc content. otherwise, parse + eval custom rule
     // applying the GROQ filter may result in a slimmer set of documents
-    if (resource.event.filter || resource.event.projection) {
-        const query = `*[${resource.event.filter || ''}]${resource.event.projection || ''}`;
+    const filter = 'filter' in event ? event.filter : undefined;
+    const projection = 'projection' in event ? event.projection : undefined;
+    if (filter || projection) {
+        const query = `*[${filter || ''}]${projection || ''}`;
         try {
             const rule = groq.parse(query, { mode: 'delta' });
             const sanity = projectId && dataset ? { projectId, dataset } : undefined;
@@ -42,21 +47,24 @@ 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 = [] } = options;
+    const { forceColor = true, timeout = 10, onNestedInvoke, depth = 0, callStack = [], onStepEvent = () => { }, } = 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).
+    let filteredData = payload?.payload || {};
     // Apply the GROQ rule before preparing a build so a filtered-out event skips
     // the (potentially expensive) transpile entirely.
-    let filteredData = payload?.payload?.data || {};
-    if (resource.type === 'sanity.function.document' ||
-        resource.type === 'sanity.function.media-library.asset') {
+    if (isGroqInvocation(resource)) {
         if (!isGroqContextOptions(context)) {
             throw new Error('GROQ-based functions require a context with clientOptions');
         }
         const { projectId, dataset } = context.clientOptions;
         if ('before' in payload) {
             filteredData = await applyGroqRule(resource, payload, projectId, dataset);
+            const filter = resource.event && 'filter' in resource.event ? resource.event.filter : '';
             if (typeof filteredData === 'undefined') {
                 return {
-                    logs: `⚠️ Filter "${resource.event?.filter}" returned an empty result. Skipping invoke.`,
+                    logs: `⚠️ Filter "${filter}" returned an empty result. Skipping invoke.`,
                     error: undefined,
                     json: undefined,
                 };
@@ -208,6 +216,10 @@ export default async function invoke(resource, payload, context, options) {
                 catch {
                     return;
                 }
+                if (msg?.type === 'step-event') {
+                    onStepEvent(msg.event);
+                    return;
+                }
                 // Nested invoke request — handle without tearing down the child.
                 if (msg?.type === 'invoke-request') {
                     handleNestedInvoke({ id: msg.id, name: msg.name, payload: msg.payload });
@@ -289,7 +301,12 @@ export default async function invoke(resource, payload, context, options) {
                     }),
                 },
             };
-            const startMessage = { type: 'start', srcPath: functionPath, payload };
+            const startMessage = {
+                type: 'start',
+                srcPath: functionPath,
+                payload,
+                isDurable: resource.type === SANITY_FUNCTION_DURABLE,
+            };
             child.send(JSON.stringify(startMessage));
         }
         function shutdown() {

package/dist/utils/functions/invoke/resolve-invoke-type.d.ts

@@ -0,0 +1,51 @@
+import type { BlueprintResource } from '@sanity/blueprints';
+import type { Logger } from '../../logger.js';
+import type { EventType, FunctionGroqResource, FunctionResource, FunctionTestFlags, InvokeContextOptions, InvokePayloadOptions } from '../../types.js';
+import buildPayload from '../build-payload.js';
+import { fetchAsset, fetchDocument } from '../fetch-document.js';
+export type InvocationPlan = {
+    kind: 'groq';
+    inputSource: 'document' | 'media';
+    isDurable: boolean;
+} | {
+    kind: 'plain';
+    isDurable: false;
+} | {
+    kind: 'durable';
+    inputSource: 'payload';
+    isDurable: true;
+};
+export type InputContext = {
+    flags: FunctionTestFlags;
+    projectId?: string;
+    organizationId?: string;
+    api?: string;
+    apiHost: string;
+    token?: string;
+    withUserToken?: boolean;
+    resources: BlueprintResource[];
+    blueprintFileDir: string;
+    log: Logger;
+};
+type InvocationDeps = {
+    fetchDocument: typeof fetchDocument;
+    fetchAsset: typeof fetchAsset;
+    buildPayload: typeof buildPayload;
+};
+export declare const defaultInvocationDeps: InvocationDeps;
+export interface InvokeInput {
+    payload: Record<string, unknown>;
+    before: Record<string, unknown> | null;
+    after: Record<string, unknown> | null;
+}
+export declare const resolveInvocationPlan: (resource: FunctionResource) => InvocationPlan;
+/**
+ * True when the function's event is delivered through a GROQ rule (a document or
+ * media-library event, whether plain or durable), so its payload is a document the
+ * rule may narrow before the handler sees it.
+ */
+export declare const isGroqInvocation: (resource: FunctionResource) => resource is FunctionGroqResource;
+export declare const collectInvokeInput: (plan: InvocationPlan, input: InputContext, deps: InvocationDeps) => Promise<InvokeInput>;
+export declare const buildContext: (plan: InvocationPlan, input: InputContext) => InvokeContextOptions;
+export declare const buildInvokeOptions: (plan: InvocationPlan, invokeInput: InvokeInput, eventType: EventType) => InvokePayloadOptions;
+export {};

package/dist/utils/functions/invoke/resolve-invoke-type.js

@@ -0,0 +1,131 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { cwd } from 'node:process';
+import { SANITY_FUNCTION_DOCUMENT, SANITY_FUNCTION_DURABLE, SANITY_FUNCTION_MEDIA_LIBRARY_ASSET, SANITY_FUNCTION_PUBSUB, SANITY_FUNCTION_SCHEDULED, SANITY_FUNCTION_SYNC_TAG_INVALIDATE, } from '../../../constants.js';
+import { parseJsonObject } from '../../parse-json-object.js';
+import buildPayload from '../build-payload.js';
+import { fetchAsset, fetchDocument } from '../fetch-document.js';
+export const defaultInvocationDeps = { fetchDocument, fetchAsset, buildPayload };
+const assertNever = (resource) => {
+    throw new Error(`No invocation plan for function type: ${resource.type}`);
+};
+const resolveDurableInvocationPlan = (event) => {
+    switch (event?.type) {
+        case 'document':
+            return { kind: 'groq', inputSource: 'document', isDurable: true };
+        case 'media-library':
+            return { kind: 'groq', inputSource: 'media', isDurable: true };
+        case 'sync-tag-invalidate':
+        case undefined:
+            return { kind: 'durable', inputSource: 'payload', isDurable: true };
+    }
+};
+export const resolveInvocationPlan = (resource) => {
+    switch (resource.type) {
+        case SANITY_FUNCTION_DOCUMENT:
+            return { kind: 'groq', inputSource: 'document', isDurable: false };
+        case SANITY_FUNCTION_MEDIA_LIBRARY_ASSET:
+            return { kind: 'groq', inputSource: 'media', isDurable: false };
+        case SANITY_FUNCTION_DURABLE:
+            return resolveDurableInvocationPlan(resource.event);
+        case SANITY_FUNCTION_SCHEDULED:
+        case SANITY_FUNCTION_PUBSUB:
+        case SANITY_FUNCTION_SYNC_TAG_INVALIDATE:
+            return { kind: 'plain', isDurable: false };
+        default:
+            return assertNever(resource);
+    }
+};
+/**
+ * True when the function's event is delivered through a GROQ rule (a document or
+ * media-library event, whether plain or durable), so its payload is a document the
+ * rule may narrow before the handler sees it.
+ */
+export const isGroqInvocation = (resource) => resolveInvocationPlan(resource).kind === 'groq';
+export const collectInvokeInput = async (plan, input, deps) => {
+    const source = plan.kind === 'groq' ? plan.inputSource : 'none';
+    return resolveInvokeInput(source, input, deps);
+};
+export const buildContext = (plan, input) => {
+    const withToken = input.withUserToken ? { token: input.token } : {};
+    if (plan.kind === 'plain') {
+        return {
+            clientOptions: { ...withToken },
+            resources: input.resources,
+            blueprintFileDir: input.blueprintFileDir,
+        };
+    }
+    const isMedia = plan.kind === 'groq' && plan.inputSource === 'media';
+    return {
+        clientOptions: {
+            apiVersion: input.api,
+            dataset: input.flags.dataset,
+            projectId: input.projectId,
+            organizationId: input.organizationId,
+            ...withToken,
+        },
+        eventResourceType: isMedia ? 'media-library' : 'dataset',
+        eventResourceId: (isMedia ? input.flags['media-library-id'] : `${input.projectId}.${input.flags.dataset}`) ||
+            '',
+        functionResourceType: 'project',
+        functionResourceId: input.projectId || '',
+        resources: input.resources,
+        blueprintFileDir: input.blueprintFileDir,
+    };
+};
+export const buildInvokeOptions = (plan, invokeInput, eventType) => {
+    switch (plan.kind) {
+        case 'groq':
+            return {
+                event: eventType,
+                payload: invokeInput.payload,
+                before: invokeInput.before,
+                after: invokeInput.after,
+            };
+        case 'plain':
+            // Cron functions have no payload, but pubsub and sync-tag-invalidate carry
+            // whatever the producer sent, so pass it through for all of them.
+            return { event: 'plain', payload: invokeInput.payload };
+        case 'durable':
+            return { event: 'durable', payload: invokeInput.payload };
+    }
+};
+const resolveInvokeInput = async (source, input, deps) => {
+    const { flags } = input;
+    const fetchById = (id) => source === 'document'
+        ? deps.fetchDocument(id, {
+            projectId: input.projectId,
+            dataset: flags.dataset,
+            apiVersion: input.api,
+            apiHost: input.apiHost,
+            token: input.token,
+        }, input.log)
+        : deps.fetchAsset(id, {
+            mediaLibraryId: flags['media-library-id'],
+            apiVersion: input.api,
+            apiHost: input.apiHost,
+            token: input.token,
+        }, input.log);
+    let before = null;
+    let after = null;
+    if (flags['data-before'] && flags['data-after']) {
+        before = parseJsonObject(flags['data-before']);
+        after = parseJsonObject(flags['data-after']);
+    }
+    else if (flags['file-before'] && flags['file-after']) {
+        before = parseJsonObject(readFileSync(join(cwd(), flags['file-before']), 'utf8'));
+        after = parseJsonObject(readFileSync(join(cwd(), flags['file-after']), 'utf8'));
+    }
+    else if (flags['document-id-before'] && flags['document-id-after']) {
+        before = await fetchById(flags['document-id-before']);
+        after = await fetchById(flags['document-id-after']);
+    }
+    let payload;
+    if (after)
+        payload = after;
+    else if (flags['document-id'])
+        payload = await fetchById(flags['document-id']);
+    else
+        payload = deps.buildPayload({ data: flags.data, file: flags.file });
+    return { payload, before, after };
+};

package/dist/utils/progress.js

@@ -2,6 +2,9 @@ import { stderr } from 'node:process';
 import { onExit } from 'signal-exit';
 const ST = '\x1b\\';
 export const HEARTBEAT_INTERVAL_MS = 5_000;
+// Ora clobbers stderr.write and messes with OSC output.
+// Keep the original writer so progress sequences do not collide.
+const writeToStderr = stderr.write.bind(stderr);
 const STATES = {
     clear: 0,
     normal: 1,
@@ -24,7 +27,7 @@ function startHeartbeat(sequence) {
         return;
     heartbeat = setInterval(() => {
         if (stderr.isTTY && heartbeatSequence)
-            stderr.write(heartbeatSequence);
+            writeToStderr(heartbeatSequence);
     }, HEARTBEAT_INTERVAL_MS);
     heartbeat.unref();
 }
@@ -37,7 +40,7 @@ function write(state, value = 0) {
         exitHookRegistered = true;
         function clear() {
             stopHeartbeat();
-            stderr.write(`\x1b]9;4;0;0${ST}`);
+            writeToStderr(`\x1b]9;4;0;0${ST}`);
         }
         // arc/utils SIGINT handler clobbers our signal-exit; luckily it then calls process.exit()
         process.once('exit', clear); // triggered by arc/utils SIGINT handler
@@ -47,7 +50,7 @@ function write(state, value = 0) {
     const active = state === 'normal' || state === 'paused' || state === 'busy';
     if (!active)
         stopHeartbeat();
-    stderr.write(sequence);
+    writeToStderr(sequence);
     if (active)
         startHeartbeat(sequence);
 }