@uipath/maestro-builder-sdk 6.16.14 → 6.17.0

package/dist/bindings-v2.d.ts

@@ -2,7 +2,7 @@
 export interface BindingsV2Resource {
     resource: string;
     key: string;
-    id: string;
+    id?: string;
     value: Record<string, unknown>;
     metadata: Record<string, unknown>;
     [k: string]: unknown;
@@ -61,3 +61,41 @@ export declare function connectionResources(flow: unknown): BindingsV2Resource[]
 export declare function mergeBindingsV2(existing: unknown, connections: BindingsV2Resource[]): BindingsV2Document;
 /** Read a `bindings_v2.json`, or `undefined` when absent or unparseable. */
 export declare function readBindingsV2(path: string): BindingsV2Document | undefined;
+/** The files of one inline agent, as `uip agent refresh` reads them. */
+export interface InlineAgentFiles {
+    /** `<agent>/agent.json`. */
+    agent: unknown;
+    /** Every `<agent>/resources/<id>/resource.json` that has a `$resourceType`. */
+    resources: unknown[];
+    /** Every `<agent>/features/<id>/feature.json` that has a `$featureType`. */
+    features: unknown[];
+}
+/**
+ * The `bindings_v2.json` rows one inline agent declares — what `uip agent
+ * refresh --inline-in-flow` generates for it, and what `uip agent validate
+ * --inline-in-flow` requires to be on disk (`AgentValidationDrift`,
+ * flow-builder-sdk#962).
+ *
+ * A transcription of the agent tool's own generator, `generateBindings` in
+ * `@uipath/tool-agent/agent-bindings` (Studio.Common `packager/src/bindings/`;
+ * read from 2.0.0, the version uipath-cli's agent-tool locks, and identical in the
+ * bundle of uip 1.205.0-dev.9071). It is a COPY, so
+ * `tests/agent-bindings-contract.test.ts` runs the real generator over the
+ * resources compile writes and fails on any row that differs.
+ *
+ * Inputs are read the way refresh reads them: every resource file, then any
+ * resource in `agent.json` whose name no file already has; the same for features.
+ * Rows are deduplicated on `resource` + `key`, first one wins.
+ */
+export declare function inlineAgentResources(files: InlineAgentFiles): BindingsV2Resource[];
+/**
+ * Fold one inline agent's rows into the project's rows, the way `uip agent
+ * refresh --inline-in-flow` does (`mergeInlineFlowBindings`): drop the rows that
+ * exactly match a fresh one (this agent's own earlier output), then keep the
+ * FIRST row per identity with the existing rows first — so a row the flow
+ * already declares wins over the agent's copy of it — and spell every
+ * connection row's `resource` as `connection`.
+ */
+export declare function mergeInlineAgentResources(existing: BindingsV2Resource[], fresh: BindingsV2Resource[]): BindingsV2Resource[];
+/** Read one inline agent's directory the way refresh does; `undefined` when it has no readable `agent.json`. */
+export declare function readInlineAgentFiles(agentDir: string): InlineAgentFiles | undefined;

package/dist/bindings-v2.js

@@ -32,16 +32,29 @@
  *
  * ## What this derives, and what it deliberately leaves alone
  *
- * Only `connection` resources, which is what refresh imports and what #689 is
- * about. Pack derives more from the BPMN projection — a `core.trigger.scheduled`
- * flow also yields a `TimeTrigger` resource whose `CronExpression` comes from
- * translating the trigger's ISO-8601 `timerPreset`. Re-deriving those here would
- * be a second implementation of someone else's generator, free to drift, for no
- * gain in the package. So non-connection resources already in the file are
- * PRESERVED untouched and never invented: {@link mergeBindingsV2} replaces only
- * the connection rows.
+ * Two kinds of row, each copied from the generator that owns it:
+ *
+ *   - `connection` rows for the flow's own connector steps — what pack derives,
+ *     and what #689 is about ({@link connectionResources}).
+ *   - every inline agent's rows (`process`, `index`, `app`, `connection`, …) —
+ *     what `uip agent refresh --inline-in-flow` derives from the agent's
+ *     directory with the agent tool's `generateBindings`
+ *     ({@link inlineAgentResources}). `uip agent validate --inline-in-flow`
+ *     regenerates them and fails with `AgentValidationDrift` when one is
+ *     missing, and the SDK route never runs refresh, so compile writes them
+ *     (flow-builder-sdk#962). `tests/agent-bindings-contract.test.ts` runs the
+ *     real generator against this copy.
+ *
+ * Pack derives more from the BPMN projection — a `core.trigger.scheduled` flow
+ * also yields a `TimeTrigger` resource whose `CronExpression` comes from
+ * translating the trigger's ISO-8601 `timerPreset`. Nothing in the SDK route
+ * checks those against the project file, and pack regenerates them in the
+ * package, so they are not copied here: other rows already in the file are
+ * PRESERVED untouched and never invented ({@link mergeBindingsV2},
+ * {@link mergeInlineAgentResources}).
  */
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { BindingRefusal, connectionConnectorConflictMessage } from './core/binding-messages.js';
 /** The document version pack emits. */
 const DOCUMENT_VERSION = '2.0';
@@ -257,3 +270,270 @@ export function readBindingsV2(path) {
         return undefined;
     }
 }
+// ─────────────────────────────────────────────────────────────────────────────
+// Inline-agent rows — the ones `uip agent refresh --inline-in-flow` derives
+// ─────────────────────────────────────────────────────────────────────────────
+/** The folder sentinel the agent tool treats the same as an empty folder. */
+const SOLUTION_FOLDER = 'solution_folder';
+/** Escalation recipient types that name an asset (`assetName` + `folderPath`). */
+const ASSET_RECIPIENT_TYPES = new Set([4, 6]);
+/** An escalation of this `escalationType` stores to a bucket, not an Action Center app. */
+const VS_ESCALATION_TYPE = 1;
+/** Tool `type` → the `subType` of the `process` row it declares. */
+const PROCESS_TOOL_SUBTYPES = {
+    process: 'process',
+    agent: 'agent',
+    api: 'api',
+    processOrchestration: 'processOrchestration',
+    flow: 'flow',
+    function: 'function',
+};
+function bindingValue(defaultValue, displayName) {
+    return { defaultValue, isExpression: false, displayName };
+}
+function agentRowMetadata() {
+    return { bindingsVersion: BINDINGS_VERSION, solutionsSupport: 'true' };
+}
+/** Adds `folderPath` unless the folder is empty or `solution_folder` — both mean "the solution's own folder". */
+function withFolderPath(value, raw) {
+    if (raw && raw !== SOLUTION_FOLDER)
+        value.folderPath = bindingValue(raw, 'Folder path');
+    return value;
+}
+/** A row whose value is one `name` (plus the folder) and whose metadata is the default pair. */
+function namedRow(resource, name, displayName, folder) {
+    return {
+        resource,
+        key: name,
+        value: withFolderPath({ name: bindingValue(name, displayName) }, folder),
+        metadata: agentRowMetadata(),
+    };
+}
+function processRow(name, subType, folder) {
+    return {
+        resource: 'process',
+        key: name,
+        value: withFolderPath({ name: bindingValue(name, 'Process name') }, folder),
+        metadata: { subType, ...agentRowMetadata() },
+    };
+}
+function agentConnectionRow(id, connector, displayName) {
+    return {
+        resource: 'connection',
+        key: id,
+        value: { connectionId: bindingValue(id, displayName) },
+        metadata: { connector, useConnectionService: 'true', ...agentRowMetadata() },
+    };
+}
+function toolRows(tool) {
+    const props = isRecord(tool.properties) ? tool.properties : {};
+    const rows = [];
+    const subType = typeof tool.type === 'string' && Object.hasOwn(PROCESS_TOOL_SUBTYPES, tool.type)
+        ? PROCESS_TOOL_SUBTYPES[tool.type]
+        : undefined;
+    if (subType !== undefined) {
+        rows.push(processRow(props.processName, subType, props.folderPath));
+    }
+    else if (tool.type === 'integration') {
+        rows.push(agentConnectionRow(props.connection?.id, props.connection?.connector?.key, 'Connection ID'));
+    }
+    else if (tool.type === 'ixp') {
+        rows.push({
+            resource: 'ixp',
+            key: props.projectName,
+            value: {
+                name: bindingValue(props.projectName, 'IXP project name'),
+                version: bindingValue(props.versionTag, 'IXP project version'),
+            },
+            // The generator leaves `solutionsSupport` off an IXP row on purpose.
+            metadata: { bindingsVersion: BINDINGS_VERSION },
+        });
+    }
+    else if (tool.type === 'internal' && props.toolType === 'deep-rag') {
+        // A DeepRAG built-in grounds on an index; every other `internal` tool, and
+        // every unknown type, declares nothing.
+        const indexName = isRecord(props.settings) ? props.settings.indexName : undefined;
+        if (typeof indexName === 'string' && indexName.length > 0)
+            rows.push(namedRow('index', indexName, 'Index Name'));
+    }
+    for (const policy of Array.isArray(tool.guardrail?.policies) ? tool.guardrail.policies : []) {
+        if (policy?.action?.$actionType === 'escalate' && policy.action.app?.name) {
+            rows.push(namedRow('app', policy.action.app.name, 'App name', policy.action.app.folderName));
+        }
+    }
+    return rows;
+}
+function assetRecipientRows(recipients) {
+    const rows = [];
+    for (const r of Array.isArray(recipients) ? recipients : []) {
+        if (isRecord(r) && ASSET_RECIPIENT_TYPES.has(r.type) && r.assetName) {
+            rows.push(namedRow('asset', r.assetName, 'Asset Name', r.folderPath));
+        }
+    }
+    return rows;
+}
+function resourceRows(resource) {
+    switch (resource.$resourceType) {
+        case 'tool':
+            return toolRows(resource);
+        case 'context':
+            if (resource.contextType === 'datafabricentityset') {
+                return (Array.isArray(resource.entitySet) ? resource.entitySet : []).map((entity) => ({
+                    resource: 'entity',
+                    key: entity.referenceKey ?? entity.id,
+                    value: withFolderPath({ name: bindingValue(entity.name, 'Entity name') }, entity.folderId),
+                    metadata: { ...agentRowMetadata(), scope: 'folder' },
+                }));
+            }
+            return [namedRow('index', resource.indexName, 'Index Name', resource.folderPath)];
+        case 'escalation': {
+            if (resource.escalationType === VS_ESCALATION_TYPE) {
+                const bucket = resource.vsEscalationProperties?.storageBucketName;
+                return bucket
+                    ? [namedRow('bucket', bucket, 'Storage Bucket Name', resource.vsEscalationProperties?.storageBucketFolderPath)]
+                    : [];
+            }
+            const rows = [];
+            for (const channel of Array.isArray(resource.channels) ? resource.channels : []) {
+                if (channel?.type === 'actionCenter' && channel.properties?.appName) {
+                    rows.push(namedRow('app', channel.properties.appName, 'App name', channel.properties.folderName));
+                }
+                rows.push(...assetRecipientRows(channel?.recipients));
+            }
+            return rows;
+        }
+        case 'mcp':
+            return [namedRow('mcpServer', resource.slug, 'Slug', resource.folderPath)];
+        case 'a2a':
+            return [namedRow('remoteA2aAgent', resource.slug, 'Slug', resource.folderPath)];
+        default:
+            return [];
+    }
+}
+function agentDefinitionRows(agent) {
+    if (agent.type !== 'lowCode')
+        return [];
+    const rows = [];
+    const byom = agent.settings?.byomProperties;
+    if (byom)
+        rows.push(agentConnectionRow(byom.connectionId, byom.connectorKey, 'Model connection ID'));
+    for (const guardrail of Array.isArray(agent.guardrails) ? agent.guardrails : []) {
+        if (guardrail?.action?.$actionType !== 'escalate')
+            continue;
+        if (guardrail.action.app?.name) {
+            rows.push(namedRow('app', guardrail.action.app.name, 'App name', guardrail.action.app.folderName));
+        }
+        rows.push(...assetRecipientRows([guardrail.action.recipient]));
+    }
+    return rows;
+}
+/**
+ * The `bindings_v2.json` rows one inline agent declares — what `uip agent
+ * refresh --inline-in-flow` generates for it, and what `uip agent validate
+ * --inline-in-flow` requires to be on disk (`AgentValidationDrift`,
+ * flow-builder-sdk#962).
+ *
+ * A transcription of the agent tool's own generator, `generateBindings` in
+ * `@uipath/tool-agent/agent-bindings` (Studio.Common `packager/src/bindings/`;
+ * read from 2.0.0, the version uipath-cli's agent-tool locks, and identical in the
+ * bundle of uip 1.205.0-dev.9071). It is a COPY, so
+ * `tests/agent-bindings-contract.test.ts` runs the real generator over the
+ * resources compile writes and fails on any row that differs.
+ *
+ * Inputs are read the way refresh reads them: every resource file, then any
+ * resource in `agent.json` whose name no file already has; the same for features.
+ * Rows are deduplicated on `resource` + `key`, first one wins.
+ */
+export function inlineAgentResources(files) {
+    const agent = isRecord(files.agent) ? files.agent : {};
+    const fileResources = files.resources.filter(isRecord);
+    const fileNames = new Set(fileResources.map((r) => r.name));
+    const resources = [
+        ...fileResources,
+        ...(Array.isArray(agent.resources) ? agent.resources.filter(isRecord) : []).filter((r) => !fileNames.has(r.name)),
+    ];
+    const fileFeatures = files.features.filter(isRecord);
+    const featureNames = new Set(fileFeatures.map((f) => f.name));
+    const features = [
+        ...fileFeatures,
+        ...(Array.isArray(agent.features) ? agent.features.filter(isRecord) : []).filter((f) => !featureNames.has(f.name)),
+    ];
+    const rows = [];
+    for (const resource of resources)
+        rows.push(...resourceRows(resource));
+    for (const feature of features) {
+        if (feature.$featureType === 'memorySpace') {
+            rows.push(namedRow('memorySpace', feature.memorySpaceName, 'Memory name', feature.folderPath));
+        }
+    }
+    rows.push(...agentDefinitionRows(agent));
+    const seen = new Set();
+    return rows.filter((row) => {
+        const id = `${row.resource}_${row.key}`;
+        if (seen.has(id))
+            return false;
+        seen.add(id);
+        return true;
+    });
+}
+/** Refresh's identity for "this agent's own earlier row": exact casing, plus the folder. */
+function agentRowDedupeKey(row) {
+    const value = isRecord(row.value) ? row.value : {};
+    const folderPath = isRecord(value.folderPath) ? value.folderPath.defaultValue ?? '' : '';
+    return `${row.resource}:${row.key}:${folderPath}`;
+}
+/** flow-schema's `mergeBindingResources` identity: resource case-insensitive, a connection's key too. */
+function mergeIdentity(row) {
+    const resource = String(row.resource ?? '').toLowerCase();
+    const key = String(row.key ?? row.id ?? '');
+    return `${resource}\u0000${resource === 'connection' ? key.toLowerCase() : key}`;
+}
+/**
+ * Fold one inline agent's rows into the project's rows, the way `uip agent
+ * refresh --inline-in-flow` does (`mergeInlineFlowBindings`): drop the rows that
+ * exactly match a fresh one (this agent's own earlier output), then keep the
+ * FIRST row per identity with the existing rows first — so a row the flow
+ * already declares wins over the agent's copy of it — and spell every
+ * connection row's `resource` as `connection`.
+ */
+export function mergeInlineAgentResources(existing, fresh) {
+    const freshKeys = new Set(fresh.map(agentRowDedupeKey));
+    const seen = new Set();
+    const out = [];
+    for (const row of [...existing.filter((r) => !freshKeys.has(agentRowDedupeKey(r))), ...fresh]) {
+        const id = mergeIdentity(row);
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        out.push(isConnection(row.resource) && row.resource !== 'connection' ? { ...row, resource: 'connection' } : row);
+    }
+    return out;
+}
+/** Read one inline agent's directory the way refresh does; `undefined` when it has no readable `agent.json`. */
+export function readInlineAgentFiles(agentDir) {
+    let agent;
+    try {
+        agent = JSON.parse(readFileSync(join(agentDir, 'agent.json'), 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+    const read = (sub, file, tag) => {
+        const dir = join(agentDir, sub);
+        if (!existsSync(dir))
+            return [];
+        const out = [];
+        for (const entry of readdirSync(dir).sort()) {
+            try {
+                const body = JSON.parse(readFileSync(join(dir, entry, file), 'utf8'));
+                if (isRecord(body) && body[tag])
+                    out.push(body);
+            }
+            catch {
+                // Refresh skips a malformed or missing file the same way.
+            }
+        }
+        return out;
+    };
+    return { agent, resources: read('resources', 'resource.json', '$resourceType'), features: read('features', 'feature.json', '$featureType') };
+}

package/dist/bpmn/compile-cli.js

@@ -15,7 +15,7 @@
  * XML (semantic-only — no diagram). The authoritative deploy gate is
  * `uip maestro bpmn validate`; a separate "tidy" step lays the diagram out.
  */
-import { reportResult } from '../cli-result.js';
+import { reportDiagnostics, reportResult, thrownDiagnostic } from '../cli-result.js';
 import { writeFileSync } from 'node:fs';
 import { basename, resolve } from 'node:path';
 import { resolveBpmnFile, loadBuiltBpmn } from './load.js';
@@ -54,11 +54,20 @@ export async function run(argv) {
     const diags = check(built, connectorCheckOpts(library, bindFile ? bindings : undefined));
     for (const d of diags)
         console.error(`  ${d.level === 'error' ? '✗' : '⚠'} [${d.code}] ${d.message}`);
+    // Reported before serialize, so every exit path carries what stderr printed.
+    reportDiagnostics(diags);
     if (diags.some((d) => d.level === 'error')) {
         console.error(`compile: ${diags.filter((d) => d.level === 'error').length} error(s); not emitting.`);
         return 1;
     }
-    const xml = await serialize(built, { library, bindings });
+    let xml;
+    try {
+        xml = await serialize(built, { library, bindings });
+    }
+    catch (error) {
+        reportDiagnostics([...diags, thrownDiagnostic(error)]);
+        throw error;
+    }
     const base = basename(file).replace(/\.bpmn\.ts$|\.ts$/, '');
     const out = flagValue(argv, '-o') ?? `${base}.bpmn`;
     writeFileSync(out, xml);

package/dist/bpmn/decompile.js

@@ -59,6 +59,7 @@ import { errorSchema, errorSchemaWithResponse } from './bpmn-sdk.js';
 import { SCRIPT_ARGS_ENVELOPE, defaultScriptInputSchema } from './serialize.js';
 import { BPMN_SCHEMA_VERSIONS } from './format-profile.js';
 import { preserveSchemaVersion } from '../schema-version.js';
+import { commentText } from '../core/comment-text.js';
 const require = createRequire(import.meta.url);
 const uipathDescriptor = require('./uipath-moddle.v1.json');
 /**
@@ -1828,7 +1829,7 @@ function variablesHost(defs, process) {
         `// collaboration, and the SDK models a bare bpmn:process — so recompiling this\n` +
         `// file will NOT reproduce the pool or its lanes, and the canvas will look\n` +
         `// different. Dropped:\n` +
-        dropped.map((d) => `//   - ${d}\n`).join('') +
+        dropped.map((d) => `//   - ${commentText(d)}\n`).join('') +
         `// The variables below were declared on the collaboration and are carried over;\n` +
         `// those scoped to it are rehomed onto the process, which is a legal scope.\n\n`;
     return { container: collab, rehome: { from: collab.id, to: process.id }, note };

package/dist/bpmn/registry-fallback.js

@@ -32,8 +32,12 @@
  *     `registry pull --force` and one more `get`. Both outcomes are remembered
  *     for the process, so a file with ten unknown nodes costs at most two CLI
  *     calls, not twenty.
+ *
+ * The call goes through `registry/uip/client.ts` (`runUipSync`), so
+ * `UIP_REPLAY_DIR` and `UIP_RECORD_DIR` apply here as they do to every other
+ * registry call.
  */
-import { execFileSync } from 'node:child_process';
+import { runUipSync } from '../registry/uip/client.js';
 /** The `uip` binary. Matches `scripts/materialize-bpmn-registry.mjs`. */
 const UIP = () => process.env.UIP ?? 'uip';
 /**
@@ -66,12 +70,10 @@ let warnedLive = false;
 function uip(args, timeoutMs) {
     let out;
     try {
-        out = execFileSync(UIP(), args, {
-            encoding: 'utf8',
-            stdio: ['ignore', 'pipe', 'ignore'],
-            timeout: timeoutMs,
-            maxBuffer: 64 * 1024 * 1024,
-        });
+        const result = runUipSync([UIP(), ...args], { timeoutMs });
+        if (result.code !== 0)
+            return undefined; // a non-zero exit or a timeout means no answer
+        out = result.stdout;
     }
     catch {
         return undefined;

package/dist/case/compile-cli.js

@@ -9,8 +9,9 @@
  * caseplan.json. The authoritative deploy gate is `uip maestro case validate`.
  * Output defaults to `caseplan.json` (the platform's canonical file name).
  */
-import { reportResult } from '../cli-result.js';
-import { writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { reportDiagnostics, reportResult, thrownDiagnostic } from '../cli-result.js';
+import { writeJsonFile } from '../core/json-file.js';
+import { readFileSync, existsSync } from 'node:fs';
 import { join, dirname, basename, resolve } from 'node:path';
 import { resolveCaseFile, loadBuiltCase } from './load.js';
 import { serialize } from './serialize.js';
@@ -40,6 +41,8 @@ export async function run(argv) {
     const diags = check(built);
     for (const d of diags)
         console.error(`  ${d.level === 'error' ? '✗' : '⚠'} [${d.code}] ${d.message}`);
+    // Reported before serialize, so every exit path carries what stderr printed.
+    reportDiagnostics(diags);
     const errors = diags.filter((d) => d.level === 'error');
     if (errors.length) {
         console.error(`compile: ${errors.length} error(s); not emitting.`);
@@ -55,9 +58,16 @@ export async function run(argv) {
     const library = openCliLibrary(argv);
     const bindFile = flagValue(argv, '--bindings') ?? defaultBindingsFile();
     const bindings = new Bindings(bindFile);
-    const caseplan = serialize(built, { library, bindings });
+    let caseplan;
+    try {
+        caseplan = serialize(built, { library, bindings });
+    }
+    catch (error) {
+        reportDiagnostics([...diags, thrownDiagnostic(error)]);
+        throw error;
+    }
     const out = flagValue(argv, '-o') ?? 'caseplan.json';
-    writeFileSync(out, JSON.stringify(caseplan, null, 2) + '\n');
+    writeJsonFile(out, caseplan);
     const stages = caseplan.nodes.filter((n) => String(n.type).endsWith('Stage')).length;
     const triggers = syncEntryPoints(caseplan, out);
     const epNote = triggers >= 0 ? `, synced entry-points.json (${triggers} trigger(s))` : '';
@@ -135,7 +145,7 @@ function syncEntryPoints(caseplan, outPath) {
             displayName: (n.data && n.data.label) || n.id,
         };
     });
-    writeFileSync(epPath, JSON.stringify(ep, null, 2) + '\n');
+    writeJsonFile(epPath, ep);
     return triggerNodes.length;
 }
 /**
@@ -243,7 +253,7 @@ function syncBindingsV2(caseplan, outPath) {
         });
     }
     resources.push(...connectionResources);
-    writeFileSync(sidecarPath, JSON.stringify({ version: '2.0', resources }, null, 2) + '\n');
+    writeJsonFile(sidecarPath, { version: '2.0', resources });
     return resources.length;
 }
 function referencedBindingValue(value, bindings) {

package/dist/case/decompile-cli.js

@@ -24,6 +24,7 @@ import { flagValue, runWhenInvokedDirectly } from '../cli-run.js';
 import { Library } from '../core/library.js';
 import { decompileWithDiagnostics } from './decompile.js';
 import { CASE_IMPORT } from '../package-name.js';
+import { commentText } from '../core/comment-text.js';
 /** Derive a PascalCase base name from the case name for the default output file. */
 function baseName(plan) {
     const src = plan.name ?? plan.id ?? 'Case';
@@ -88,7 +89,7 @@ export function run(argv) {
 function pipelineScript(originalPath, tsPath, pipelinePath, importSpecifier, bestEffort, libraryDir) {
     const base = pipelinePath.replace(/\.pipeline\.mjs$/, '');
     return `#!/usr/bin/env node
-// Generated by case decompile — edit ${basename(tsPath)}, then run this file.
+// Generated by case decompile — edit ${commentText(basename(tsPath))}, then run this file.
 import { execFileSync, spawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 

package/dist/case/decompile.js

@@ -1,3 +1,4 @@
+import { commentText } from '../core/comment-text.js';
 import { CASE_FORMAT_PROFILE, CASE_SCHEMA_VERSIONS } from './format-profile.js';
 import { preserveSchemaVersion } from '../schema-version.js';
 const TASK_KIND_METHOD = {
@@ -1164,7 +1165,7 @@ export function decompileWithDiagnostics(plan, options = {}) {
     if (schema.call)
         out.line(depth, schema.call);
     if (schema.problem)
-        out.line(depth, `// TODO: ${schema.problem}`);
+        out.line(depth, `// TODO: ${commentText(schema.problem)}`);
     if (plan.name !== undefined)
         out.line(depth, `.name(${str(plan.name)})`);
     if (plan.description !== undefined)
@@ -1205,7 +1206,7 @@ export function decompileWithDiagnostics(plan, options = {}) {
     const diagnosticHeader = diagnostics.length
         ? `${[
             '// BEST-EFFORT DECOMPILE: this source is intentionally not buildable until every marker below is repaired.',
-            ...diagnostics.map((diagnostic) => `// [${diagnostic.code}] ${diagnostic.location}: ${diagnostic.message}`
+            ...diagnostics.map((diagnostic) => `// [${commentText(diagnostic.code)}] ${commentText(diagnostic.location)}: ${commentText(diagnostic.message)}`
                 .replace(/[\r\n]+/g, ' ')),
         ].join('\n')}\n\n`
         : '';

package/dist/case/merge-cli.js

@@ -10,7 +10,8 @@
  * for what each side decides and why the join is by label rather than by id.
  */
 import { reportResult } from '../cli-result.js';
-import { readFileSync, writeFileSync } from 'node:fs';
+import { writeJsonFile } from '../core/json-file.js';
+import { readFileSync } from 'node:fs';
 import { basename, resolve } from 'node:path';
 import { mergeCase } from './merge.js';
 import { flagValue, runWhenInvokedDirectly } from '../cli-run.js';
@@ -32,7 +33,7 @@ export function run(argv) {
         warn: (message) => console.error(`case-merge: warning: ${message}`),
     });
     const out = flagValue(argv, '-o') ?? 'merged.caseplan.json';
-    writeFileSync(out, JSON.stringify(merged, null, 2) + '\n');
+    writeJsonFile(out, merged);
     const stages = (merged.nodes ?? [])
         .filter((node) => String(node.type ?? '').endsWith('Stage')).length;
     console.log(`case-merge: wrote ${basename(out)} (${stages} stage(s))`);