@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/content/api/version-fields.js

@@ -0,0 +1,193 @@
+"use strict";
+/**
+ * Version-level field read/write helpers for the Authoring GraphQL
+ * surface.
+ *
+ * Used by `scai content version *` and `scai content publish unpublish` to
+ * read/write the three publish-state fields Sitecore exposes per
+ * version:
+ *
+ *   - `__Never publish` (boolean — stored as "1" / "")
+ *   - `__Valid from`    (datetime — ISO 8601 string)
+ *   - `__Valid to`      (datetime — ISO 8601 string)
+ *
+ * Distinct from `src/recipe/api/authoring-client.ts:updateItem` for
+ * two reasons:
+ *
+ *   1. Recipe pushes write **item-level** fields (no version/language
+ *      qualifier on the mutation input) — fine for shared fields and
+ *      "the only version" usage, but never targets a specific version.
+ *      The publish-state fields are versioned, so the mutation needs
+ *      `language` and `version` on the input.
+ *   2. Recipe pushes go through `dispatchMutation` with rollback,
+ *      retries, and idempotent-create fallback. The content-state
+ *      verbs are explicit single-version writes with audit-log gating;
+ *      they don't want the recipe push path's behavior.
+ *
+ * Mutation shape verified against the Authoring GraphQL schema
+ * (XM Cloud, 2026-05-14) — `UpdateItemInput` accepts `language` /
+ * `version` alongside `itemId` and `fields`, and the version-scoped
+ * write only touches the targeted version.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveSinglePathToId = exports.writeVersionFields = exports.readVersionFields = exports.findField = exports.formatBoolean = exports.parseBoolean = exports.PUBLISH_STATE_FIELDS = exports.FIELD_VALID_TO = exports.FIELD_VALID_FROM = exports.FIELD_NEVER_PUBLISH = exports.SITECORE_BOOLEAN_FALSE = exports.SITECORE_BOOLEAN_TRUE = void 0;
+const graphql_1 = require("../../recipe/api/graphql");
+const errors_1 = require("../../shared/errors");
+/**
+ * Sitecore boolean fields are stored as a string: `"1"` for true and
+ * an empty string for false. This is the wire form `updateItem`
+ * accepts and `getItem` returns. Anyone consuming `__Never publish`
+ * from a remote read should canonicalize via {@link parseBoolean}.
+ */
+exports.SITECORE_BOOLEAN_TRUE = "1";
+exports.SITECORE_BOOLEAN_FALSE = "";
+exports.FIELD_NEVER_PUBLISH = "__Never publish";
+exports.FIELD_VALID_FROM = "__Valid from";
+exports.FIELD_VALID_TO = "__Valid to";
+/**
+ * The set of publish-state fields scai reads/writes per version. Kept
+ * as a tuple so the type system can narrow on field names elsewhere.
+ */
+exports.PUBLISH_STATE_FIELDS = [
+    exports.FIELD_NEVER_PUBLISH,
+    exports.FIELD_VALID_FROM,
+    exports.FIELD_VALID_TO,
+];
+const READ_QUERY = `
+query($itemId: ID!, $language: String!, $version: Int) {
+  item(where: { itemId: $itemId }) {
+    itemId
+    name
+    path
+    version(language: $language, version: $version) {
+      version
+      language { name }
+      fields(ownFields: false) {
+        nodes {
+          name
+          value
+        }
+      }
+    }
+  }
+}`;
+const UPDATE_MUTATION = `
+mutation($itemId: ID!, $language: String!, $version: Int!, $fields: [FieldValueInput!]!) {
+  updateItem(input: {
+    itemId: $itemId
+    language: $language
+    version: $version
+    fields: $fields
+  }) {
+    item { itemId }
+  }
+}`;
+/**
+ * Parse Sitecore's wire form for booleans. Returns:
+ *   - `true`  for "1"
+ *   - `false` for "" or "0" or undefined
+ *   - the raw value's truthiness for anything else (defensive)
+ */
+const parseBoolean = (raw) => {
+    if (raw === exports.SITECORE_BOOLEAN_TRUE)
+        return true;
+    if (raw === exports.SITECORE_BOOLEAN_FALSE || raw == null || raw === "0")
+        return false;
+    return Boolean(raw);
+};
+exports.parseBoolean = parseBoolean;
+/**
+ * Format a boolean for the wire ("1" / "").
+ */
+const formatBoolean = (value) => value ? exports.SITECORE_BOOLEAN_TRUE : exports.SITECORE_BOOLEAN_FALSE;
+exports.formatBoolean = formatBoolean;
+/**
+ * Look up a single field on a snapshot. Returns the stored value or
+ * `null` when the field isn't present on the version (Sitecore treats
+ * absent versioned fields as effectively empty; we surface that
+ * distinction to the audit trail as `null` so an operator can tell
+ * apart "was explicitly empty" from "wasn't there at all").
+ */
+const findField = (snapshot, name) => {
+    const match = snapshot.fields.find((f) => f.name === name);
+    return match ? match.value : null;
+};
+exports.findField = findField;
+/**
+ * Read the version-state fields for `(itemId, language, version?)`.
+ * Throws `INPUT_INVALID` if the item or the requested version doesn't
+ * exist — the caller is responsible for path → itemId resolution
+ * before invoking this helper (use the existing
+ * `resolveItemPathsToIds`).
+ */
+const readVersionFields = async (environment, options) => {
+    const data = await (0, graphql_1.runAuthoringGraphQL)(environment, READ_QUERY, {
+        itemId: options.itemId,
+        language: options.language,
+        version: options.version ?? null,
+    }, options.request);
+    if (!data.item) {
+        throw (0, errors_1.createScaiError)(`Item '${options.itemId}' not found in env content tree.`, "INPUT_INVALID", {
+            hint: "Verify the itemId is correct and the authenticated client has read access.",
+        });
+    }
+    if (!data.item.version) {
+        throw (0, errors_1.createScaiError)(`Item '${options.itemId}' has no version for language '${options.language}'${options.version !== undefined ? ` (version ${options.version})` : ""}.`, "INPUT_INVALID", {
+            hint: "Pass a different --language, or omit --version to target the latest. Operators creating a fresh version need to do so via the Sitecore Authoring UI first.",
+        });
+    }
+    return {
+        itemId: data.item.itemId,
+        name: data.item.name,
+        path: data.item.path,
+        language: data.item.version.language.name,
+        version: data.item.version.version,
+        fields: data.item.version.fields.nodes.map((node) => ({
+            name: node.name,
+            value: node.value,
+        })),
+    };
+};
+exports.readVersionFields = readVersionFields;
+/**
+ * Write `fields` to the version at `(itemId, language, version)`.
+ *
+ * Disables retries — the Authoring GraphQL endpoint has no
+ * idempotency-key mechanism, so retrying a write that already
+ * succeeded server-side would double-apply. Same reasoning the recipe
+ * runtime uses for `writeRequest` (see `authoring-client.ts`).
+ */
+const writeVersionFields = async (environment, options) => {
+    if (options.fields.length === 0) {
+        return;
+    }
+    await (0, graphql_1.runAuthoringGraphQL)(environment, UPDATE_MUTATION, {
+        itemId: options.itemId,
+        language: options.language,
+        version: options.version,
+        fields: options.fields.map((f) => ({ name: f.name, value: f.value })),
+    }, {
+        ...(options.request ?? {}),
+        retry: { maxAttempts: 1, ...(options.request?.retry ?? {}) },
+    });
+};
+exports.writeVersionFields = writeVersionFields;
+/**
+ * Resolve a content-tree path to its itemId via the Authoring API.
+ * Single-path convenience around the read query — the publishing
+ * surface's `resolveItemPathsToIds` is batched + multi-path; for the
+ * `content version *` verbs (one item at a time) the single-path
+ * shape is clearer.
+ *
+ * Returns the canonical itemId without curly braces.
+ */
+const resolveSinglePathToId = async (environment, path, request) => {
+    const data = await (0, graphql_1.runAuthoringGraphQL)(environment, `query($path: String!) { item(where: { path: $path }) { itemId } }`, { path }, request);
+    if (!data.item?.itemId) {
+        throw (0, errors_1.createScaiError)(`Path '${path}' did not resolve to an item.`, "INPUT_INVALID", {
+            hint: "Verify the path exists in the env's content tree and the authenticated client has read access.",
+        });
+    }
+    return data.item.itemId;
+};
+exports.resolveSinglePathToId = resolveSinglePathToId;

package/dist/content/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Public entry for `@sitecoreai-labs/sitecoreai-cli/content`.
+ *
+ * Content-state controls — per-version mutations on Sitecore's
+ * publish-state fields (`__Never publish`, `__Valid from`, `__Valid
+ * to`) and the read-only `inspect` helper. Lives separate from
+ * `./publishing` because these are CM-side mutations that don't (by
+ * themselves) call the Publishing API — operators run `scai content publish
+ * item` after their content-state changes.
+ */
+export { FIELD_NEVER_PUBLISH, FIELD_VALID_FROM, FIELD_VALID_TO, PUBLISH_STATE_FIELDS, SITECORE_BOOLEAN_FALSE, SITECORE_BOOLEAN_TRUE, findField, formatBoolean, parseBoolean, readVersionFields, resolveSinglePathToId, writeVersionFields, type PublishStateFieldName, type ReadVersionFieldsOptions, type VersionFieldsSnapshot, type VersionFieldValue, type WriteVersionFieldsOptions, } from "./api/version-fields";
+export { resolveTargetItemId } from "./tasks/shared";
+export { runContentVersionSetNeverPublish, type RunContentVersionSetNeverPublishOptions, } from "./tasks/version-never-publish";
+export { runContentVersionSetValidity, type RunContentVersionSetValidityOptions, } from "./tasks/version-validity";
+export { runContentVersionInspect, type RunContentVersionInspectOptions, } from "./tasks/version-inspect";

package/dist/content/index.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * Public entry for `@sitecoreai-labs/sitecoreai-cli/content`.
+ *
+ * Content-state controls — per-version mutations on Sitecore's
+ * publish-state fields (`__Never publish`, `__Valid from`, `__Valid
+ * to`) and the read-only `inspect` helper. Lives separate from
+ * `./publishing` because these are CM-side mutations that don't (by
+ * themselves) call the Publishing API — operators run `scai content publish
+ * item` after their content-state changes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runContentVersionInspect = exports.runContentVersionSetValidity = exports.runContentVersionSetNeverPublish = exports.resolveTargetItemId = exports.writeVersionFields = exports.resolveSinglePathToId = exports.readVersionFields = exports.parseBoolean = exports.formatBoolean = exports.findField = exports.SITECORE_BOOLEAN_TRUE = exports.SITECORE_BOOLEAN_FALSE = exports.PUBLISH_STATE_FIELDS = exports.FIELD_VALID_TO = exports.FIELD_VALID_FROM = exports.FIELD_NEVER_PUBLISH = void 0;
+// --- Authoring GraphQL helpers ----------------------------------------
+var version_fields_1 = require("./api/version-fields");
+Object.defineProperty(exports, "FIELD_NEVER_PUBLISH", { enumerable: true, get: function () { return version_fields_1.FIELD_NEVER_PUBLISH; } });
+Object.defineProperty(exports, "FIELD_VALID_FROM", { enumerable: true, get: function () { return version_fields_1.FIELD_VALID_FROM; } });
+Object.defineProperty(exports, "FIELD_VALID_TO", { enumerable: true, get: function () { return version_fields_1.FIELD_VALID_TO; } });
+Object.defineProperty(exports, "PUBLISH_STATE_FIELDS", { enumerable: true, get: function () { return version_fields_1.PUBLISH_STATE_FIELDS; } });
+Object.defineProperty(exports, "SITECORE_BOOLEAN_FALSE", { enumerable: true, get: function () { return version_fields_1.SITECORE_BOOLEAN_FALSE; } });
+Object.defineProperty(exports, "SITECORE_BOOLEAN_TRUE", { enumerable: true, get: function () { return version_fields_1.SITECORE_BOOLEAN_TRUE; } });
+Object.defineProperty(exports, "findField", { enumerable: true, get: function () { return version_fields_1.findField; } });
+Object.defineProperty(exports, "formatBoolean", { enumerable: true, get: function () { return version_fields_1.formatBoolean; } });
+Object.defineProperty(exports, "parseBoolean", { enumerable: true, get: function () { return version_fields_1.parseBoolean; } });
+Object.defineProperty(exports, "readVersionFields", { enumerable: true, get: function () { return version_fields_1.readVersionFields; } });
+Object.defineProperty(exports, "resolveSinglePathToId", { enumerable: true, get: function () { return version_fields_1.resolveSinglePathToId; } });
+Object.defineProperty(exports, "writeVersionFields", { enumerable: true, get: function () { return version_fields_1.writeVersionFields; } });
+// --- Target resolution --------------------------------------------------
+// `resolveTargetItemId` turns an `--item-id` *or* `--path` into a
+// canonical item id — the presentation-free target-resolution step the
+// content-version runners share.
+var shared_1 = require("./tasks/shared");
+Object.defineProperty(exports, "resolveTargetItemId", { enumerable: true, get: function () { return shared_1.resolveTargetItemId; } });
+// --- Task runners -------------------------------------------------------
+var version_never_publish_1 = require("./tasks/version-never-publish");
+Object.defineProperty(exports, "runContentVersionSetNeverPublish", { enumerable: true, get: function () { return version_never_publish_1.runContentVersionSetNeverPublish; } });
+var version_validity_1 = require("./tasks/version-validity");
+Object.defineProperty(exports, "runContentVersionSetValidity", { enumerable: true, get: function () { return version_validity_1.runContentVersionSetValidity; } });
+var version_inspect_1 = require("./tasks/version-inspect");
+Object.defineProperty(exports, "runContentVersionInspect", { enumerable: true, get: function () { return version_inspect_1.runContentVersionInspect; } });

package/dist/content/tasks/shared.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Shared scaffolding for `scai content version *` tasks.
+ *
+ * Each verb (set-validity, set-never-publish, inspect) follows the
+ * same pattern: resolve `(itemId or path, language, version?)` → load
+ * the current version snapshot → apply the verb-specific logic →
+ * audit. The boilerplate around env resolution, path → id resolution,
+ * tier gating and the dry-run / `--allow-write` / `--confirm-token`
+ * dance is identical, so it lives here.
+ */
+import type { EnvironmentConfiguration } from "../../config/types";
+import { Logger } from "../../shared/logger";
+import { computeScopeHash } from "../../shared/publish-consent";
+import type { PublishAuditScope } from "../../shared/publish-audit";
+import { type VersionFieldsSnapshot } from "../../content/api/version-fields";
+export interface CommonContentVersionOptions {
+    config?: string;
+    environmentName?: string;
+    itemId?: string;
+    path?: string;
+    language: string;
+    /** Specific version (1-indexed). Undefined → latest. */
+    version?: number;
+    whatIf?: boolean;
+    allowWrite?: boolean;
+    confirmToken?: string;
+    yes?: boolean;
+    verbose?: boolean;
+    trace?: boolean;
+    quiet?: boolean;
+    json?: boolean;
+    logFile?: string;
+    nonInteractive?: boolean;
+}
+export declare const buildLogger: (options: CommonContentVersionOptions) => Logger;
+/**
+ * Resolve `--item-id` or `--path` into a canonical itemId. Errors if
+ * neither (or both) are supplied — the verbs are single-item by
+ * design, so an unambiguous target is a pre-condition.
+ */
+export declare const resolveTargetItemId: (environment: EnvironmentConfiguration, options: {
+    itemId?: string;
+    path?: string;
+}) => Promise<string>;
+/**
+ * Read the current version snapshot. Resolves the request-time
+ * "latest" (`version` undefined) into the concrete version number on
+ * the returned snapshot, so subsequent writes can pin the exact
+ * version they intended. Audit log carries the concrete version for
+ * the same reason.
+ */
+export declare const loadVersionSnapshot: (environment: EnvironmentConfiguration, itemId: string, language: string, version?: number) => Promise<VersionFieldsSnapshot>;
+export interface SafetyGateInput {
+    envName: string;
+    environment: EnvironmentConfiguration;
+    scope: PublishAuditScope;
+    /** Friendly label printed in dry-run / prompt output ("set-validity",
+     *  "set-never-publish", etc.). */
+    operationLabel: string;
+    options: Pick<CommonContentVersionOptions, "allowWrite" | "whatIf" | "confirmToken" | "yes" | "nonInteractive">;
+    logger: Logger;
+    /** Optional renderer for any verb-specific dry-run lines (e.g. "would
+     *  set __Never publish: true"). Invoked before the scope-token
+     *  printout. */
+    describeChange?: () => void;
+}
+export type SafetyGateResult = {
+    proceed: false;
+} | {
+    proceed: true;
+    whatIf: false;
+};
+/**
+ * Apply the standard dry-run / allow-write / confirm-token / prompt
+ * cascade. Returns `proceed: true` only when the caller should
+ * actually issue the write. Mirrors the layering used in
+ * `runPublishItem`.
+ *
+ * The `describeChange` hook lets each verb print its specific intended
+ * mutation (e.g. "would write `__Never publish` from `false` → `true`")
+ * before the shared "Scope token" footer.
+ */
+export declare const runSafetyGate: (input: SafetyGateInput) => Promise<SafetyGateResult>;
+/** Re-exported so verb tasks don't have to know which helper module
+ *  hosts the canonical hash function. */
+export { computeScopeHash };

package/dist/content/tasks/shared.js

@@ -0,0 +1,130 @@
+"use strict";
+/**
+ * Shared scaffolding for `scai content version *` tasks.
+ *
+ * Each verb (set-validity, set-never-publish, inspect) follows the
+ * same pattern: resolve `(itemId or path, language, version?)` → load
+ * the current version snapshot → apply the verb-specific logic →
+ * audit. The boilerplate around env resolution, path → id resolution,
+ * tier gating and the dry-run / `--allow-write` / `--confirm-token`
+ * dance is identical, so it lives here.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeScopeHash = exports.runSafetyGate = exports.loadVersionSnapshot = exports.resolveTargetItemId = exports.buildLogger = void 0;
+const logger_1 = require("../../shared/logger");
+const errors_1 = require("../../shared/errors");
+const prompt_1 = require("../../shared/prompt");
+const publish_consent_1 = require("../../shared/publish-consent");
+Object.defineProperty(exports, "computeScopeHash", { enumerable: true, get: function () { return publish_consent_1.computeScopeHash; } });
+const env_tier_1 = require("../../shared/env-tier");
+const version_fields_1 = require("../../content/api/version-fields");
+const buildLogger = (options) => new logger_1.Logger(Boolean(options.verbose), Boolean(options.trace), Boolean(options.json), Boolean(options.quiet), options.logFile ?? process.env.SITECOREAI_LOG_FILE);
+exports.buildLogger = buildLogger;
+/**
+ * Resolve `--item-id` or `--path` into a canonical itemId. Errors if
+ * neither (or both) are supplied — the verbs are single-item by
+ * design, so an unambiguous target is a pre-condition.
+ */
+const resolveTargetItemId = async (environment, options) => {
+    if (options.itemId && options.path) {
+        throw (0, errors_1.createScaiError)("Pass either --item-id or --path, not both.", "INPUT_INVALID");
+    }
+    if (options.itemId) {
+        return options.itemId.replace(/[{}]/g, "");
+    }
+    if (options.path) {
+        return (0, version_fields_1.resolveSinglePathToId)(environment, options.path);
+    }
+    throw (0, errors_1.createScaiError)("Pass --item-id <guid> or --path <path> to identify the target item.", "INPUT_INVALID");
+};
+exports.resolveTargetItemId = resolveTargetItemId;
+/**
+ * Read the current version snapshot. Resolves the request-time
+ * "latest" (`version` undefined) into the concrete version number on
+ * the returned snapshot, so subsequent writes can pin the exact
+ * version they intended. Audit log carries the concrete version for
+ * the same reason.
+ */
+const loadVersionSnapshot = async (environment, itemId, language, version) => (0, version_fields_1.readVersionFields)(environment, { itemId, language, version });
+exports.loadVersionSnapshot = loadVersionSnapshot;
+const printScope = (logger, scope, label) => {
+    logger.info(`Environment:   ${scope.envName}`, "cyan");
+    if (scope.resolvedTenantId) {
+        logger.info(`Tenant:        ${scope.resolvedTenantId}`, "gray");
+    }
+    logger.info(`Operation:     ${label}`, "gray");
+    if (scope.itemIds && scope.itemIds.length > 0) {
+        logger.info(`Item ID:       ${scope.itemIds[0]}`, "gray");
+    }
+    if (scope.path) {
+        logger.info(`Path:          ${scope.path}`, "gray");
+    }
+    if (scope.languages && scope.languages.length > 0) {
+        logger.info(`Language:      ${scope.languages[0]}`, "gray");
+    }
+    if (scope.version !== undefined) {
+        logger.info(`Version:       ${scope.version}`, "gray");
+    }
+};
+/**
+ * Apply the standard dry-run / allow-write / confirm-token / prompt
+ * cascade. Returns `proceed: true` only when the caller should
+ * actually issue the write. Mirrors the layering used in
+ * `runPublishItem`.
+ *
+ * The `describeChange` hook lets each verb print its specific intended
+ * mutation (e.g. "would write `__Never publish` from `false` → `true`")
+ * before the shared "Scope token" footer.
+ */
+const runSafetyGate = async (input) => {
+    const { envName, environment, scope, operationLabel, options, logger } = input;
+    const whatIf = options.allowWrite ? Boolean(options.whatIf) : true;
+    const productionTier = (0, env_tier_1.isProductionTier)(environment);
+    if (whatIf) {
+        logger.warn(`What-if: would apply ${operationLabel} in env '${envName}'.`, "yellow");
+        printScope(logger, scope, operationLabel);
+        if (input.describeChange) {
+            input.describeChange();
+        }
+        const token = (0, publish_consent_1.mintScopeToken)(scope);
+        logger.info("", "gray");
+        if (productionTier) {
+            logger.info(`Production-tier env. Real call requires --allow-write AND --confirm-token.`, "yellow");
+        }
+        logger.info(`Scope token (TTL ${publish_consent_1.SCOPE_TOKEN_TTL_MS / 1000}s):`, "gray");
+        process.stdout.write(`${token}\n`);
+        logger.info("", "gray");
+        logger.info(`To execute: rerun with --allow-write${productionTier ? ` --confirm-token ${token}` : ""}`, "gray");
+        return { proceed: false };
+    }
+    if (productionTier) {
+        if (!options.confirmToken) {
+            throw (0, errors_1.createScaiError)(`Production-tier env '${envName}' requires --confirm-token.`, "INPUT_INVALID", {
+                hint: "Run the same command without --allow-write to mint a scope token, then pass it back as --confirm-token <token>.",
+            });
+        }
+        const verification = (0, publish_consent_1.verifyScopeToken)(options.confirmToken, scope);
+        if (!verification.ok) {
+            throw (0, errors_1.createScaiError)(`Scope token rejected (${verification.reason}).`, "INPUT_INVALID", {
+                hint: "Re-run the dry-run to mint a fresh token; the scope or env may have changed since the token was issued.",
+            });
+        }
+    }
+    else if (!options.yes) {
+        if (options.nonInteractive) {
+            throw (0, errors_1.createScaiError)("Non-interactive mode requires --yes (or --confirm-token on prod envs).", "INPUT_INVALID");
+        }
+        logger.info(`About to apply ${operationLabel} in env '${envName}'.`, "yellow");
+        printScope(logger, scope, operationLabel);
+        if (input.describeChange) {
+            input.describeChange();
+        }
+        const ok = await (0, prompt_1.promptConfirm)(`Proceed with ${operationLabel}?`, false);
+        if (!ok) {
+            logger.info("Aborted.", "yellow");
+            return { proceed: false };
+        }
+    }
+    return { proceed: true, whatIf: false };
+};
+exports.runSafetyGate = runSafetyGate;

package/dist/content/tasks/version-inspect.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `scai content version inspect` — print the publish-state fields for
+ * an item version. Read-only; does NOT write the audit log (the
+ * audit log records mutations, not reads — keep the trail focused).
+ *
+ * The output groups the three Sitecore publish-state fields
+ * (`__Never publish`, `__Valid from`, `__Valid to`) up top, then dumps
+ * the rest of the version's fields for context. JSON mode emits the
+ * raw snapshot so it can pipe into jq.
+ */
+import { type CommonContentVersionOptions } from "./shared";
+export type RunContentVersionInspectOptions = CommonContentVersionOptions;
+export declare const runContentVersionInspect: (options: RunContentVersionInspectOptions) => Promise<void>;

package/dist/content/tasks/version-inspect.js

@@ -0,0 +1,56 @@
+"use strict";
+/**
+ * `scai content version inspect` — print the publish-state fields for
+ * an item version. Read-only; does NOT write the audit log (the
+ * audit log records mutations, not reads — keep the trail focused).
+ *
+ * The output groups the three Sitecore publish-state fields
+ * (`__Never publish`, `__Valid from`, `__Valid to`) up top, then dumps
+ * the rest of the version's fields for context. JSON mode emits the
+ * raw snapshot so it can pipe into jq.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runContentVersionInspect = void 0;
+const errors_1 = require("../../shared/errors");
+const environment_1 = require("../../policy/environment");
+const version_fields_1 = require("../../content/api/version-fields");
+const shared_1 = require("./shared");
+const runContentVersionInspect = async (options) => {
+    const logger = (0, shared_1.buildLogger)(options);
+    if (!options.language) {
+        throw (0, errors_1.createScaiError)("inspect requires --language.", "INPUT_INVALID");
+    }
+    const { environment } = (0, environment_1.resolveEnvironment)(options);
+    const itemId = await (0, shared_1.resolveTargetItemId)(environment, options);
+    const snapshot = await (0, shared_1.loadVersionSnapshot)(environment, itemId, options.language, options.version);
+    const neverPublishRaw = (0, version_fields_1.findField)(snapshot, version_fields_1.FIELD_NEVER_PUBLISH);
+    const validFrom = (0, version_fields_1.findField)(snapshot, version_fields_1.FIELD_VALID_FROM);
+    const validTo = (0, version_fields_1.findField)(snapshot, version_fields_1.FIELD_VALID_TO);
+    if (logger.isJson()) {
+        process.stdout.write(`${JSON.stringify({
+            itemId: snapshot.itemId,
+            name: snapshot.name,
+            path: snapshot.path,
+            language: snapshot.language,
+            version: snapshot.version,
+            publishState: {
+                neverPublish: (0, version_fields_1.parseBoolean)(neverPublishRaw),
+                neverPublishRaw,
+                validFrom: validFrom || null,
+                validTo: validTo || null,
+            },
+            allFields: snapshot.fields,
+        }, null, 2)}\n`);
+        return;
+    }
+    logger.info(`Item:          ${snapshot.path}`, "cyan");
+    logger.info(`Item ID:       ${snapshot.itemId}`, "gray");
+    logger.info(`Language:      ${snapshot.language}`, "gray");
+    logger.info(`Version:       ${snapshot.version}`, "gray");
+    logger.info(``, "gray");
+    logger.info(`Publish state:`, "cyan");
+    logger.info(`  ${version_fields_1.FIELD_NEVER_PUBLISH}: ${(0, version_fields_1.parseBoolean)(neverPublishRaw) ? "true" : "false"} (raw: '${neverPublishRaw ?? "(absent)"}')`, "gray");
+    logger.info(`  ${version_fields_1.FIELD_VALID_FROM}:    ${validFrom || "(empty)"}`, "gray");
+    logger.info(`  ${version_fields_1.FIELD_VALID_TO}:      ${validTo || "(empty)"}`, "gray");
+};
+exports.runContentVersionInspect = runContentVersionInspect;

package/dist/content/tasks/version-never-publish.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `scai content version set-never-publish` — set or clear the
+ * `__Never publish` flag on a specific item version.
+ *
+ * Pure CM mutation — DOES NOT auto-publish. After flipping the flag,
+ * operators run `scai content publish item` (or `scai content publish unpublish`)
+ * separately. Letting these two steps stay independent means an
+ * operator can batch several `set-*` changes before paying for the
+ * publish round trip.
+ */
+import { type CommonContentVersionOptions } from "./shared";
+export interface RunContentVersionSetNeverPublishOptions extends CommonContentVersionOptions {
+    /** Target value for `__Never publish`. Required. */
+    value: boolean;
+}
+export declare const runContentVersionSetNeverPublish: (options: RunContentVersionSetNeverPublishOptions) => Promise<void>;