@sanity/workflow-cli 0.9.0 → 0.11.0

package/dist/commands/tail.js

@@ -1,11 +1,14 @@
 import { styleText } from 'node:util';
-import { Args, Command } from '@oclif/core';
+import { Args } from '@oclif/core';
+import { displayTitle, errorMessage } from '@sanity/workflow-engine';
 import logSymbols from 'log-symbols';
-import { resolveReadContext } from "../lib/context.js";
-import { fail } from "../lib/fail.js";
+import { WorkflowCommand } from "../lib/base-command.js";
+import { findInstance, resolveReadTargets } from "../lib/context.js";
+import { fail, failureDetail } from "../lib/fail.js";
 import { tagFlags } from "../lib/flags.js";
 import { formatTimestamp } from "../lib/ui.js";
-export default class Tail extends Command {
+const TAIL_TAG = 'tail';
+export default class Tail extends WorkflowCommand {
     static description = 'Stream new history entries on a workflow instance as they land in the dataset.';
     static examples = ['<%= config.bin %> tail wf-instance.abc123'];
     static args = {
@@ -19,35 +22,34 @@ export default class Tail extends Command {
     };
     async run() {
         const { args, flags } = await this.parse(Tail);
-        const { client } = await resolveReadContext(flags);
-        const initial = await client.getDocument(args.instanceId);
-        if (!initial) {
+        const targets = await resolveReadTargets(flags);
+        const hit = await findInstance({ targets, instanceId: args.instanceId, requestTag: TAIL_TAG });
+        if (!hit) {
             fail(`No instance with id "${args.instanceId}"`);
         }
+        const { client, instance: initial } = hit;
         this.log(styleText('dim', `tailing ${styleText('bold', args.instanceId)} (${initial.definition} v${initial.pinnedVersion}, ${initial.history.length} prior entries, currently in ${initial.currentStage})`));
         this.log(styleText('dim', 'Ctrl+C to stop'));
         this.log('');
-        // Track the high-water mark so we only print history entries that
-        // landed after we started tailing. Listening with `includeResult:
-        // false` (matching what the studio does) keeps the wire payload
-        // small — we just refetch on each notification.
-        let seen = initial.history.length;
+        let rejectListen;
+        const listenFailed = new Promise((_, reject) => {
+            rejectListen = reject;
+        });
+        let printChain = Promise.resolve(initial.history.length);
         const subscription = client
-            .listen(`*[_id == $id]`, { id: args.instanceId }, { includeResult: false, visibility: 'query' })
+            .listen(`*[_id == $id]`, { id: args.instanceId }, {
+            includeResult: false,
+            visibility: 'query',
+            tag: TAIL_TAG,
+        })
             .subscribe({
-            next: async () => {
-                try {
-                    seen = await this.printNewEntries({ client, instanceId: args.instanceId, seen });
-                }
-                catch (err) {
-                    const message = err instanceof Error ? err.message : String(err);
-                    process.stderr.write(`${styleText('red', `${logSymbols.error} fetch failed:`)} ${message}\n`);
-                }
-            },
-            error: (err) => {
-                const message = err instanceof Error ? err.message : String(err);
-                fail('Listen subscription error:', message);
+            next: () => {
+                printChain = printChain.then((seen) => this.printNewEntries({ client, instanceId: args.instanceId, seen }).catch((err) => {
+                    process.stderr.write(`${styleText('red', `${logSymbols.error} fetch failed:`)} ${errorMessage(err)}\n`);
+                    return seen;
+                }));
             },
+            error: rejectListen,
         });
         const shutdown = () => {
             subscription.unsubscribe();
@@ -56,23 +58,19 @@ export default class Tail extends Command {
         };
         process.on('SIGINT', shutdown);
         process.on('SIGTERM', shutdown);
-        // Keep the event loop alive — `subscribe` doesn't itself anchor the
-        // process. The shutdown handlers above are the only exit path.
-        await new Promise(() => { });
+        await listenFailed.catch((err) => {
+            subscription.unsubscribe();
+            fail('Listen subscription error:', failureDetail(err));
+        });
     }
-    /**
-     * Fetch the current instance state, print history entries past the
-     * given high-water mark, return the new mark. Pulled out so the
-     * async work in the subscription's `next` handler stays tidy.
-     */
     async printNewEntries({ client, instanceId, seen, }) {
-        const next = await client.getDocument(instanceId);
+        const next = await client.getDocument(instanceId, { tag: TAIL_TAG });
         if (!next)
             return seen;
         const newEntries = next.history.slice(seen);
         for (const entry of newEntries) {
-            this.log(`${styleText('dim', `[${formatTimestamp(entry.at)}]`)} ${styleText('cyan', entry._type)}`);
+            this.log(`${styleText('dim', `[${formatTimestamp(entry.at)}]`)} ${styleText('cyan', displayTitle(entry._type))}`);
         }
-        return next.history.length;
+        return Math.max(seen, next.history.length);
     }
 }

package/dist/hooks/finally/telemetry.d.ts

@@ -0,0 +1,8 @@
+import type { Hook } from '@oclif/core';
+/**
+ * Completes the command trace — command id, declared-flag names, success —
+ * and flushes the final batch. Runs on success and on error alike (oclif's
+ * `finally`); an invocation the prerun hook left with telemetry off no-ops.
+ */
+declare const hook: Hook<'finally'>;
+export default hook;

package/dist/hooks/finally/telemetry.js

@@ -0,0 +1,13 @@
+import { finishCliTelemetry, usedFlagNames } from "../../lib/telemetry.js";
+const hook = async function (options) {
+    try {
+        await finishCliTelemetry({
+            command: options.id,
+            flags: usedFlagNames(options.argv, options.Command?.flags),
+            success: options.error === undefined,
+        });
+    }
+    catch {
+    }
+};
+export default hook;

package/dist/hooks/prerun/telemetry.d.ts

@@ -0,0 +1,8 @@
+import type { Hook } from '@oclif/core';
+/** Builds and installs the invocation's telemetry shell before the command
+ *  runs; the `finally` hook completes the trace and flushes. Never throws.
+ *  An explicit `--share-defs` forces the store to send despite CI /
+ *  `DO_NOT_TRACK` — resolved from raw argv here, since the store is built
+ *  before oclif parses flags. */
+declare const hook: Hook<'prerun'>;
+export default hook;

package/dist/hooks/prerun/telemetry.js

@@ -0,0 +1,9 @@
+import { shouldForceShareTelemetry } from "../../lib/share-definitions.js";
+import { setupCliTelemetry } from "../../lib/telemetry-setup.js";
+const hook = async function ({ config, Command, argv }) {
+    await setupCliTelemetry({
+        cliVersion: config.version,
+        forceSend: shouldForceShareTelemetry({ commandId: Command?.id, argv }),
+    });
+};
+export default hook;

package/dist/index.js

@@ -1,4 +1 @@
-// Library entry for the package's `.` export. The CLI itself runs through the
-// `bin/run.js` (published) and `bin/dev.js` (dev) entries; this module exists
-// only to satisfy the repo's source-first exports map.
 export { execute } from '@oclif/core';

package/dist/lib/base-command.d.ts

@@ -0,0 +1,14 @@
+import { Command } from '@oclif/core';
+/**
+ * Base for the API-backed workflow commands: the backstop that renders an
+ * auth rejection (HTTP 401) escaping a command's `run` through the clean
+ * {@link fail} path — with {@link failureDetail}'s recovery hint — instead
+ * of an oclif error dump. Errors caught inside commands render the same
+ * detail at their own `fail` sites; every other error propagates to oclif
+ * unchanged.
+ */
+export declare abstract class WorkflowCommand extends Command {
+    protected catch(err: Error & {
+        exitCode?: number;
+    }): Promise<unknown>;
+}

package/dist/lib/base-command.js

@@ -0,0 +1,10 @@
+import { Command } from '@oclif/core';
+import { fail, failureDetail, isAuthRejection } from "./fail.js";
+export class WorkflowCommand extends Command {
+    async catch(err) {
+        if (isAuthRejection(err)) {
+            fail('Authentication failed:', failureDetail(err));
+        }
+        return super.catch(err);
+    }
+}

package/dist/lib/client.js

@@ -1,28 +1,16 @@
 import { getCliToken, isStaging } from '@sanity/cli-core';
 import { createClient } from '@sanity/client';
-import { datasetResourceParts, ENGINE_API_VERSION, } from '@sanity/workflow-engine';
-import { ENV } from "./env.js";
+import { clientConfigFromResource, ENGINE_API_VERSION, errorMessage, } from '@sanity/workflow-engine';
+import { ENV, envAuthToken } from "./env.js";
 import { fail } from "./fail.js";
 const API_VERSION = ENGINE_API_VERSION;
 const STAGING_API_HOST = 'https://api.sanity.work';
-/**
- * The API host to hit: an explicit `SANITY_API_HOST` wins; otherwise mirror
- * the Sanity CLI — staging routes to the staging API, prod falls through to
- * `@sanity/client`'s default. Pairs with {@link resolveToken}, which reads the
- * matching session token.
- */
 function resolveApiHost() {
     return process.env[ENV.SANITY_API_HOST] ?? (isStaging() ? STAGING_API_HOST : undefined);
 }
-/**
- * Resolve the Sanity auth token. An explicit `SANITY_AUTH_TOKEN` wins (CI /
- * scripted use); otherwise fall back to the `sanity login` session token.
- * Throws when neither exists rather than building an unauthenticated client
- * that only 401s once it hits the API.
- */
 export async function resolveToken() {
-    const fromEnv = process.env[ENV.SANITY_AUTH_TOKEN]?.trim();
-    if (fromEnv) {
+    const fromEnv = envAuthToken();
+    if (fromEnv !== undefined) {
         return fromEnv;
     }
     const fromSession = await getCliToken();
@@ -31,22 +19,17 @@ export async function resolveToken() {
     }
     throw new Error('No Sanity token found — run `sanity login`, or set SANITY_AUTH_TOKEN.');
 }
-/** {@link resolveToken}, funnelling the no-token case through the clean
- *  {@link fail} path rather than letting it surface as an oclif stack. */
 export async function resolveTokenOrFail() {
-    return resolveToken().catch((err) => fail('Authentication required:', err instanceof Error ? err.message : String(err)));
+    return resolveToken().catch((err) => fail('Authentication required:', errorMessage(err)));
 }
-/** Build a client for a workflow resource, authenticated with `token`. */
 export function clientFor(resource, token) {
     const apiHost = resolveApiHost();
-    const baseParams = { token, apiVersion: API_VERSION, useCdn: false, ...(apiHost ? { apiHost } : {}) };
-    // A dataset goes through the classic {projectId, dataset} config — the proven
-    // path, and it keeps `tail`'s client.listen() on well-trodden ground. Other
-    // resource types have no projectId/dataset split, so they pass through as a
-    // resource directly.
-    if (resource.type === 'dataset') {
-        const { projectId, dataset } = datasetResourceParts(resource.id);
-        return createClient({ ...baseParams, projectId, dataset });
-    }
-    return createClient({ ...baseParams, resource });
+    const baseParams = {
+        token,
+        apiVersion: API_VERSION,
+        useCdn: false,
+        requestTagPrefix: 'sanity.workflows.cli',
+        ...(apiHost ? { apiHost } : {}),
+    };
+    return createClient({ ...baseParams, ...clientConfigFromResource(resource) });
 }

package/dist/lib/context.d.ts

@@ -20,24 +20,34 @@ export interface InstanceContext {
 export declare function resolveContext(flags: {
     tag?: string | undefined;
 }): Promise<DeploymentContext>;
+/** One resource a read inspects, with its authenticated client. */
+export interface ReadTarget {
+    resource: WorkflowResource;
+    client: SanityClient;
+}
 /**
- * The resolution a READ shares: an authenticated client for the resource to
- * inspect — and nothing more. A read lists/inspects whatever is in the Content
- * Lake, so it must NOT inherit a deployment's tag or definition set as a
- * filter. The config only locates the resource here; the command applies the
- * user's explicit `--tag` (if any) as a query filter itself.
+ * The resolution every READ shares: an authenticated client per resource to
+ * inspect — and nothing more. A read lists/inspects whatever is in the
+ * Content Lake, so it must NOT inherit a deployment's tag or definition set
+ * as a filter. The config only locates the resources here; the command
+ * applies the user's explicit `--tag` (if any) as a query filter itself.
  *
- * Resource selection: when every deployment targets the same resource (the
- * common case) it's used with no `--tag` needed; only a config that spans
- * *different* resources needs `--tag` to say which dataset to read.
+ * Untagged, this is every distinct resource the config mentions — a read is
+ * harmless to fan out, so "show me what's deployed" spans the whole config.
+ * `--tag` narrows to that deployment's resource. The token resolves once for
+ * the run, however many targets it spans.
  */
-export declare function resolveReadContext(flags: {
+export declare function resolveReadTargets(flags: {
     tag?: string | undefined;
-}): Promise<{
-    client: SanityClient;
-}>;
+}): Promise<ReadTarget[]>;
+/** The distinct resources a read targets: the tagged deployment's sole
+ *  resource, or — untagged — every distinct one the config's deployments
+ *  mention (deduped by `type:id`). */
+export declare function resolveReadResources(config: WorkflowConfig, tag: string | undefined): WorkflowResource[];
 /** The single resource a read should target, or fail asking which when the
- *  config spans more than one. */
+ *  config spans more than one. For the paths that need one definite dataset
+ *  (the instance-targeted verbs); listings fan out via
+ *  {@link resolveReadResources} instead. */
 export declare function resolveReadResource(config: WorkflowConfig, tag: string | undefined): WorkflowResource;
 /**
  * The resolution an instance-id-targeted command shares, read or write: an
@@ -60,3 +70,29 @@ export declare function resolveInstanceContext(flags: {
  *  {@link resolveInstanceContext} so the not-found path is unit-testable
  *  without a live config/token/client. */
 export declare function loadInstanceOrFail(client: Pick<SanityClient, 'getDocument'>, instanceId: string): Promise<WorkflowInstance>;
+/** A read target that turned out to hold the instance being looked up. */
+export interface InstanceHit extends ReadTarget {
+    instance: WorkflowInstance;
+}
+/**
+ * The sole cross-resource hit, or fail listing every holding resource —
+ * ambiguity across datasets must error, never pick. `subject` names the
+ * thing being looked up in the diagnostic (`Instance <id>`, `Definition "x"`).
+ */
+export declare function soleHitOrFail<T extends {
+    resource: WorkflowResource;
+}>(hits: T[], subject: string): T | undefined;
+/**
+ * Look an instance id up across every read target. Exactly one hit wins —
+ * instance ids are random and collision-free, so a single match IS the
+ * instance. Several hits (id reuse across datasets) fail listing the
+ * resources rather than silently picking one. `undefined` means confidently
+ * not found: when a probe throws and no other target has the id, that error
+ * propagates instead — an unreadable dataset must not masquerade as "no such
+ * instance".
+ */
+export declare function findInstance({ targets, instanceId, requestTag, }: {
+    targets: ReadTarget[];
+    instanceId: string;
+    requestTag: string;
+}): Promise<InstanceHit | undefined>;

package/dist/lib/context.js

@@ -2,66 +2,41 @@ import { clientFor, resolveTokenOrFail } from "./client.js";
 import { fail } from "./fail.js";
 import { loadWorkflowConfig } from "./load-config.js";
 import { selectDeployment } from "./select-deployment.js";
-/**
- * The resolution a WRITE shares: discover the config, pick the deployment for
- * `--tag` (or the sole one), and build an authenticated client for that
- * deployment's resource. A write acts on one specific deployment, so a
- * single, definite target is exactly what it needs.
- */
+import { resourceLabel } from "./ui.js";
 export async function resolveContext(flags) {
     const config = await loadWorkflowConfig();
     const deployment = selectDeployment(config, { tag: flags.tag });
     return { deployment, client: clientFor(deployment.workflowResource, await resolveTokenOrFail()) };
 }
-/**
- * The resolution a READ shares: an authenticated client for the resource to
- * inspect — and nothing more. A read lists/inspects whatever is in the Content
- * Lake, so it must NOT inherit a deployment's tag or definition set as a
- * filter. The config only locates the resource here; the command applies the
- * user's explicit `--tag` (if any) as a query filter itself.
- *
- * Resource selection: when every deployment targets the same resource (the
- * common case) it's used with no `--tag` needed; only a config that spans
- * *different* resources needs `--tag` to say which dataset to read.
- */
-export async function resolveReadContext(flags) {
+export async function resolveReadTargets(flags) {
     const config = await loadWorkflowConfig();
-    return { client: clientFor(resolveReadResource(config, flags.tag), await resolveTokenOrFail()) };
+    const resources = resolveReadResources(config, flags.tag);
+    const token = await resolveTokenOrFail();
+    return resources.map((resource) => ({ resource, client: clientFor(resource, token) }));
 }
-/** The single resource a read should target, or fail asking which when the
- *  config spans more than one. */
-export function resolveReadResource(config, tag) {
+export function resolveReadResources(config, tag) {
+    if (tag !== undefined) {
+        return [selectDeployment(config, { tag }).workflowResource];
+    }
     const byKey = new Map(config.deployments.map((d) => [
         `${d.workflowResource.type}:${d.workflowResource.id}`,
         d.workflowResource,
     ]));
     const resources = [...byKey.values()];
-    const [sole] = resources;
-    if (sole === undefined) {
+    if (resources.length === 0) {
         fail('No deployments configured.');
     }
-    if (resources.length === 1) {
+    return resources;
+}
+export function resolveReadResource(config, tag) {
+    const resources = resolveReadResources(config, tag);
+    const [sole] = resources;
+    if (resources.length === 1 && sole !== undefined) {
         return sole;
     }
-    if (tag === undefined) {
-        const tags = config.deployments.map((d) => d.tag).join(', ');
-        fail('Config spans multiple resources — pass --tag to choose one.', `Available tags: ${tags}`);
-    }
-    return selectDeployment(config, { tag }).workflowResource;
+    const tags = config.deployments.map((d) => d.tag).join(', ');
+    fail('Config spans multiple resources — pass --tag to choose one.', `Available tags: ${tags}`);
 }
-/**
- * The resolution an instance-id-targeted command shares, read or write: an
- * authenticated client for the resource, plus the instance itself — so the
- * command derives its partition (`tag`) from the instance, never from the
- * config's declared deployments. An instance id is globally unique and carries
- * its own `tag`, so a command that names one acts on that instance regardless
- * of which tags the config happens to deploy; the config only locates the
- * resource (via {@link resolveReadResource}, no tag filter).
- *
- * Contrast {@link resolveContext}: the deploy/diff/delete path IS scoped to a
- * declared deployment because it acts on the authored definition set (or a
- * definition name, which — unlike an instance id — isn't unique across tags).
- */
 export async function resolveInstanceContext(flags, instanceId) {
     const config = await loadWorkflowConfig();
     const workflowResource = resolveReadResource(config, flags.tag);
@@ -69,14 +44,40 @@ export async function resolveInstanceContext(flags, instanceId) {
     const instance = await loadInstanceOrFail(client, instanceId);
     return { client, scope: { tag: instance.tag, workflowResource } };
 }
-/** Fetch an instance by id, exiting cleanly when the resource has no such
- *  document — the diagnostic an operator sees on a mistyped id. Split out from
- *  {@link resolveInstanceContext} so the not-found path is unit-testable
- *  without a live config/token/client. */
 export async function loadInstanceOrFail(client, instanceId) {
-    const instance = await client.getDocument(instanceId);
+    const instance = await client.getDocument(instanceId, {
+        tag: 'instance.load',
+    });
     if (!instance) {
         fail(`Workflow instance ${instanceId} not found`);
     }
     return instance;
 }
+export function soleHitOrFail(hits, subject) {
+    const [sole, ...rest] = hits;
+    if (rest.length > 0) {
+        fail(`${subject} exists in several resources — pass --tag to choose one.`, hits.map((hit) => resourceLabel(hit.resource)).join('\n'));
+    }
+    return sole;
+}
+export async function findInstance({ targets, instanceId, requestTag, }) {
+    const probes = await Promise.allSettled(targets.map(async (target) => {
+        const instance = await target.client.getDocument(instanceId, {
+            tag: requestTag,
+        });
+        return instance === undefined ? undefined : { ...target, instance };
+    }));
+    const hits = probes
+        .filter((probe) => probe.status === 'fulfilled')
+        .map((probe) => probe.value)
+        .filter((hit) => hit !== undefined);
+    const sole = soleHitOrFail(hits, `Instance ${instanceId}`);
+    if (sole !== undefined) {
+        return sole;
+    }
+    const failedProbe = probes.find((probe) => probe.status === 'rejected');
+    if (failedProbe !== undefined) {
+        throw failedProbe.reason;
+    }
+    return undefined;
+}

package/dist/lib/definitions.d.ts

@@ -9,6 +9,16 @@ export declare function buildDefinitionShowQuery(flags: DefinitionShowQueryArgs)
     groq: string;
     params: Record<string, unknown>;
 };
+/**
+ * The tag partitions holding any version of a definition name within one
+ * dataset. An untagged lookup that would span several partitions must error
+ * (the highest version ACROSS partitions is meaningless — it could show a
+ * prod operator the dev definition), the same way a cross-dataset hit does.
+ */
+export declare function buildDefinitionTagsQuery(name: string): {
+    groq: string;
+    params: Record<string, unknown>;
+};
 /**
  * Fetch the deployed definition a command targets — latest unless pinned via
  * `version`. An absent pinned version always fails (the caller asked for

package/dist/lib/definitions.js

@@ -1,5 +1,5 @@
-import { WORKFLOW_DEFINITION_TYPE, tagScopeFilter, validateDefinition, } from '@sanity/workflow-engine';
-import { errorMessage, fail } from "./fail.js";
+import { WORKFLOW_DEFINITION_TYPE, errorMessage, tagScopeFilter, validateDefinition, } from '@sanity/workflow-engine';
+import { fail } from "./fail.js";
 export function buildDefinitionShowQuery(flags) {
     const params = { name: flags.name };
     const filters = [`_type == "${WORKFLOW_DEFINITION_TYPE}"`, 'name == $name'];
@@ -14,26 +14,22 @@ export function buildDefinitionShowQuery(flags) {
     const groq = `*[${filters.join(' && ')}] | order(version desc) [0]`;
     return { groq, params };
 }
-/**
- * Fetch the deployed definition a command targets — latest unless pinned via
- * `version`. An absent pinned version always fails (the caller asked for
- * something specific); an absent latest returns `undefined` so the caller
- * decides whether that's fatal.
- */
+export function buildDefinitionTagsQuery(name) {
+    return {
+        groq: `array::unique(*[_type == "${WORKFLOW_DEFINITION_TYPE}" && name == $name].tag)`,
+        params: { name },
+    };
+}
 export async function fetchDeployedDefinition({ client, name, tag, version, }) {
     const { groq, params } = buildDefinitionShowQuery({ name, tag, version });
-    const deployed = await client.fetch(groq, params);
+    const deployed = await client.fetch(groq, params, {
+        tag: 'definition.load',
+    });
     if (deployed === null && version !== undefined) {
         fail(`No deployed definition "${name}" v${version}.`);
     }
     return deployed ?? undefined;
 }
-/**
- * Narrow a batch to one definition name (`only`), failing with the available
- * names when there's no match. With `only` unset the whole batch passes through
- * (a fresh array, so callers can mutate without aliasing). `context` prefixes
- * the failure so callers whose run spans several deployments can attribute it.
- */
 export function selectDefinitions(allDefinitions, { only, context = '' }) {
     if (!only) {
         return [...allDefinitions];
@@ -45,11 +41,6 @@ export function selectDefinitions(allDefinitions, { only, context = '' }) {
     }
     return filtered;
 }
-/**
- * Per-definition structural/GROQ checks plus one batch-level check the engine
- * doesn't do for us: duplicate `name` within the set. Returns the
- * human-readable error lines; empty means the batch is valid.
- */
 export function collectValidationErrors(defs) {
     const errors = [];
     const seen = new Map();
@@ -70,10 +61,6 @@ export function collectValidationErrors(defs) {
     }
     return errors;
 }
-/** Validate a set of definitions, exiting with the collected errors on any
- *  failure. The single validate-then-fail gate `deploy` and `definition diff`
- *  share, so the two can't drift into divergent failure messages. `context`
- *  prefixes the failure with the deployment it belongs to in multi-target runs. */
 export function validateOrFail(defs, context = '') {
     const errors = collectValidationErrors(defs);
     if (errors.length > 0) {

package/dist/lib/diff.d.ts

@@ -2,7 +2,10 @@ import type { DiffEntry } from '@sanity/workflow-engine';
 /** One summary line per diff entry, tagged create / unchanged. Definitions are
  *  immutable, so a content change is a new version (`create`), never an update. */
 export declare function summaryLines(entries: DiffEntry[]): string[];
-/** Render a JSON diff of `oldObj` → `newObj` as `+`/`-`/context lines. */
+/** Render a JSON diff of `oldObj` → `newObj` as `+`/`-`/context lines, long
+ *  unchanged runs collapsed to a dim `… N unchanged lines` marker. */
 export declare function diffLines(oldObj: object, newObj: object): string[];
-/** The full diff report: the summary block plus a per-change diff. */
+/** The full diff report: the summary block plus a per-change diff of the
+ *  authored content — the deploy envelope is stripped from both sides (the
+ *  version and docId already render on the summary line). */
 export declare function diffReport(entries: DiffEntry[]): string[];