@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/workflow/api/resolve-command.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveWorkflowCommandId = void 0;
+/**
+ * Resolve a human-friendly workflow command name (e.g. "Submit",
+ * "Approve") to its `commandId` for a specific item's current state.
+ *
+ * Returns `null` if the workflow exposes no command with that name at
+ * the item's current state.
+ */
+const resolveWorkflowCommandId = async (client, options) => {
+    const wanted = options.commandName.toLowerCase();
+    const commands = await client.getWorkflowCommandsForItem({
+        workflowId: options.workflowId,
+        itemId: options.itemId,
+    });
+    const matches = commands.filter((c) => c.displayName.toLowerCase() === wanted);
+    if (matches.length === 0)
+        return null;
+    return {
+        commandId: matches[0].commandId,
+        displayName: matches[0].displayName,
+        duplicateMatches: matches.length,
+    };
+};
+exports.resolveWorkflowCommandId = resolveWorkflowCommandId;

package/dist/workflow/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Public entry for `@sitecoreai-labs/sitecoreai-cli/workflow`.
+ *
+ * Sitecore item workflow surface — state inspection, command resolution,
+ * advance/apply/reset lifecycle. Authoring GraphQL underneath.
+ */
+export { createWorkflowApiClient, type WorkflowApiClient, type WorkflowClientOptions, type ItemSelector, type ItemWorkflowState, type WorkflowCommandSummary, type WorkflowExecutionResult, type ExecuteWorkflowCommandInput, type WorkflowDefinitionSummary, type ListWorkflowDefinitionsOptions, type AssignedItemSummary, type SearchItemsByWorkflowStateOptions, type WorkflowDefinitionDetail, type WorkflowStateDetail, type WorkflowCommandDetail, type WorkflowChildSummary, } from "./api/client";
+export { resolveWorkflowCommandId, type ResolveWorkflowCommandOptions, type ResolveWorkflowCommandResult, } from "./api/resolve-command";
+export { runWorkflowAuthoringGraphQL, type WorkflowRequestOptions } from "./api/graphql";
+export { runWorkflowInspect, type WorkflowInspectOptions, type WorkflowInspectResult, } from "./tasks/inspect";
+export { runWorkflowListCommands, type WorkflowListCommandsOptions, type WorkflowListCommandsResult, } from "./tasks/list-commands";
+export { runWorkflowListDefs, type WorkflowListDefsOptions, type WorkflowListDefsResult, } from "./tasks/list-defs";
+export { runWorkflowStatus, type WorkflowStatusOptions, type WorkflowStatusResult, } from "./tasks/status";
+export { runWorkflowAssigned, type WorkflowAssignedOptions, type WorkflowAssignedResult, } from "./tasks/assigned";
+export { runWorkflowAdvance, type WorkflowAdvanceOptions, type WorkflowAdvanceResult, type WorkflowAdvanceStatus, } from "./tasks/advance";
+export { runWorkflowReset, type WorkflowResetOptions, type WorkflowResetResult, type WorkflowResetStatus, } from "./tasks/reset";
+export { runWorkflowApply, type WorkflowApplyOptions, type WorkflowApplyResult, type WorkflowApplyStatus, } from "./tasks/apply";
+export { type WorkflowTaskOptions, type ResolvedWorkflowTenant, resolveWorkflowTenant, toLogger, parseItemReference, printWorkflowResult, dashifyItemId, } from "./tasks/shared";

package/dist/workflow/index.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * Public entry for `@sitecoreai-labs/sitecoreai-cli/workflow`.
+ *
+ * Sitecore item workflow surface — state inspection, command resolution,
+ * advance/apply/reset lifecycle. Authoring GraphQL underneath.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dashifyItemId = exports.printWorkflowResult = exports.parseItemReference = exports.toLogger = exports.resolveWorkflowTenant = exports.runWorkflowApply = exports.runWorkflowReset = exports.runWorkflowAdvance = exports.runWorkflowAssigned = exports.runWorkflowStatus = exports.runWorkflowListDefs = exports.runWorkflowListCommands = exports.runWorkflowInspect = exports.runWorkflowAuthoringGraphQL = exports.resolveWorkflowCommandId = exports.createWorkflowApiClient = void 0;
+var client_1 = require("./api/client");
+Object.defineProperty(exports, "createWorkflowApiClient", { enumerable: true, get: function () { return client_1.createWorkflowApiClient; } });
+var resolve_command_1 = require("./api/resolve-command");
+Object.defineProperty(exports, "resolveWorkflowCommandId", { enumerable: true, get: function () { return resolve_command_1.resolveWorkflowCommandId; } });
+var graphql_1 = require("./api/graphql");
+Object.defineProperty(exports, "runWorkflowAuthoringGraphQL", { enumerable: true, get: function () { return graphql_1.runWorkflowAuthoringGraphQL; } });
+var inspect_1 = require("./tasks/inspect");
+Object.defineProperty(exports, "runWorkflowInspect", { enumerable: true, get: function () { return inspect_1.runWorkflowInspect; } });
+var list_commands_1 = require("./tasks/list-commands");
+Object.defineProperty(exports, "runWorkflowListCommands", { enumerable: true, get: function () { return list_commands_1.runWorkflowListCommands; } });
+var list_defs_1 = require("./tasks/list-defs");
+Object.defineProperty(exports, "runWorkflowListDefs", { enumerable: true, get: function () { return list_defs_1.runWorkflowListDefs; } });
+var status_1 = require("./tasks/status");
+Object.defineProperty(exports, "runWorkflowStatus", { enumerable: true, get: function () { return status_1.runWorkflowStatus; } });
+var assigned_1 = require("./tasks/assigned");
+Object.defineProperty(exports, "runWorkflowAssigned", { enumerable: true, get: function () { return assigned_1.runWorkflowAssigned; } });
+var advance_1 = require("./tasks/advance");
+Object.defineProperty(exports, "runWorkflowAdvance", { enumerable: true, get: function () { return advance_1.runWorkflowAdvance; } });
+var reset_1 = require("./tasks/reset");
+Object.defineProperty(exports, "runWorkflowReset", { enumerable: true, get: function () { return reset_1.runWorkflowReset; } });
+var apply_1 = require("./tasks/apply");
+Object.defineProperty(exports, "runWorkflowApply", { enumerable: true, get: function () { return apply_1.runWorkflowApply; } });
+var shared_1 = require("./tasks/shared");
+Object.defineProperty(exports, "resolveWorkflowTenant", { enumerable: true, get: function () { return shared_1.resolveWorkflowTenant; } });
+Object.defineProperty(exports, "toLogger", { enumerable: true, get: function () { return shared_1.toLogger; } });
+Object.defineProperty(exports, "parseItemReference", { enumerable: true, get: function () { return shared_1.parseItemReference; } });
+Object.defineProperty(exports, "printWorkflowResult", { enumerable: true, get: function () { return shared_1.printWorkflowResult; } });
+Object.defineProperty(exports, "dashifyItemId", { enumerable: true, get: function () { return shared_1.dashifyItemId; } });

package/dist/workflow/tasks/advance.d.ts

@@ -0,0 +1,39 @@
+import { type WorkflowTaskOptions } from "./shared";
+export interface WorkflowAdvanceOptions extends WorkflowTaskOptions {
+    /** Item GUID or content-tree path. Required. */
+    item: string;
+    /** Workflow command display name (case-insensitive). Required. */
+    command: string;
+    /** Comment recorded with the workflow execution (audit trail). */
+    comments?: string;
+    /** Plan-only — don't issue the mutation. */
+    whatIf?: boolean;
+    /** Per-invocation write gate override (matches the `cleanup` `--allow-write` flag). */
+    allowWrite?: boolean;
+}
+export type WorkflowAdvanceStatus = "advanced" | "what-if" | "failed" | "skipped-no-workflow" | "skipped-final" | "skipped-no-command";
+export interface WorkflowAdvanceResult {
+    itemId: string | null;
+    path: string | null;
+    workflowName: string | null;
+    fromState: string | null;
+    toState: string | null;
+    commandRequested: string;
+    commandUsed: string | null;
+    status: WorkflowAdvanceStatus;
+    message?: string;
+}
+/**
+ * Advance a single Sitecore item through one workflow transition.
+ *
+ * The single-item primitive — counterpart to
+ * `scai hygiene cleanup workflow advance`, which sweeps stale items in batch.
+ * Use this verb for surgical "push this approval through now"
+ * operations; use the cleanup verb for scheduled backlog flushes.
+ *
+ * Gating: same `allowWrite` model as cleanup (env config /
+ * `SITECOREAI_ENV_<NAME>_ALLOW_WRITE=true` / `--allow-write`).
+ * `--what-if` skips the gate and reports the planned action without
+ * issuing the mutation.
+ */
+export declare const runWorkflowAdvance: (options: WorkflowAdvanceOptions) => Promise<WorkflowAdvanceResult>;

package/dist/workflow/tasks/advance.js

@@ -0,0 +1,182 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runWorkflowAdvance = void 0;
+const allow_write_1 = require("../../policy/allow-write");
+const errors_1 = require("../../shared/errors");
+const resolve_command_1 = require("../api/resolve-command");
+const shared_1 = require("./shared");
+/**
+ * Advance a single Sitecore item through one workflow transition.
+ *
+ * The single-item primitive — counterpart to
+ * `scai hygiene cleanup workflow advance`, which sweeps stale items in batch.
+ * Use this verb for surgical "push this approval through now"
+ * operations; use the cleanup verb for scheduled backlog flushes.
+ *
+ * Gating: same `allowWrite` model as cleanup (env config /
+ * `SITECOREAI_ENV_<NAME>_ALLOW_WRITE=true` / `--allow-write`).
+ * `--what-if` skips the gate and reports the planned action without
+ * issuing the mutation.
+ */
+const runWorkflowAdvance = async (options) => {
+    const logger = (0, shared_1.toLogger)(options);
+    if (!options.command) {
+        throw (0, errors_1.createScaiError)("--command is required.", "INPUT_INVALID");
+    }
+    const selector = (0, shared_1.parseItemReference)(options.item);
+    const { envName, root, client } = (0, shared_1.resolveWorkflowTenant)(options);
+    if (!options.whatIf) {
+        (0, allow_write_1.ensureAllowWrite)(root, envName, options.allowWrite);
+    }
+    else if (!logger.isJson()) {
+        logger.info("What-if mode — no workflow command will be executed.", "yellow");
+    }
+    const wf = await client.getItemWorkflow(selector);
+    if (!wf || !wf.workflowId) {
+        const result = {
+            itemId: wf?.itemId ?? null,
+            path: wf?.path ?? selector.path ?? null,
+            workflowName: null,
+            fromState: null,
+            toState: null,
+            commandRequested: options.command,
+            commandUsed: null,
+            status: "skipped-no-workflow",
+            message: `Item ${selector.path ?? selector.itemId} is not under workflow.`,
+        };
+        (0, shared_1.printWorkflowResult)({
+            logger,
+            command: "workflow.advance",
+            envName,
+            result,
+            humanLines: [result.message ?? ""],
+        });
+        return result;
+    }
+    if (wf.stateIsFinal) {
+        const result = {
+            itemId: wf.itemId,
+            path: wf.path,
+            workflowName: wf.workflowName,
+            fromState: wf.stateName,
+            toState: null,
+            commandRequested: options.command,
+            commandUsed: null,
+            status: "skipped-final",
+            message: `Item is already in a final workflow state ('${wf.stateName ?? "?"}'); no transition needed.`,
+        };
+        (0, shared_1.printWorkflowResult)({
+            logger,
+            command: "workflow.advance",
+            envName,
+            result,
+            humanLines: [result.message ?? ""],
+        });
+        return result;
+    }
+    const command = await (0, resolve_command_1.resolveWorkflowCommandId)(client, {
+        workflowId: wf.workflowId,
+        itemId: (0, shared_1.dashifyItemId)(wf.itemId),
+        commandName: options.command,
+    });
+    if (!command) {
+        const result = {
+            itemId: wf.itemId,
+            path: wf.path,
+            workflowName: wf.workflowName,
+            fromState: wf.stateName,
+            toState: null,
+            commandRequested: options.command,
+            commandUsed: null,
+            status: "skipped-no-command",
+            message: `Workflow '${wf.workflowName}' has no command named '${options.command}' at state '${wf.stateName ?? "?"}'. Run 'scai content workflow list-commands ${selector.path ?? selector.itemId}' to see available commands.`,
+        };
+        (0, shared_1.printWorkflowResult)({
+            logger,
+            command: "workflow.advance",
+            envName,
+            result,
+            humanLines: [result.message ?? ""],
+        });
+        return result;
+    }
+    if (command.duplicateMatches > 1) {
+        logger.warn(`Workflow '${wf.workflowName}' has ${command.duplicateMatches} commands named '${options.command}' at this state — using the first match (${command.commandId}). Disambiguate if this is wrong.`);
+    }
+    if (options.whatIf) {
+        const result = {
+            itemId: wf.itemId,
+            path: wf.path,
+            workflowName: wf.workflowName,
+            fromState: wf.stateName,
+            toState: null,
+            commandRequested: options.command,
+            commandUsed: command.displayName,
+            status: "what-if",
+            message: `Would execute '${command.displayName}' (${command.commandId}) on ${wf.path ?? wf.itemId}.`,
+        };
+        (0, shared_1.printWorkflowResult)({
+            logger,
+            command: "workflow.advance",
+            envName,
+            result,
+            humanLines: [result.message ?? ""],
+        });
+        return result;
+    }
+    try {
+        const exec = await client.executeWorkflowCommand({
+            commandId: command.commandId,
+            itemId: (0, shared_1.dashifyItemId)(wf.itemId),
+            ...(options.comments !== undefined && { comments: options.comments }),
+        });
+        const result = {
+            itemId: wf.itemId,
+            path: wf.path,
+            workflowName: wf.workflowName,
+            fromState: wf.stateName,
+            toState: exec.nextStateId,
+            commandRequested: options.command,
+            commandUsed: command.displayName,
+            status: exec.successful ? "advanced" : "failed",
+            ...(exec.successful
+                ? {}
+                : { message: exec.message ?? "Workflow command returned successful=false." }),
+        };
+        (0, shared_1.printWorkflowResult)({
+            logger,
+            command: "workflow.advance",
+            envName,
+            result,
+            humanLines: [
+                exec.successful
+                    ? `Advanced ${wf.path ?? wf.itemId} via '${command.displayName}' — next state: ${exec.nextStateId ?? "(unspecified)"}.`
+                    : `Failed to advance ${wf.path ?? wf.itemId}: ${result.message}`,
+            ],
+        });
+        return result;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const result = {
+            itemId: wf.itemId,
+            path: wf.path,
+            workflowName: wf.workflowName,
+            fromState: wf.stateName,
+            toState: null,
+            commandRequested: options.command,
+            commandUsed: command.displayName,
+            status: "failed",
+            message,
+        };
+        (0, shared_1.printWorkflowResult)({
+            logger,
+            command: "workflow.advance",
+            envName,
+            result,
+            humanLines: [`Failed to advance ${wf.path ?? wf.itemId}: ${message}`],
+        });
+        return result;
+    }
+};
+exports.runWorkflowAdvance = runWorkflowAdvance;

package/dist/workflow/tasks/apply.d.ts

@@ -0,0 +1,47 @@
+import { type WorkflowTaskOptions } from "./shared";
+export interface WorkflowApplyOptions extends WorkflowTaskOptions {
+    /** Item GUID or content-tree path to attach the workflow to. Required. */
+    item: string;
+    /**
+     * Workflow GUID, content-tree path, or display/item name. Required.
+     * Same resolution as `runWorkflowInspect`: GUID → direct, path →
+     * lookup, free text → name match against `listWorkflowDefinitions`.
+     */
+    workflow: string;
+    /**
+     * Override the state to land on. Defaults to the workflow's
+     * `__Initial state`. Pass either a state GUID or a state name (e.g.
+     * "Draft") to start the item somewhere other than initial.
+     */
+    state?: string;
+    /** Plan-only — don't issue the field write. */
+    whatIf?: boolean;
+    /** Per-invocation write gate override. */
+    allowWrite?: boolean;
+}
+export type WorkflowApplyStatus = "applied" | "what-if" | "failed" | "skipped-already-attached" | "skipped-workflow-not-found" | "skipped-state-not-found";
+export interface WorkflowApplyResult {
+    itemId: string | null;
+    path: string | null;
+    workflowItemId: string | null;
+    workflowName: string | null;
+    stateItemId: string | null;
+    stateName: string | null;
+    status: WorkflowApplyStatus;
+    message?: string;
+}
+/**
+ * Attach a workflow to an item — sets the item's `__Workflow` and
+ * `__Workflow state` fields directly via `updateItem`. Bypasses the
+ * workflow engine; no submit/validation actions fire.
+ *
+ * Useful when content was authored before the workflow existed, or
+ * when an item was orphaned by a workflow rename. For new items
+ * created via recipe / CMS UX, attach the workflow via Standard
+ * Values (`__Default workflow` field) on the template instead.
+ *
+ * The `workflow` ref accepts any of: workflow GUID, content-tree path,
+ * or display/item name (resolved against `listWorkflowDefinitions`).
+ * Same resolver as `workflow_inspect verb=inspect`.
+ */
+export declare const runWorkflowApply: (options: WorkflowApplyOptions) => Promise<WorkflowApplyResult>;

package/dist/workflow/tasks/apply.js

@@ -0,0 +1,193 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runWorkflowApply = void 0;
+const allow_write_1 = require("../../policy/allow-write");
+const errors_1 = require("../../shared/errors");
+const shared_1 = require("./shared");
+/**
+ * Attach a workflow to an item — sets the item's `__Workflow` and
+ * `__Workflow state` fields directly via `updateItem`. Bypasses the
+ * workflow engine; no submit/validation actions fire.
+ *
+ * Useful when content was authored before the workflow existed, or
+ * when an item was orphaned by a workflow rename. For new items
+ * created via recipe / CMS UX, attach the workflow via Standard
+ * Values (`__Default workflow` field) on the template instead.
+ *
+ * The `workflow` ref accepts any of: workflow GUID, content-tree path,
+ * or display/item name (resolved against `listWorkflowDefinitions`).
+ * Same resolver as `workflow_inspect verb=inspect`.
+ */
+const runWorkflowApply = async (options) => {
+    const logger = (0, shared_1.toLogger)(options);
+    if (!options.workflow) {
+        throw (0, errors_1.createScaiError)("--workflow is required.", "INPUT_INVALID");
+    }
+    const itemSelector = (0, shared_1.parseItemReference)(options.item);
+    const { envName, root, client } = (0, shared_1.resolveWorkflowTenant)(options);
+    if (!options.whatIf) {
+        (0, allow_write_1.ensureAllowWrite)(root, envName, options.allowWrite);
+    }
+    else if (!logger.isJson()) {
+        logger.info("What-if mode — no field write will happen.", "yellow");
+    }
+    // Resolve workflow ref → workflow definition detail.
+    const wfRef = options.workflow.trim();
+    const workflowDetail = await (0, shared_1.resolveWorkflowRef)(client, wfRef);
+    if (!workflowDetail) {
+        const result = {
+            itemId: null,
+            path: itemSelector.path ?? null,
+            workflowItemId: null,
+            workflowName: null,
+            stateItemId: null,
+            stateName: null,
+            status: "skipped-workflow-not-found",
+            message: `Workflow '${wfRef}' did not resolve to a Workflow-templated item.`,
+        };
+        (0, shared_1.printWorkflowResult)({
+            logger,
+            command: "workflow.apply",
+            envName,
+            result,
+            humanLines: [result.message ?? ""],
+        });
+        return result;
+    }
+    // Resolve target state. Default to initial state.
+    let targetStateId = null;
+    let targetStateName = null;
+    if (options.state) {
+        const stateRef = options.state.trim();
+        const match = (0, shared_1.resolveWorkflowState)(workflowDetail, stateRef);
+        if (match) {
+            targetStateId = match.itemId;
+            targetStateName = match.name;
+        }
+        if (!targetStateId) {
+            const result = {
+                itemId: null,
+                path: itemSelector.path ?? null,
+                workflowItemId: workflowDetail.itemId,
+                workflowName: workflowDetail.displayName ?? workflowDetail.name,
+                stateItemId: null,
+                stateName: null,
+                status: "skipped-state-not-found",
+                message: `Workflow '${workflowDetail.displayName ?? workflowDetail.name}' has no state named or matching '${stateRef}'.`,
+            };
+            (0, shared_1.printWorkflowResult)({
+                logger,
+                command: "workflow.apply",
+                envName,
+                result,
+                humanLines: [result.message ?? ""],
+            });
+            return result;
+        }
+    }
+    else {
+        const initialStateId = await client.getWorkflowInitialStateId(workflowDetail.itemId);
+        if (!initialStateId) {
+            throw (0, errors_1.createScaiError)(`Workflow '${workflowDetail.displayName ?? workflowDetail.name}' has no __Initial state set.`, "UNKNOWN");
+        }
+        targetStateId = initialStateId;
+        const initial = workflowDetail.states.find((s) => s.itemId.replace(/[{}]/g, "").toLowerCase() ===
+            initialStateId.replace(/[{}]/g, "").toLowerCase());
+        targetStateName = initial?.displayName ?? initial?.name ?? null;
+    }
+    // Idempotency: item already attached to this workflow + state.
+    const existingWf = await client.getItemWorkflow(itemSelector);
+    if (existingWf &&
+        existingWf.workflowId &&
+        existingWf.workflowId.replace(/[{}]/g, "").toLowerCase() ===
+            workflowDetail.itemId.replace(/[{}]/g, "").toLowerCase() &&
+        existingWf.stateId &&
+        existingWf.stateId.replace(/[{}]/g, "").toLowerCase() ===
+            (targetStateId ?? "").replace(/[{}]/g, "").toLowerCase()) {
+        const result = {
+            itemId: existingWf.itemId,
+            path: existingWf.path,
+            workflowItemId: workflowDetail.itemId,
+            workflowName: workflowDetail.displayName ?? workflowDetail.name,
+            stateItemId: targetStateId,
+            stateName: targetStateName,
+            status: "skipped-already-attached",
+            message: `Item already attached to workflow '${workflowDetail.displayName ?? workflowDetail.name}' at state '${targetStateName ?? "?"}'.`,
+        };
+        (0, shared_1.printWorkflowResult)({
+            logger,
+            command: "workflow.apply",
+            envName,
+            result,
+            humanLines: [result.message ?? ""],
+        });
+        return result;
+    }
+    if (options.whatIf) {
+        const result = {
+            itemId: existingWf?.itemId ?? null,
+            path: existingWf?.path ?? itemSelector.path ?? null,
+            workflowItemId: workflowDetail.itemId,
+            workflowName: workflowDetail.displayName ?? workflowDetail.name,
+            stateItemId: targetStateId,
+            stateName: targetStateName,
+            status: "what-if",
+            message: `Would attach ${itemSelector.path ?? itemSelector.itemId} to workflow '${workflowDetail.displayName ?? workflowDetail.name}' at state '${targetStateName ?? "?"}'.`,
+        };
+        (0, shared_1.printWorkflowResult)({
+            logger,
+            command: "workflow.apply",
+            envName,
+            result,
+            humanLines: [result.message ?? ""],
+        });
+        return result;
+    }
+    try {
+        await client.setItemWorkflowState({
+            ...(itemSelector.itemId ? { itemId: itemSelector.itemId } : { path: itemSelector.path }),
+            workflowId: workflowDetail.itemId,
+            stateId: targetStateId ?? undefined,
+        });
+        const result = {
+            itemId: existingWf?.itemId ?? itemSelector.itemId ?? null,
+            path: existingWf?.path ?? itemSelector.path ?? null,
+            workflowItemId: workflowDetail.itemId,
+            workflowName: workflowDetail.displayName ?? workflowDetail.name,
+            stateItemId: targetStateId,
+            stateName: targetStateName,
+            status: "applied",
+            message: `Attached ${itemSelector.path ?? itemSelector.itemId} to workflow '${workflowDetail.displayName ?? workflowDetail.name}' at state '${targetStateName ?? "?"}'.`,
+        };
+        (0, shared_1.printWorkflowResult)({
+            logger,
+            command: "workflow.apply",
+            envName,
+            result,
+            humanLines: [result.message ?? ""],
+        });
+        return result;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const result = {
+            itemId: existingWf?.itemId ?? itemSelector.itemId ?? null,
+            path: existingWf?.path ?? itemSelector.path ?? null,
+            workflowItemId: workflowDetail.itemId,
+            workflowName: workflowDetail.displayName ?? workflowDetail.name,
+            stateItemId: null,
+            stateName: null,
+            status: "failed",
+            message,
+        };
+        (0, shared_1.printWorkflowResult)({
+            logger,
+            command: "workflow.apply",
+            envName,
+            result,
+            humanLines: [`Failed to apply workflow: ${message}`],
+        });
+        return result;
+    }
+};
+exports.runWorkflowApply = runWorkflowApply;

package/dist/workflow/tasks/assigned.d.ts

@@ -0,0 +1,33 @@
+import type { AssignedItemSummary } from "../api/client";
+import { type WorkflowTaskOptions } from "./shared";
+export interface WorkflowAssignedOptions extends WorkflowTaskOptions {
+    /** Workflow state GUID — the item ID of the State item. Required. */
+    state: string;
+    /** Override the search index. Defaults to `sitecore_master_index`. */
+    index?: string;
+    /**
+     * Override the search field. Defaults to `__workflow state`. Some
+     * tenants index the field as `__workflow_state` instead — use this
+     * to switch when the default returns no hits.
+     */
+    field?: string;
+    /** Page size for the search backend. Defaults to 100. */
+    pageSize?: number;
+    /** Cap on items returned. Defaults to 500. */
+    limit?: number;
+}
+export interface WorkflowAssignedResult {
+    stateId: string;
+    items: AssignedItemSummary[];
+}
+/**
+ * Find items currently in the given workflow state — the CLI's "workbox"
+ * equivalent. Backed by the Sitecore search index over the
+ * `__workflow state` field.
+ *
+ * On tenants where the search field is indexed under a different name
+ * (e.g. `__workflow_state`), supply `--field`. If results are still
+ * empty, run with `--trace` and verify the field name against your
+ * tenant's index schema.
+ */
+export declare const runWorkflowAssigned: (options: WorkflowAssignedOptions) => Promise<WorkflowAssignedResult>;

package/dist/workflow/tasks/assigned.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runWorkflowAssigned = void 0;
+const errors_1 = require("../../shared/errors");
+const shared_1 = require("./shared");
+/**
+ * Find items currently in the given workflow state — the CLI's "workbox"
+ * equivalent. Backed by the Sitecore search index over the
+ * `__workflow state` field.
+ *
+ * On tenants where the search field is indexed under a different name
+ * (e.g. `__workflow_state`), supply `--field`. If results are still
+ * empty, run with `--trace` and verify the field name against your
+ * tenant's index schema.
+ */
+const runWorkflowAssigned = async (options) => {
+    const logger = (0, shared_1.toLogger)(options);
+    if (!options.state) {
+        throw (0, errors_1.createScaiError)("--state is required.", "INPUT_INVALID");
+    }
+    const { envName, client } = (0, shared_1.resolveWorkflowTenant)(options);
+    const items = await client.searchItemsByWorkflowState({
+        stateId: options.state,
+        ...(options.index !== undefined && { index: options.index }),
+        ...(options.field !== undefined && { field: options.field }),
+        ...(options.pageSize !== undefined && { pageSize: options.pageSize }),
+        ...(options.limit !== undefined && { maxItems: options.limit }),
+    });
+    const lines = items.length > 0
+        ? items.map((i) => `${i.path} (${i.templateName ?? "?"})${i.updatedDate ? ` — updated ${i.updatedDate}` : ""}`)
+        : [`No items found in state ${options.state}.`];
+    (0, shared_1.printWorkflowResult)({
+        logger,
+        command: "workflow.assigned",
+        envName,
+        result: { stateId: options.state, items },
+        humanLines: lines,
+    });
+    return { stateId: options.state, items };
+};
+exports.runWorkflowAssigned = runWorkflowAssigned;