@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/hygiene/api/client.js

@@ -0,0 +1,827 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MASTER_INDEX = exports.MEDIA_LIBRARY_ROOT = exports.createHygieneApiClient = void 0;
+const errors_1 = require("../../shared/errors");
+const graphql_1 = require("../../shared/graphql");
+const client_1 = require("../../workflow/api/client");
+const graphql_2 = require("./graphql");
+/**
+ * Authoring GraphQL operations used by `scai hygiene audit` and `scai hygiene cleanup`.
+ *
+ * Schema verified against XM Cloud Authoring API by introspection
+ * (2026-05-13). The shape of `SearchQueryInput`, `Item.versions`,
+ * `ItemWorkflow`, `archivedItems`, and `deleteItemVersion` are pinned
+ * here; if a tenant exposes a divergent schema, the call surfaces as
+ * a `NETWORK` `ScaiError` with the upstream message preserved.
+ *
+ * Index name: `sitecore_master_index` is the conventional master-DB
+ * index name on XM Cloud. Indexes are not user-renameable on XM Cloud,
+ * but the search index is overridable per-call so callers can target
+ * `sitecore_web_index` for published-state queries if needed.
+ */
+const DEFAULT_MASTER_INDEX = "sitecore_master_index";
+exports.DEFAULT_MASTER_INDEX = DEFAULT_MASTER_INDEX;
+const MEDIA_LIBRARY_ROOT = "/sitecore/media library";
+exports.MEDIA_LIBRARY_ROOT = MEDIA_LIBRARY_ROOT;
+const SEARCH_RESULT_FRAGMENT = `
+totalCount
+results {
+  itemId
+  path
+  name
+  displayName
+  templateId
+  templateName
+  language { name }
+  version
+  updatedDate
+  createdDate
+  database
+  parentId
+}`;
+/**
+ * Build the `search` query as an inlined GraphQL document.
+ *
+ * **Why inline instead of variables.** The XM Cloud Authoring API
+ * rejects `SearchCriteriaType` (and likely all enum types) when passed
+ * via JSON variables — the server returns `EXEC_INVALID_TYPE: "The
+ * value of $query has a wrong structure."` even for spec-conformant
+ * variable bindings. Inlining the enum as a GraphQL literal token
+ * (`criteriaType: CONTAINS`) is the only shape the resolver accepts.
+ *
+ * We escape strings via JSON.stringify, which is GraphQL-string-safe
+ * because GraphQL string syntax is a strict subset of JSON string
+ * syntax (both use `\"`, `\\`, `\n`, etc.). Numbers and booleans pass
+ * through as their JS toString form. Enums are emitted as bare tokens
+ * (no quotes), which is what makes this work.
+ */
+const ENUM_FIELDS = new Set(["criteriaType", "operator", "direction"]);
+const serializeGraphQLValue = (value, key) => {
+    if (value === null || value === undefined)
+        return "null";
+    if (key && ENUM_FIELDS.has(key) && typeof value === "string") {
+        // Enum token — bare identifier, no quotes.
+        return value;
+    }
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    if (Array.isArray(value)) {
+        return `[${value.map((v) => serializeGraphQLValue(v, key)).join(", ")}]`;
+    }
+    if (typeof value === "object") {
+        const obj = value;
+        const entries = Object.entries(obj).filter(([, v]) => v !== undefined);
+        return `{ ${entries.map(([k, v]) => `${k}: ${serializeGraphQLValue(v, k)}`).join(", ")} }`;
+    }
+    return String(value);
+};
+const buildSearchDocument = (queryInput) => {
+    const literal = serializeGraphQLValue(queryInput);
+    return `query { search(query: ${literal}) { ${SEARCH_RESULT_FRAGMENT} } }`;
+};
+const GET_ITEM_FIELDS_BY_PATH = `
+query($path: String!) {
+  item(where: { path: $path }) {
+    itemId
+    path
+    fields(ownFields: false) {
+      nodes {
+        name
+        value
+        templateField { templateFieldId }
+      }
+    }
+  }
+}`;
+const GET_ITEM_FIELDS_BY_ID = `
+query($itemId: ID!) {
+  item(where: { itemId: $itemId }) {
+    itemId
+    path
+    fields(ownFields: false) {
+      nodes {
+        name
+        value
+        templateField { templateFieldId }
+      }
+    }
+  }
+}`;
+const GET_ITEM_VERSIONS_BY_PATH = `
+query($path: String!, $language: String) {
+  item(where: { path: $path, language: $language, existingVersionOnly: true }) {
+    versions {
+      itemId
+      version
+      versionName
+      language { name }
+    }
+  }
+}`;
+const GET_ITEM_VERSIONS_BY_ID = `
+query($itemId: ID!, $language: String) {
+  item(where: { itemId: $itemId, language: $language, existingVersionOnly: true }) {
+    versions {
+      itemId
+      version
+      versionName
+      language { name }
+    }
+  }
+}`;
+const LIST_ARCHIVED_ITEMS_DEFAULT = `
+query($pageIndex: Int, $pageSize: Int) {
+  archivedItems(pageIndex: $pageIndex, pageSize: $pageSize) {
+    archivalId
+    itemId
+    name
+    originalLocation
+    archivedBy
+    archivedDate
+    parentId
+  }
+}`;
+const LIST_ARCHIVED_ITEMS_NAMED = `
+query($archiveName: String!, $pageIndex: Int, $pageSize: Int) {
+  archivedItems(archiveName: $archiveName, pageIndex: $pageIndex, pageSize: $pageSize) {
+    archivalId
+    itemId
+    name
+    originalLocation
+    archivedBy
+    archivedDate
+    parentId
+  }
+}`;
+const DELETE_ITEM_VERSION_MUTATION = `
+mutation($input: DeleteItemVersionInput!) {
+  deleteItemVersion(input: $input) {
+    successful
+  }
+}`;
+const DELETE_ITEM_MUTATION = `
+mutation($input: DeleteItemInput!) {
+  deleteItem(input: $input) {
+    successful
+  }
+}`;
+const DELETE_ITEM_TEMPLATE_MUTATION = `
+mutation($input: DeleteItemTemplateInput!) {
+  deleteItemTemplate(input: $input) {
+    successful
+  }
+}`;
+const UPDATE_ITEM_MUTATION = `
+mutation($input: UpdateItemInput!) {
+  updateItem(input: $input) {
+    item { itemId }
+  }
+}`;
+const ADD_ITEM_VERSION_MUTATION = `
+mutation($input: AddItemVersionInput!) {
+  addItemVersion(input: $input) {
+    item { itemId }
+    versionNumber
+  }
+}`;
+const LIST_USERS_QUERY = `
+query($first: PaginationAmount, $after: String) {
+  users(first: $first, after: $after) {
+    nodes { name isAdministrator isAuthenticated domain { name } }
+    pageInfo { hasNextPage endCursor }
+  }
+}`;
+/**
+ * Per-role member sampling: `nodes` on `AccountConnection` doesn't
+ * expose `totalCount`, so we page-1 the members and check `nodes`
+ * length. >= 1 → has members; 0 → empty role. Quickest signal we can
+ * get without an O(R*M) per-role member walk.
+ */
+const LIST_ROLES_QUERY = `
+query($first: PaginationAmount, $after: String) {
+  roles(first: $first, after: $after) {
+    nodes {
+      name
+      domain { name }
+      members(first: 1) { nodes { name } }
+    }
+    pageInfo { hasNextPage endCursor }
+  }
+}`;
+const GET_USER_DETAIL_QUERY = `
+query($userName: String!) {
+  user(userName: $userName) {
+    name
+    isAdministrator
+    roles { name }
+    profile { lastLoginDate lastActivityDate }
+  }
+}`;
+const DELETE_USER_MUTATION = `
+mutation($input: DeleteUserInput!) {
+  deleteUser(input: $input) { successful }
+}`;
+const DELETE_ROLE_MUTATION = `
+mutation($input: DeleteRoleInput!) {
+  deleteRole(input: $input) { successful }
+}`;
+const DELETE_ARCHIVED_ITEM_MUTATION = `
+mutation($input: DeleteArchivedItemInput!) {
+  deleteArchivedItem(input: $input) {
+    successful
+  }
+}`;
+const ARCHIVE_VERSION_MUTATION = `
+mutation($input: ArchiveVersionInput!) {
+  archiveVersion(input: $input) {
+    archiveVersionId
+  }
+}`;
+/**
+ * Sitecore's well-known "Template" template id. Items based on this
+ * template ARE themselves templates; using it as a `_template` filter
+ * via search lets us enumerate templates under any content-tree subtree
+ * (the Authoring API's `itemTemplates` connection doesn't accept a
+ * subtree scope, only a single-template `path`).
+ */
+const TEMPLATE_TEMPLATE_ID = "ab86861a603046c5b394e8f99e8b87db";
+const CHILD_FRAGMENT = `
+itemId
+name
+path
+template { templateId }`;
+const GET_CHILDREN_BY_PATH = `
+query($path: String!) {
+  item(where: { path: $path }) {
+    children {
+      nodes { ${CHILD_FRAGMENT} }
+    }
+  }
+}`;
+const GET_CHILDREN_BY_ID = `
+query($itemId: ID!) {
+  item(where: { itemId: $itemId }) {
+    children {
+      nodes { ${CHILD_FRAGMENT} }
+    }
+  }
+}`;
+const createHygieneApiClient = (options) => {
+    const { environment, request } = options;
+    const defaultIndex = options.defaultIndex ?? DEFAULT_MASTER_INDEX;
+    const readRequest = {
+        ...request,
+        retry: { ...request?.retry, retryableStatuses: graphql_1.READ_RETRYABLE_STATUSES },
+    };
+    /**
+     * Hygiene mutations are limited to `deleteItemVersion`. Reused recipe-style
+     * "no retry on writes" policy — the Authoring API has no idempotency-key
+     * mechanism, so retrying a delete that may have already applied risks
+     * surfacing a confusing "version not found" on the second attempt.
+     */
+    const writeRequest = {
+        ...(request ?? {}),
+        retry: { maxAttempts: 1 },
+    };
+    // Workflow primitives live in @/workflow/api; we delegate the
+    // hygiene-facing methods so cleanup-workflow-advance and
+    // audit-stale-workflow keep their existing HygieneApiClient surface.
+    const workflowClient = (0, client_1.createWorkflowApiClient)({
+        environment,
+        request,
+    });
+    const buildSearchQuery = (query) => ({
+        index: query.index ?? defaultIndex,
+        ...(query.language !== undefined && { language: query.language }),
+        ...(query.latestVersionOnly !== undefined && {
+            latestVersionOnly: query.latestVersionOnly,
+        }),
+        ...(query.paging !== undefined && { paging: query.paging }),
+        ...(query.searchStatement !== undefined && { searchStatement: query.searchStatement }),
+        ...(query.filterStatement !== undefined && { filterStatement: query.filterStatement }),
+        ...(query.sort !== undefined && { sort: query.sort }),
+    });
+    const search = async (query) => {
+        const document = buildSearchDocument(buildSearchQuery(query));
+        const data = await (0, graphql_2.runHygieneAuthoringGraphQL)(environment, document, undefined, readRequest);
+        return {
+            totalCount: data.search?.totalCount ?? 0,
+            results: data.search?.results ?? [],
+        };
+    };
+    async function* searchAll(query, perPage = 100, parallel = 1) {
+        const startIndex = query.paging?.pageIndex ?? 0;
+        const pageSize = query.paging?.pageSize ?? perPage;
+        // Sanitise: parallel must be >= 1.
+        const fanout = Math.max(1, Math.floor(parallel));
+        // Always fetch the first page sequentially. We need its `totalCount`
+        // to know how many pages to schedule in parallel mode; in serial
+        // mode we use it both for results and for the termination test.
+        const firstPage = await search({
+            ...query,
+            paging: { pageIndex: startIndex, pageSize },
+        });
+        for (const r of firstPage.results)
+            yield r;
+        if (firstPage.results.length < pageSize || firstPage.totalCount <= pageSize) {
+            // No further pages needed.
+            return;
+        }
+        const totalPages = Math.ceil(firstPage.totalCount / pageSize);
+        // First page already consumed; remaining pages are [startIndex+1 ... totalPages-1+startIndex].
+        const remainingStart = startIndex + 1;
+        const remainingEnd = startIndex + totalPages - 1;
+        if (fanout === 1) {
+            // Serial path — preserves the original ordering guarantee that
+            // existing callers may rely on (e.g. test fixtures).
+            let seen = firstPage.results.length;
+            for (let pageIndex = remainingStart; pageIndex <= remainingEnd; pageIndex += 1) {
+                const page = await search({
+                    ...query,
+                    paging: { pageIndex, pageSize },
+                });
+                for (const r of page.results)
+                    yield r;
+                seen += page.results.length;
+                if (page.results.length < pageSize || seen >= firstPage.totalCount)
+                    break;
+            }
+            return;
+        }
+        // Parallel path — fetch pages in windows of size `fanout`. Within
+        // a window, pages resolve concurrently; the window's results are
+        // yielded in pageIndex order so per-window ordering is stable, but
+        // cross-window order remains the page-index order.
+        for (let windowStart = remainingStart; windowStart <= remainingEnd; windowStart += fanout) {
+            const windowEnd = Math.min(windowStart + fanout - 1, remainingEnd);
+            const indices = [];
+            for (let i = windowStart; i <= windowEnd; i += 1)
+                indices.push(i);
+            const pages = await Promise.all(indices.map((pageIndex) => search({
+                ...query,
+                paging: { pageIndex, pageSize },
+            })));
+            for (const page of pages) {
+                for (const r of page.results)
+                    yield r;
+            }
+            // Early stop: if the last page of this window returned a short
+            // page, no further pages exist regardless of totalCount drift.
+            if (pages[pages.length - 1].results.length < pageSize)
+                return;
+        }
+    }
+    const fieldsFromNode = (node) => {
+        if (!node)
+            return [];
+        return node.fields.nodes
+            .filter((f) => f.templateField?.templateFieldId)
+            .map((f) => ({
+            fieldId: f.templateField.templateFieldId,
+            name: f.name,
+            value: f.value,
+        }));
+    };
+    const getItemFields = async (selector) => {
+        if (selector.itemId) {
+            const data = await (0, graphql_2.runHygieneAuthoringGraphQL)(environment, GET_ITEM_FIELDS_BY_ID, { itemId: selector.itemId }, readRequest);
+            return data.item ? fieldsFromNode(data.item) : null;
+        }
+        if (selector.path) {
+            const data = await (0, graphql_2.runHygieneAuthoringGraphQL)(environment, GET_ITEM_FIELDS_BY_PATH, { path: selector.path }, readRequest);
+            return data.item ? fieldsFromNode(data.item) : null;
+        }
+        throw (0, errors_1.createScaiError)("getItemFields requires path or itemId.", "INPUT_INVALID");
+    };
+    /**
+     * Aliased batched read for field-lookup. One POST returns up to
+     * `itemIds.length` items' fields. Keeps the request payload bounded
+     * — caller should chunk to ~25 per batch like the recipe client does.
+     */
+    const getItemFieldsBatch = async (itemIds) => {
+        const result = new Map();
+        if (itemIds.length === 0)
+            return result;
+        const varDecls = itemIds.map((_, i) => `$id${i}: ID!`).join(", ");
+        const selections = itemIds
+            .map((_, i) => `
+  i${i}: item(where: { itemId: $id${i} }) {
+    itemId
+    fields(ownFields: false) {
+      nodes { name value templateField { templateFieldId } }
+    }
+  }`)
+            .join("");
+        const query = `query Batch(${varDecls}) {${selections}\n}`;
+        const variables = {};
+        itemIds.forEach((id, i) => {
+            variables[`id${i}`] = id;
+        });
+        const data = await (0, graphql_2.runHygieneAuthoringGraphQL)(environment, query, variables, readRequest);
+        itemIds.forEach((id, i) => {
+            const node = data[`i${i}`];
+            result.set(id, node ? fieldsFromNode(node) : null);
+        });
+        return result;
+    };
+    const itemExists = async (itemId) => {
+        const data = await (0, graphql_2.runHygieneAuthoringGraphQL)(environment, `query($itemId: ID!) { item(where: { itemId: $itemId }) { itemId } }`, { itemId }, readRequest);
+        return data.item !== null;
+    };
+    const itemsExistBatch = async (itemIds) => {
+        const result = new Map();
+        if (itemIds.length === 0)
+            return result;
+        const varDecls = itemIds.map((_, i) => `$id${i}: ID!`).join(", ");
+        const selections = itemIds
+            .map((_, i) => `
+  i${i}: item(where: { itemId: $id${i} }) { itemId }`)
+            .join("");
+        const query = `query Batch(${varDecls}) {${selections}\n}`;
+        const variables = {};
+        itemIds.forEach((id, i) => {
+            variables[`id${i}`] = id;
+        });
+        const data = await (0, graphql_2.runHygieneAuthoringGraphQL)(environment, query, variables, readRequest);
+        itemIds.forEach((id, i) => {
+            result.set(id, data[`i${i}`] !== null);
+        });
+        return result;
+    };
+    const getItemVersions = async (selector) => {
+        const variables = { language: selector.language ?? null };
+        if (selector.itemId) {
+            const data = await (0, graphql_2.runHygieneAuthoringGraphQL)(environment, GET_ITEM_VERSIONS_BY_ID, { itemId: selector.itemId, ...variables }, readRequest);
+            return data.item?.versions ?? [];
+        }
+        if (selector.path) {
+            const data = await (0, graphql_2.runHygieneAuthoringGraphQL)(environment, GET_ITEM_VERSIONS_BY_PATH, { path: selector.path, ...variables }, readRequest);
+            return data.item?.versions ?? [];
+        }
+        throw (0, errors_1.createScaiError)("getItemVersions requires path or itemId.", "INPUT_INVALID");
+    };
+    const getItemWorkflow = async (itemId, path) => {
+        const result = await workflowClient.getItemWorkflow({ itemId });
+        if (!result)
+            return null;
+        return { ...result, path: result.path ?? path };
+    };
+    const listArchivedItems = async (opts = {}) => {
+        // The Authoring API resolver rejects a null `archiveName` even when
+        // the GraphQL declaration types it as nullable. Use a query that
+        // omits the variable entirely when the caller didn't ask for a
+        // specific archive — that's the "all archives" path. When the caller
+        // does provide a name, use the variant that declares it as required.
+        const pageIndex = opts.pageIndex ?? 0;
+        const pageSize = opts.pageSize ?? 100;
+        if (opts.archiveName !== undefined) {
+            const data = await (0, graphql_2.runHygieneAuthoringGraphQL)(environment, LIST_ARCHIVED_ITEMS_NAMED, { archiveName: opts.archiveName, pageIndex, pageSize }, readRequest);
+            return data.archivedItems ?? [];
+        }
+        const data = await (0, graphql_2.runHygieneAuthoringGraphQL)(environment, LIST_ARCHIVED_ITEMS_DEFAULT, { pageIndex, pageSize }, readRequest);
+        return data.archivedItems ?? [];
+    };
+    const deleteItemVersion = async (input) => {
+        if (!input.itemId && !input.path) {
+            throw (0, errors_1.createScaiError)("deleteItemVersion requires either itemId or path.", "INPUT_INVALID");
+        }
+        const payload = {
+            language: input.language,
+            version: input.version,
+            database: input.database ?? "master",
+        };
+        if (input.itemId)
+            payload.itemId = input.itemId;
+        else if (input.path)
+            payload.path = input.path;
+        const data = await (0, graphql_2.runHygieneAuthoringGraphQL)(environment, DELETE_ITEM_VERSION_MUTATION, { input: payload }, writeRequest);
+        if (!data.deleteItemVersion?.successful) {
+            throw (0, errors_1.createScaiError)(`deleteItemVersion returned successful=${data.deleteItemVersion?.successful} for ${input.itemId ?? input.path} @${input.language} v${input.version}`, "UNKNOWN");
+        }
+    };
+    const deleteItem = async (input) => {
+        if (!input.itemId && !input.path) {
+            throw (0, errors_1.createScaiError)("deleteItem requires either itemId or path.", "INPUT_INVALID");
+        }
+        const payload = {
+            database: input.database ?? "master",
+            permanently: input.permanently ?? true,
+        };
+        if (input.itemId)
+            payload.itemId = input.itemId;
+        else if (input.path)
+            payload.path = input.path;
+        const data = await (0, graphql_2.runHygieneAuthoringGraphQL)(environment, DELETE_ITEM_MUTATION, { input: payload }, writeRequest);
+        if (!data.deleteItem?.successful) {
+            throw (0, errors_1.createScaiError)(`deleteItem returned successful=${data.deleteItem?.successful} for ${input.itemId ?? input.path}`, "UNKNOWN");
+        }
+    };
+    const deleteItemTemplate = async (templateId, database = "master") => {
+        const data = await (0, graphql_2.runHygieneAuthoringGraphQL)(environment, DELETE_ITEM_TEMPLATE_MUTATION, { input: { templateId, database } }, writeRequest);
+        if (!data.deleteItemTemplate?.successful) {
+            throw (0, errors_1.createScaiError)(`deleteItemTemplate returned successful=${data.deleteItemTemplate?.successful} for template ${templateId}`, "UNKNOWN");
+        }
+    };
+    const deleteArchivedItem = async (archivalId, archiveName) => {
+        const input = { archivalId };
+        if (archiveName !== undefined)
+            input.archiveName = archiveName;
+        const data = await (0, graphql_2.runHygieneAuthoringGraphQL)(environment, DELETE_ARCHIVED_ITEM_MUTATION, { input }, writeRequest);
+        if (!data.deleteArchivedItem?.successful) {
+            throw (0, errors_1.createScaiError)(`deleteArchivedItem returned successful=${data.deleteArchivedItem?.successful} for ${archivalId}`, "UNKNOWN");
+        }
+    };
+    const archiveVersion = async (input) => {
+        if (!input.itemId && !input.itemPath) {
+            throw (0, errors_1.createScaiError)("archiveVersion requires either itemId or itemPath.", "INPUT_INVALID");
+        }
+        const payload = {
+            language: input.language,
+            version: input.version,
+        };
+        if (input.itemId)
+            payload.itemId = input.itemId;
+        else if (input.itemPath)
+            payload.itemPath = input.itemPath;
+        if (input.archiveName !== undefined)
+            payload.archiveName = input.archiveName;
+        const data = await (0, graphql_2.runHygieneAuthoringGraphQL)(environment, ARCHIVE_VERSION_MUTATION, { input: payload }, writeRequest);
+        return data.archiveVersion?.archiveVersionId ?? null;
+    };
+    /**
+     * Enumerate item templates, optionally scoped to a content-tree subtree.
+     *
+     * Implementation note: the Authoring API's `itemTemplates(where: {path})`
+     * matches one template by path (not a subtree), and `standardValuesItem`
+     * requires a `language` argument that's awkward to thread through here.
+     * Instead, we use the search index — items where `_template` is the
+     * well-known "Template" template id ARE themselves templates. Adding a
+     * `_path` filter scopes to a subtree. Name + path are pulled from the
+     * search result; `fullName` is derived from the path by stripping the
+     * `/sitecore/templates/` prefix.
+     */
+    const listItemTemplates = async (opts = {}) => {
+        const results = [];
+        let rootItemId;
+        let rootPrefix;
+        if (opts.rootPath) {
+            const normalizedRoot = opts.rootPath.replace(/\/+$/, "").toLowerCase();
+            // A `pageSize: 1` `_fullpath` lookup cannot distinguish an exact hit
+            // from a near-match the index ranked first; a wrong (shallower) root
+            // silently widens the `_path CONTAINS` scope below. Fetch a small
+            // page and confirm the path matches exactly.
+            const r = await search({
+                paging: { pageSize: 20 },
+                searchStatement: {
+                    criteria: {
+                        field: "_fullpath",
+                        value: normalizedRoot,
+                        criteriaType: "EXACT",
+                    },
+                },
+            });
+            rootItemId = r.results.find((x) => x.path?.toLowerCase() === normalizedRoot)?.itemId;
+            if (!rootItemId) {
+                throw (0, errors_1.createScaiError)(`Root path '${opts.rootPath}' was not found in the template tree.`, "INPUT_INVALID", { hint: "Pass --root as an existing item path, e.g. /sitecore/templates/Project." });
+            }
+            rootPrefix = `${normalizedRoot}/`;
+        }
+        const statement = rootItemId
+            ? {
+                operator: "MUST",
+                subStatements: [
+                    {
+                        criteria: {
+                            field: "_template",
+                            value: TEMPLATE_TEMPLATE_ID,
+                            criteriaType: "EXACT",
+                        },
+                    },
+                    {
+                        criteria: {
+                            field: "_path",
+                            value: rootItemId.toLowerCase().replace(/[-{}]/g, ""),
+                            criteriaType: "CONTAINS",
+                        },
+                    },
+                ],
+            }
+            : {
+                criteria: {
+                    field: "_template",
+                    value: TEMPLATE_TEMPLATE_ID,
+                    criteriaType: "EXACT",
+                },
+            };
+        // Dedup by templateId. The search index returns the same template
+        // multiple times when its `_path` contains the root itemId in
+        // multiple language indexes / version rows, even with
+        // `latestVersionOnly: true` (SXA tenants in particular surface
+        // `Project`, `Experience Accelerator`, etc. 4–5x each). Without
+        // this Set, every downstream audit double-counts.
+        const seen = new Set();
+        for await (const r of searchAll({
+            latestVersionOnly: true,
+            searchStatement: statement,
+        }, opts.pageSize ?? 100)) {
+            if (!r.itemId || seen.has(r.itemId))
+                continue;
+            // The `_path CONTAINS` index filter is a substring match and can
+            // over-match; confirm the hit truly sits under the requested root.
+            if (rootPrefix && !(r.path?.toLowerCase() ?? "").startsWith(rootPrefix))
+                continue;
+            seen.add(r.itemId);
+            const fullName = r.path ? r.path.replace(/^\/sitecore\/templates\//i, "") : null;
+            results.push({
+                templateId: r.itemId,
+                name: r.name,
+                fullName,
+                standardValuesItemId: null,
+            });
+        }
+        return results;
+    };
+    const getChildren = async (selector) => {
+        const map = (nodes) => nodes.map((n) => ({
+            itemId: n.itemId,
+            name: n.name,
+            path: n.path,
+            templateId: n.template?.templateId ?? null,
+            templateName: null,
+        }));
+        if (selector.itemId) {
+            const data = await (0, graphql_2.runHygieneAuthoringGraphQL)(environment, GET_CHILDREN_BY_ID, { itemId: selector.itemId }, readRequest);
+            return data.item ? map(data.item.children.nodes) : [];
+        }
+        if (selector.path) {
+            const data = await (0, graphql_2.runHygieneAuthoringGraphQL)(environment, GET_CHILDREN_BY_PATH, { path: selector.path }, readRequest);
+            return data.item ? map(data.item.children.nodes) : [];
+        }
+        throw (0, errors_1.createScaiError)("getChildren requires itemId or path.", "INPUT_INVALID");
+    };
+    const updateItemFields = async (input) => {
+        if (!input.itemId) {
+            throw (0, errors_1.createScaiError)("updateItemFields requires itemId.", "INPUT_INVALID");
+        }
+        if (!input.fields.length) {
+            // No-op for empty field updates — saves a wire call.
+            return;
+        }
+        const data = await (0, graphql_2.runHygieneAuthoringGraphQL)(environment, UPDATE_ITEM_MUTATION, {
+            input: {
+                itemId: input.itemId,
+                fields: input.fields,
+            },
+        }, writeRequest);
+        if (!data.updateItem?.item?.itemId) {
+            throw (0, errors_1.createScaiError)(`updateItem returned no itemId for ${input.itemId}.`, "UNKNOWN");
+        }
+    };
+    const renameItem = async (input) => {
+        if (!input.itemId) {
+            throw (0, errors_1.createScaiError)("renameItem requires itemId.", "INPUT_INVALID");
+        }
+        if (!input.name || !input.name.trim()) {
+            throw (0, errors_1.createScaiError)("renameItem requires a non-empty name.", "INPUT_INVALID");
+        }
+        if (/[/\\]/.test(input.name)) {
+            // Slashes in a Sitecore item name produce paths the resolver can't
+            // round-trip; reject at the API boundary so the caller doesn't
+            // hand the foot-gun to the user.
+            throw (0, errors_1.createScaiError)("Item names cannot contain '/' or '\\'.", "INPUT_INVALID");
+        }
+        const data = await (0, graphql_2.runHygieneAuthoringGraphQL)(environment, UPDATE_ITEM_MUTATION, { input: { itemId: input.itemId, name: input.name } }, writeRequest);
+        if (!data.updateItem?.item?.itemId) {
+            throw (0, errors_1.createScaiError)(`renameItem returned no itemId for ${input.itemId}.`, "UNKNOWN");
+        }
+    };
+    const addItemVersion = async (input) => {
+        if (!input.itemId) {
+            throw (0, errors_1.createScaiError)("addItemVersion requires itemId.", "INPUT_INVALID");
+        }
+        if (!input.language) {
+            throw (0, errors_1.createScaiError)("addItemVersion requires language.", "INPUT_INVALID");
+        }
+        const data = await (0, graphql_2.runHygieneAuthoringGraphQL)(environment, ADD_ITEM_VERSION_MUTATION, {
+            input: {
+                itemId: input.itemId,
+                language: input.language,
+                ...(input.baseVersion !== undefined && { versionNumber: input.baseVersion }),
+            },
+        }, writeRequest);
+        if (!data.addItemVersion?.item?.itemId) {
+            throw (0, errors_1.createScaiError)(`addItemVersion returned no itemId for ${input.itemId}/${input.language}.`, "UNKNOWN");
+        }
+        return { versionNumber: data.addItemVersion.versionNumber };
+    };
+    const listUsers = async (opts = {}) => {
+        const pageSize = opts.pageSize ?? 100;
+        const result = [];
+        let after = null;
+        while (true) {
+            const variables = { first: pageSize };
+            if (after)
+                variables.after = after;
+            const data = await (0, graphql_2.runHygieneAuthoringGraphQL)(environment, LIST_USERS_QUERY, variables, readRequest);
+            const conn = data.users;
+            if (!conn)
+                break;
+            for (const u of conn.nodes) {
+                result.push({
+                    name: u.name,
+                    isAdministrator: u.isAdministrator,
+                    isAuthenticated: u.isAuthenticated,
+                    domain: u.domain?.name ?? null,
+                });
+            }
+            if (!conn.pageInfo.hasNextPage || !conn.pageInfo.endCursor)
+                break;
+            after = conn.pageInfo.endCursor;
+        }
+        return result;
+    };
+    const listRoles = async (opts = {}) => {
+        const pageSize = opts.pageSize ?? 100;
+        const result = [];
+        let after = null;
+        while (true) {
+            const variables = { first: pageSize };
+            if (after)
+                variables.after = after;
+            const data = await (0, graphql_2.runHygieneAuthoringGraphQL)(environment, LIST_ROLES_QUERY, variables, readRequest);
+            const conn = data.roles;
+            if (!conn)
+                break;
+            for (const r of conn.nodes) {
+                // members(first:1) — count signal only. >= 1 → role has at
+                // least one direct member. 0 → empty role.
+                result.push({
+                    name: r.name,
+                    domain: r.domain?.name ?? null,
+                    memberCount: r.members?.nodes.length ?? 0,
+                });
+            }
+            if (!conn.pageInfo.hasNextPage || !conn.pageInfo.endCursor)
+                break;
+            after = conn.pageInfo.endCursor;
+        }
+        return result;
+    };
+    const getUserDetail = async (userName) => {
+        const data = await (0, graphql_2.runHygieneAuthoringGraphQL)(environment, GET_USER_DETAIL_QUERY, { userName }, readRequest);
+        if (!data.user)
+            return null;
+        return {
+            name: data.user.name,
+            isAdministrator: data.user.isAdministrator,
+            roles: data.user.roles.map((r) => r.name),
+            lastLogin: data.user.profile?.lastLoginDate ?? null,
+            lastActivity: data.user.profile?.lastActivityDate ?? null,
+        };
+    };
+    const deleteUser = async (userName) => {
+        const data = await (0, graphql_2.runHygieneAuthoringGraphQL)(environment, DELETE_USER_MUTATION, { input: { userName } }, writeRequest);
+        if (!data.deleteUser?.successful) {
+            throw (0, errors_1.createScaiError)(`deleteUser returned successful=${data.deleteUser?.successful} for ${userName}`, "UNKNOWN");
+        }
+    };
+    const deleteRole = async (roleName) => {
+        const data = await (0, graphql_2.runHygieneAuthoringGraphQL)(environment, DELETE_ROLE_MUTATION, { input: { roleName } }, writeRequest);
+        if (!data.deleteRole?.successful) {
+            throw (0, errors_1.createScaiError)(`deleteRole returned successful=${data.deleteRole?.successful} for ${roleName}`, "UNKNOWN");
+        }
+    };
+    const executeWorkflowCommand = workflowClient.executeWorkflowCommand;
+    const getWorkflowCommandsForItem = workflowClient.getWorkflowCommandsForItem;
+    return {
+        search,
+        searchAll,
+        getItemFields,
+        getItemFieldsBatch,
+        itemExists,
+        itemsExistBatch,
+        getItemVersions,
+        getItemWorkflow,
+        listArchivedItems,
+        deleteItemVersion,
+        deleteItem,
+        deleteItemTemplate,
+        deleteArchivedItem,
+        archiveVersion,
+        listItemTemplates,
+        getChildren,
+        updateItemFields,
+        renameItem,
+        addItemVersion,
+        listUsers,
+        listRoles,
+        getUserDetail,
+        deleteUser,
+        deleteRole,
+        executeWorkflowCommand,
+        getWorkflowCommandsForItem,
+    };
+};
+exports.createHygieneApiClient = createHygieneApiClient;