@sanity/workflow-cli 0.8.1 → 0.10.0

package/dist/commands/tail.js

@@ -1,10 +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 { buildClient, loadClient } from "../lib/client.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 = {
@@ -13,36 +17,38 @@ export default class Tail extends Command {
             description: 'Workflow instance id to tail.',
         }),
     };
+    static flags = {
+        ...tagFlags,
+    };
     async run() {
-        const { args } = await this.parse(Tail);
-        const client = loadClient();
-        const initial = await client.getDocument(args.instanceId);
-        if (!initial) {
+        const { args, flags } = await this.parse(Tail);
+        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;
         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`);
+                    process.stderr.write(`${styleText('red', `${logSymbols.error} fetch failed:`)} ${errorMessage(err)}\n`);
                 }
             },
             error: (err) => {
-                const message = err instanceof Error ? err.message : String(err);
-                fail('Listen subscription error:', message);
+                fail('Listen subscription error:', failureDetail(err));
             },
         });
         const shutdown = () => {
@@ -52,22 +58,15 @@ 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(() => { });
     }
-    /**
-     * 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;
     }

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,5 @@
+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. */
+declare const hook: Hook<'prerun'>;
+export default hook;

package/dist/hooks/prerun/telemetry.js

@@ -0,0 +1,5 @@
+import { setupCliTelemetry } from "../../lib/telemetry-setup.js";
+const hook = async function ({ config }) {
+    await setupCliTelemetry({ cliVersion: config.version });
+};
+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.d.ts

@@ -1,17 +1,14 @@
 import { type SanityClient } from '@sanity/client';
-export interface ClientEnv {
-    projectId: string;
-    dataset: string;
-    token: string;
-    apiHost: string;
-    apiVersion: string;
-}
-export declare function buildClient(env?: ClientEnv): SanityClient;
+import { type WorkflowResource } from '@sanity/workflow-engine';
 /**
- * {@link buildClient} but funnel a missing/empty `SANITY_*` env var
- * through the standard {@link failOnThrow} path, so commands fail with a
- * clean message rather than a raw stack trace. This is the boundary
- * commands call; {@link buildClient} stays throw-based for tests and for
- * callers that supply their own {@link ClientEnv}.
+ * 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 declare function loadClient(): SanityClient;
+export declare function resolveToken(): Promise<string>;
+/** {@link resolveToken}, funnelling the no-token case through the clean
+ *  {@link fail} path rather than letting it surface as an oclif stack. */
+export declare function resolveTokenOrFail(): Promise<string>;
+/** Build a client for a workflow resource, authenticated with `token`. */
+export declare function clientFor(resource: WorkflowResource, token: string): SanityClient;

package/dist/lib/client.js

@@ -1,40 +1,35 @@
+import { getCliToken, isStaging } from '@sanity/cli-core';
 import { createClient } from '@sanity/client';
-import { ENV } from "./env.js";
-import { failOnThrow } from "./fail.js";
-function readClientEnv() {
-    const projectId = process.env[ENV.SANITY_PROJECT_ID];
-    const token = process.env[ENV.SANITY_AUTH_TOKEN];
-    if (!projectId) {
-        throw new Error('SANITY_PROJECT_ID is required (set in root .env)');
+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';
+function resolveApiHost() {
+    return process.env[ENV.SANITY_API_HOST] ?? (isStaging() ? STAGING_API_HOST : undefined);
+}
+export async function resolveToken() {
+    const fromEnv = envAuthToken();
+    if (fromEnv !== undefined) {
+        return fromEnv;
     }
-    if (!token) {
-        throw new Error('SANITY_AUTH_TOKEN is required with editor role (set in root .env)');
+    const fromSession = await getCliToken();
+    if (fromSession) {
+        return fromSession;
     }
-    return {
-        projectId,
-        dataset: process.env[ENV.SANITY_DATASET] ?? 'production',
-        token,
-        apiHost: process.env[ENV.SANITY_API_HOST] ?? 'https://api.sanity.io',
-        apiVersion: '2026-04-29',
-    };
+    throw new Error('No Sanity token found — run `sanity login`, or set SANITY_AUTH_TOKEN.');
 }
-export function buildClient(env = readClientEnv()) {
-    return createClient({
-        projectId: env.projectId,
-        dataset: env.dataset,
-        apiVersion: env.apiVersion,
-        token: env.token,
-        apiHost: env.apiHost,
-        useCdn: false,
-    });
+export async function resolveTokenOrFail() {
+    return resolveToken().catch((err) => fail('Authentication required:', errorMessage(err)));
 }
-/**
- * {@link buildClient} but funnel a missing/empty `SANITY_*` env var
- * through the standard {@link failOnThrow} path, so commands fail with a
- * clean message rather than a raw stack trace. This is the boundary
- * commands call; {@link buildClient} stays throw-based for tests and for
- * callers that supply their own {@link ClientEnv}.
- */
-export function loadClient() {
-    return failOnThrow('Invalid Sanity client config:', () => buildClient());
+export function clientFor(resource, token) {
+    const apiHost = resolveApiHost();
+    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

@@ -0,0 +1,98 @@
+import type { SanityClient } from '@sanity/client';
+import type { WorkflowConfig, WorkflowDeployment, WorkflowInstance, WorkflowResource } from '@sanity/workflow-engine';
+import type { EngineScope } from './operation-args.ts';
+export interface DeploymentContext {
+    deployment: WorkflowDeployment;
+    client: SanityClient;
+}
+export interface InstanceContext {
+    client: SanityClient;
+    /** The engine scope derived from the instance itself — `{tag, workflowResource}`
+     *  ready to pass straight to an engine verb, so callers never re-assemble it. */
+    scope: EngineScope;
+}
+/**
+ * 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.
+ */
+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 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.
+ *
+ * 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 resolveReadTargets(flags: {
+    tag?: string | undefined;
+}): 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. 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
+ * 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 declare function resolveInstanceContext(flags: {
+    tag?: string | undefined;
+}, instanceId: string): Promise<InstanceContext>;
+/** 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 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

@@ -0,0 +1,83 @@
+import { clientFor, resolveTokenOrFail } from "./client.js";
+import { fail } from "./fail.js";
+import { loadWorkflowConfig } from "./load-config.js";
+import { selectDeployment } from "./select-deployment.js";
+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()) };
+}
+export async function resolveReadTargets(flags) {
+    const config = await loadWorkflowConfig();
+    const resources = resolveReadResources(config, flags.tag);
+    const token = await resolveTokenOrFail();
+    return resources.map((resource) => ({ resource, client: clientFor(resource, token) }));
+}
+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()];
+    if (resources.length === 0) {
+        fail('No deployments configured.');
+    }
+    return resources;
+}
+export function resolveReadResource(config, tag) {
+    const resources = resolveReadResources(config, tag);
+    const [sole] = resources;
+    if (resources.length === 1 && sole !== undefined) {
+        return sole;
+    }
+    const tags = config.deployments.map((d) => d.tag).join(', ');
+    fail('Config spans multiple resources — pass --tag to choose one.', `Available tags: ${tags}`);
+}
+export async function resolveInstanceContext(flags, instanceId) {
+    const config = await loadWorkflowConfig();
+    const workflowResource = resolveReadResource(config, flags.tag);
+    const client = clientFor(workflowResource, await resolveTokenOrFail());
+    const instance = await loadInstanceOrFail(client, instanceId);
+    return { client, scope: { tag: instance.tag, workflowResource } };
+}
+export async function loadInstanceOrFail(client, 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

@@ -1,36 +1,45 @@
-import { type WorkflowDefinition } from '@sanity/workflow-engine';
+import type { SanityClient } from '@sanity/client';
+import { type DeployedDefinition, type WorkflowDefinition } from '@sanity/workflow-engine';
+interface DefinitionShowQueryArgs {
+    name: string;
+    tag?: string | undefined;
+    version?: number | undefined;
+}
+export declare function buildDefinitionShowQuery(flags: DefinitionShowQueryArgs): {
+    groq: string;
+    params: Record<string, unknown>;
+};
 /**
- * Turn a configured definitions source into a specifier `import()` can
- * load. Path-like values (relative or absolute) resolve against `cwd` and
- * become file URLs so they're imported as files, not bare package names;
- * anything else passes through as a module specifier (e.g. a workspace
- * package such as `@sanity/workflow-examples`).
+ * 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 declare function resolveDefinitionsSpecifier(source: string, cwd: string): string;
+export declare function fetchDeployedDefinition({ client, name, tag, version, }: {
+    client: SanityClient;
+    name: string;
+    tag: string;
+    version: number | undefined;
+}): Promise<DeployedDefinition | undefined>;
 /**
- * Pull the `allDefinitions` array out of an imported definitions module,
- * failing hard with a source-specific message when the module doesn't
- * expose it. Per-definition structure is validated downstream by
- * {@link collectValidationErrors}, so this only asserts the array shape.
+ * 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 declare function extractDefinitions(mod: unknown, source: string): WorkflowDefinition[];
+export declare function selectDefinitions(allDefinitions: WorkflowDefinition[], { only, context }: {
+    only: string | undefined;
+    context?: string;
+}): WorkflowDefinition[];
 /**
- * Narrow the local batch to one definition `name`, 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).
- */
-export declare function selectDefinitions(allDefinitions: WorkflowDefinition[], only: string | undefined): WorkflowDefinition[];
-/**
- * The full local-definitions pipeline shared by `deploy` and
- * `definition diff`: resolve the `WORKFLOW_DEFS` source, import it,
- * narrow to `only` (when given), and fail on any validation error.
- */
-export declare function loadValidatedDefinitions(only: string | undefined): Promise<WorkflowDefinition[]>;
-/** {@link loadValidatedDefinitions} narrowed to exactly one definition name. */
-export declare function loadValidatedDefinition(name: string): Promise<WorkflowDefinition>;
-/**
- * Per-definition structural/GROQ checks plus one batch-level check the
- * engine doesn't do for us: duplicate `name` within the local set.
- * Returns the human-readable error lines; empty means the batch is valid.
+ * 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 declare function collectValidationErrors(defs: WorkflowDefinition[]): string[];
+/** 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 declare function validateOrFail(defs: WorkflowDefinition[], context?: string): void;
+export {};