@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/recipe/validate.d.ts

@@ -14,21 +14,46 @@ import type { Recipe } from "./schema/recipe";
  *     params[*].sitecore.sourceTypes[*]   → any template-bearing recipe
  *     insertOptions[*]                    → any template-bearing recipe
  *
+ *   ComponentTemplateRecipe
+ *     placeholders[*].allowedComponents[*]→ ComponentTemplateRecipe
+ *
  *   ContentItemRecipe
  *     templateType                        → any template-bearing recipe
  *     fields[*].link-internal.ref         → any recipe
  *     fields[*].reference.refs[*]         → any recipe
  *
+ *   PageTemplateRecipe
+ *     fields[*].sitecore.sourceTypes[*]   → any template-bearing recipe
+ *     insertOptions[*]                    → PageTemplateRecipe
+ *     layout.placeholders[*][*].componentHandle           → ComponentTemplateRecipe
+ *     layout.placeholders[*][*].datasourceRef.handle      → ContentItemRecipe
+ *
+ *   PlaceholderRecipe
+ *     allowedComponents[*]                → ComponentTemplateRecipe
+ *
+ *   PageRecipe
+ *     template                            → PageTemplateRecipe
+ *     fields[*].link-internal.ref          → any recipe
+ *     fields[*].reference.refs[*]          → any recipe
+ *     layout.placeholders[*][*].componentHandle      → ComponentTemplateRecipe
+ *     layout.placeholders[*][*].datasourceRef.handle → ContentItemRecipe
+ *
  *   PartialDesignRecipe
  *     layout.placeholders[*][*].componentHandle           → ComponentTemplateRecipe
  *     layout.placeholders[*][*].datasourceRef.handle      → ContentItemRecipe
  *
  *   PageDesignRecipe
- *     appliesTo[*]                        → ContentTemplateRecipe (page templates)
+ *     appliesTo[*]                        → PageTemplateRecipe
  *     partials[*]                         → PartialDesignRecipe
  *     layout.placeholders[*][*].componentHandle           → ComponentTemplateRecipe
  *     layout.placeholders[*][*].datasourceRef.handle      → ContentItemRecipe
  *
+ * Beyond reference resolution this also checks **placement legality** —
+ * a layout placement into a recipe-defined placeholder whose
+ * `Allowed Controls` whitelist doesn't include the component is reported
+ * as a `PlacementViolation` — and flags a placeholder `key` declared by
+ * more than one recipe.
+ *
  * Cycle detection covers `insertOptions` chains
  * (`ComponentTemplate.insertOptions → ContentTemplate.insertOptions → …`)
  * — the only place the current schema permits transitive recipe-to-recipe
@@ -77,11 +102,36 @@ export interface FieldShapeError {
     /** Operator-readable explanation. */
     message: string;
 }
+/**
+ * A layout placement that drops a component into a recipe-defined
+ * placeholder whose `Allowed Controls` whitelist doesn't include it —
+ * the "what's allowed in a placeholder" enforcement.
+ *
+ * Only raised for placeholders the recipe set itself defines (a
+ * `PlaceholderRecipe` or an inline `ComponentTemplateRecipe.placeholders`
+ * slot) AND that carry a non-empty whitelist. Placements into
+ * pre-existing tenant placeholders, or into recipe-defined placeholders
+ * with an empty (unrestricted) whitelist, are not checkable here and
+ * pass.
+ */
+export interface PlacementViolation {
+    /** Handle of the recipe that holds the offending layout. */
+    fromRecipe: string;
+    /** Dotted path to the placement — `layout.placeholders./header.0`. */
+    fromField: string;
+    /** The component handle being placed. */
+    componentHandle: string;
+    /** The placeholder key it was placed into. */
+    placeholderKey: string;
+    /** The component handles the placeholder's whitelist does allow. */
+    allowedComponents: readonly string[];
+}
 export interface ValidationResult {
     unresolvedHandles: UnresolvedHandle[];
     duplicateHandles: DuplicateHandle[];
     cycles: CyclicReference[];
     fieldShapeErrors: FieldShapeError[];
+    placementViolations: PlacementViolation[];
 }
 export declare const isValid: (result: ValidationResult) => boolean;
 /**
@@ -100,4 +150,3 @@ export declare function validateRecipeSet(recipes: readonly Recipe[]): Validatio
  * should hard-stop before compilation when the recipe set is malformed.
  */
 export declare function validateRecipeSetOrThrow(recipes: readonly Recipe[]): void;
-//# sourceMappingURL=validate.d.ts.map

package/dist/recipe/validate.js

@@ -5,11 +5,17 @@ exports.formatValidationErrors = formatValidationErrors;
 exports.validateRecipeSet = validateRecipeSet;
 exports.validateRecipeSetOrThrow = validateRecipeSetOrThrow;
 const errors_1 = require("../shared/errors");
-const TEMPLATE_KINDS = ["component-template", "content-template"];
+const TEMPLATE_KINDS = [
+    "component-template",
+    "content-template",
+    "page-template",
+];
 const COMPONENT_TEMPLATE_KINDS = ["component-template"];
 const CONTENT_TEMPLATE_KINDS = ["content-template"];
+const PAGE_TEMPLATE_KINDS = ["page-template"];
+const PAGE_KINDS = ["page"];
 const CONTENT_ITEM_KINDS = ["content-item"];
-const PARAMETERS_TEMPLATE_KINDS = ["parameters-template"];
+const PARAMETERS_TEMPLATE_KINDS = ["design-parameters-template"];
 const SECTION_DEFINITION_KINDS = ["section-definition"];
 const PARTIAL_DESIGN_KINDS = ["partial-design"];
 const PAGE_DESIGN_KINDS = ["page-design"];
@@ -18,7 +24,10 @@ const ANY_KINDS = [
     "component-template",
     "content-template",
     "content-item",
-    "parameters-template",
+    "page-template",
+    "page",
+    "placeholder",
+    "design-parameters-template",
     "section-definition",
     "partial-design",
     "page-design",
@@ -26,7 +35,8 @@ const ANY_KINDS = [
 const isValid = (result) => result.unresolvedHandles.length === 0 &&
     result.duplicateHandles.length === 0 &&
     result.cycles.length === 0 &&
-    result.fieldShapeErrors.length === 0;
+    result.fieldShapeErrors.length === 0 &&
+    result.placementViolations.length === 0;
 exports.isValid = isValid;
 /**
  * Render a `ValidationResult` as a multi-line, human-readable error
@@ -49,6 +59,9 @@ function formatValidationErrors(result) {
     for (const err of result.fieldShapeErrors) {
         lines.push(`${err.fromRecipe} → ${err.fromField}: ${err.message}`);
     }
+    for (const v of result.placementViolations) {
+        lines.push(`${v.fromRecipe} → ${v.fromField}: '${v.componentHandle}' is not allowed in placeholder '${v.placeholderKey}' (allowed: ${v.allowedComponents.join(", ") || "none"}).`);
+    }
     return lines.join("\n");
 }
 /**
@@ -94,6 +107,79 @@ function validateRecipeSet(recipes) {
             });
         }
     };
+    const placementViolations = [];
+    // Pre-pass: collect recipe-defined placeholder keys and their resolved
+    // `Allowed Controls` whitelists — standalone `PlaceholderRecipe` plus
+    // inline `ComponentTemplateRecipe.placeholders`, then `placedIn`
+    // pushes. Mirrors `buildPlaceholderSettingsAggregate` in `compile.ts`
+    // so the legality check sees the same allow-sets the compiler emits.
+    const placeholderAllow = new Map();
+    const placeholderDefiners = new Map();
+    const declarePlaceholder = (key, byRecipe) => {
+        placeholderDefiners.set(key, [...(placeholderDefiners.get(key) ?? []), byRecipe]);
+        let set = placeholderAllow.get(key);
+        if (!set) {
+            set = new Set();
+            placeholderAllow.set(key, set);
+        }
+        return set;
+    };
+    for (const recipe of recipes) {
+        if (recipe.kind === "placeholder") {
+            const set = declarePlaceholder(recipe.key, recipe.handle);
+            for (const handle of recipe.allowedComponents ?? [])
+                set.add(handle);
+        }
+        else if (recipe.kind === "component-template") {
+            for (const slot of recipe.placeholders ?? []) {
+                const set = declarePlaceholder(slot.key, recipe.handle);
+                for (const handle of slot.allowedComponents ?? [])
+                    set.add(handle);
+            }
+        }
+    }
+    for (const recipe of recipes) {
+        if (recipe.kind !== "component-template")
+            continue;
+        for (const key of recipe.placedIn ?? []) {
+            placeholderAllow.get(key)?.add(recipe.handle);
+        }
+    }
+    // A placeholder key declared by 2+ recipes is ambiguous — both would
+    // derive the same Placeholder Settings item GUID. Flag it once.
+    for (const [key, definers] of placeholderDefiners) {
+        if (definers.length > 1) {
+            fieldShapeErrors.push({
+                fromRecipe: definers[0],
+                fromField: "placeholder key",
+                message: `placeholder key '${key}' is declared by multiple recipes (${definers.join(", ")}) — a key maps to exactly one Placeholder Settings item; declare it once.`,
+            });
+        }
+    }
+    /**
+     * Check every placement in a layout against the placeholder allow-set.
+     * Only flags placements into recipe-defined placeholders with a
+     * non-empty whitelist — pre-existing tenant placeholders and
+     * unrestricted (empty-whitelist) ones can't be checked and pass.
+     */
+    const checkLayoutPlacements = (fromRecipe, placeholders) => {
+        for (const [phKey, placements] of Object.entries(placeholders)) {
+            const allow = placeholderAllow.get(phKey);
+            if (!allow || allow.size === 0)
+                continue;
+            placements.forEach((placement, idx) => {
+                if (!allow.has(placement.componentHandle)) {
+                    placementViolations.push({
+                        fromRecipe,
+                        fromField: `layout.placeholders.${phKey}.${idx}`,
+                        componentHandle: placement.componentHandle,
+                        placeholderKey: phKey,
+                        allowedComponents: [...allow].sort((a, b) => a.localeCompare(b)),
+                    });
+                }
+            });
+        }
+    };
     for (const recipe of recipes) {
         switch (recipe.kind) {
             case "component-template":
@@ -122,8 +208,13 @@ function validateRecipeSet(recipes) {
                 recipe.availableIn?.forEach((handle, idx) => {
                     checkRef(recipe.handle, `availableIn.${idx}`, handle, SECTION_DEFINITION_KINDS);
                 });
+                (recipe.placeholders ?? []).forEach((slot, idx) => {
+                    slot.allowedComponents?.forEach((handle, aIdx) => {
+                        checkRef(recipe.handle, `placeholders.${idx}.allowedComponents.${aIdx}`, handle, COMPONENT_TEMPLATE_KINDS);
+                    });
+                });
                 break;
-            case "parameters-template":
+            case "design-parameters-template":
                 recipe.params.forEach((param, idx) => {
                     param.sitecore?.sourceTypes?.forEach((handle, sIdx) => {
                         checkRef(recipe.handle, `params.${idx}.sitecore.sourceTypes.${sIdx}`, handle, TEMPLATE_KINDS);
@@ -166,10 +257,11 @@ function validateRecipeSet(recipes) {
                         }
                     });
                 }
+                checkLayoutPlacements(recipe.handle, recipe.layout.placeholders);
                 break;
             case "page-design":
                 recipe.appliesTo.forEach((handle, idx) => {
-                    checkRef(recipe.handle, `appliesTo.${idx}`, handle, CONTENT_TEMPLATE_KINDS);
+                    checkRef(recipe.handle, `appliesTo.${idx}`, handle, PAGE_TEMPLATE_KINDS);
                 });
                 recipe.partials.forEach((handle, idx) => {
                     checkRef(recipe.handle, `partials.${idx}`, handle, PARTIAL_DESIGN_KINDS);
@@ -183,11 +275,62 @@ function validateRecipeSet(recipes) {
                             }
                         });
                     }
+                    checkLayoutPlacements(recipe.handle, recipe.layout.placeholders);
+                }
+                break;
+            case "page-template":
+                (recipe.fields ?? []).forEach((field, idx) => {
+                    field.sitecore?.sourceTypes?.forEach((handle, sIdx) => {
+                        checkRef(recipe.handle, `fields.${idx}.sitecore.sourceTypes.${sIdx}`, handle, TEMPLATE_KINDS);
+                    });
+                });
+                recipe.insertOptions?.forEach((handle, idx) => {
+                    checkRef(recipe.handle, `insertOptions.${idx}`, handle, PAGE_TEMPLATE_KINDS);
+                });
+                if (recipe.layout) {
+                    for (const [phKey, placements] of Object.entries(recipe.layout.placeholders)) {
+                        placements.forEach((placement, idx) => {
+                            checkRef(recipe.handle, `layout.placeholders.${phKey}.${idx}.componentHandle`, placement.componentHandle, COMPONENT_TEMPLATE_KINDS);
+                            if (placement.datasourceRef?.kind === "shared") {
+                                checkRef(recipe.handle, `layout.placeholders.${phKey}.${idx}.datasourceRef.handle`, placement.datasourceRef.handle, CONTENT_ITEM_KINDS);
+                            }
+                        });
+                    }
+                    checkLayoutPlacements(recipe.handle, recipe.layout.placeholders);
+                }
+                break;
+            case "placeholder":
+                (recipe.allowedComponents ?? []).forEach((handle, idx) => {
+                    checkRef(recipe.handle, `allowedComponents.${idx}`, handle, COMPONENT_TEMPLATE_KINDS);
+                });
+                break;
+            case "page":
+                checkRef(recipe.handle, "template", recipe.template, PAGE_TEMPLATE_KINDS);
+                for (const [fieldName, value] of Object.entries(recipe.fields ?? {})) {
+                    if (value.shape === "link-internal") {
+                        checkRef(recipe.handle, `fields.${fieldName}.ref`, value.ref, ANY_KINDS);
+                    }
+                    else if (value.shape === "reference") {
+                        value.refs.forEach((handle, idx) => {
+                            checkRef(recipe.handle, `fields.${fieldName}.refs.${idx}`, handle, ANY_KINDS);
+                        });
+                    }
+                }
+                if (recipe.layout) {
+                    for (const [phKey, placements] of Object.entries(recipe.layout.placeholders)) {
+                        placements.forEach((placement, idx) => {
+                            checkRef(recipe.handle, `layout.placeholders.${phKey}.${idx}.componentHandle`, placement.componentHandle, COMPONENT_TEMPLATE_KINDS);
+                            if (placement.datasourceRef?.kind === "shared") {
+                                checkRef(recipe.handle, `layout.placeholders.${phKey}.${idx}.datasourceRef.handle`, placement.datasourceRef.handle, CONTENT_ITEM_KINDS);
+                            }
+                        });
+                    }
+                    checkLayoutPlacements(recipe.handle, recipe.layout.placeholders);
                 }
                 break;
             case "site-template":
                 recipe.pageTemplates.forEach((handle, idx) => {
-                    checkRef(recipe.handle, `pageTemplates.${idx}`, handle, CONTENT_TEMPLATE_KINDS);
+                    checkRef(recipe.handle, `pageTemplates.${idx}`, handle, PAGE_TEMPLATE_KINDS);
                 });
                 recipe.pageDesigns.forEach((handle, idx) => {
                     checkRef(recipe.handle, `pageDesigns.${idx}`, handle, PAGE_DESIGN_KINDS);
@@ -196,15 +339,15 @@ function validateRecipeSet(recipes) {
                     for (const [parentHandle, allowedChildren] of Object.entries(recipe.insertOptionsMatrix)) {
                         // The KEY is itself a page-template handle. Validate it too —
                         // a typo in the key would silently never apply at apply time.
-                        checkRef(recipe.handle, `insertOptionsMatrix.${parentHandle}`, parentHandle, CONTENT_TEMPLATE_KINDS);
+                        checkRef(recipe.handle, `insertOptionsMatrix.${parentHandle}`, parentHandle, PAGE_TEMPLATE_KINDS);
                         allowedChildren.forEach((childHandle, idx) => {
-                            checkRef(recipe.handle, `insertOptionsMatrix.${parentHandle}.${idx}`, childHandle, CONTENT_TEMPLATE_KINDS);
+                            checkRef(recipe.handle, `insertOptionsMatrix.${parentHandle}.${idx}`, childHandle, PAGE_TEMPLATE_KINDS);
                         });
                     }
                 }
                 if (recipe.templatesToDesigns) {
                     for (const [templateHandle, designHandle] of Object.entries(recipe.templatesToDesigns)) {
-                        checkRef(recipe.handle, `templatesToDesigns.${templateHandle} (key)`, templateHandle, CONTENT_TEMPLATE_KINDS);
+                        checkRef(recipe.handle, `templatesToDesigns.${templateHandle} (key)`, templateHandle, PAGE_TEMPLATE_KINDS);
                         checkRef(recipe.handle, `templatesToDesigns.${templateHandle}`, designHandle, PAGE_DESIGN_KINDS);
                     }
                 }
@@ -212,9 +355,7 @@ function validateRecipeSet(recipes) {
             case "site":
                 checkRef(recipe.handle, "siteTemplate", recipe.siteTemplate, SITE_TEMPLATE_KINDS);
                 if (recipe.initialHome !== undefined) {
-                    // PageRecipe doesn't exist yet — accept any kind. When
-                    // PageRecipe lands, narrow this to PAGE_RECIPE_KINDS.
-                    checkRef(recipe.handle, "initialHome", recipe.initialHome, ANY_KINDS);
+                    checkRef(recipe.handle, "initialHome", recipe.initialHome, PAGE_KINDS);
                 }
                 // Cross-field shape: SiteRecipe must specify exactly one of
                 // collectionId or collectionName. The Zod schema can't enforce
@@ -238,7 +379,13 @@ function validateRecipeSet(recipes) {
         }
     }
     const cycles = detectInsertOptionsCycles(index, recipes);
-    return { unresolvedHandles: unresolved, duplicateHandles, cycles, fieldShapeErrors };
+    return {
+        unresolvedHandles: unresolved,
+        duplicateHandles,
+        cycles,
+        fieldShapeErrors,
+        placementViolations,
+    };
 }
 /**
  * DFS over `insertOptions` edges. Each unique cycle is reported once,
@@ -292,6 +439,6 @@ function detectInsertOptionsCycles(index, recipes) {
 function validateRecipeSetOrThrow(recipes) {
     const result = validateRecipeSet(recipes);
     if (!(0, exports.isValid)(result)) {
-        throw (0, errors_1.createCliError)(`Recipe set validation failed:\n${formatValidationErrors(result)}`, "INPUT_INVALID");
+        throw (0, errors_1.createScaiError)(`Recipe set validation failed:\n${formatValidationErrors(result)}`, "INPUT_INVALID");
     }
 }

package/dist/scripting/connect.d.ts

@@ -0,0 +1,24 @@
+import { type HygieneApiClient } from "../hygiene/api/client";
+/**
+ * Unified client for ad-hoc TypeScript scripting against a configured
+ * scai environment. The intent: replace one-shot imports from `@/`-path
+ * internals with a stable, ergonomic entry point that handles env
+ * resolution, auth, and client lifecycle in one call.
+ *
+ * Stability contract: the shape of `ScaiClient` and the `connect`
+ * signature are part of the public surface. Internal area clients
+ * (currently just `hygiene`) are exposed by reference — their own
+ * stability contract lives in `scai/hygiene`. Adding a new area client
+ * here is a public-API decision.
+ */
+export interface ScaiClient {
+    envName: string;
+    hygiene: HygieneApiClient;
+}
+export interface ConnectOptions {
+    /** Environment name from `sitecoreai.cli.json`. Defaults to `defaultEnvProfile`. */
+    envName?: string;
+    /** Override the config file path (directory or full path). Defaults to `process.cwd()`. */
+    configPath?: string;
+}
+export declare const connect: (options?: ConnectOptions) => ScaiClient;

package/dist/scripting/connect.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.connect = void 0;
+const environment_1 = require("../policy/environment");
+const client_1 = require("../hygiene/api/client");
+const connect = (options = {}) => {
+    const resolved = (0, environment_1.resolveEnvironment)({
+        config: options.configPath,
+        environmentName: options.envName,
+    });
+    const hygiene = (0, client_1.createHygieneApiClient)({
+        environment: resolved.environment,
+        request: resolved.timeoutMs ? { timeoutMs: resolved.timeoutMs } : undefined,
+    });
+    return { envName: resolved.envName, hygiene };
+};
+exports.connect = connect;

package/dist/scripting/helpers/multilist.d.ts

@@ -0,0 +1,26 @@
+import type { ScaiClient } from "../connect";
+export interface RemoveRefArgs {
+    itemId: string;
+    fieldName: string;
+    /** GUID to remove. Matched case-insensitively, with or without braces. */
+    refToRemove: string;
+    /** When false (default), no mutation is made — returns the diff only. */
+    allowWrite?: boolean;
+}
+export interface RemoveRefResult {
+    changed: boolean;
+    before: string;
+    after: string;
+    /** True when the helper made the wire call. False on dry-run or no-op. */
+    applied: boolean;
+}
+/**
+ * Remove a specific GUID from a multilist-shaped field on a single
+ * item. The match is case-insensitive and brace-tolerant — both
+ * `{ABC...}` and `abc...` shapes resolve to the same entry.
+ *
+ * Returns `changed: true` when the GUID was present in the field
+ * (regardless of `allowWrite`). `applied: true` only when the
+ * mutation actually reached the Authoring API.
+ */
+export declare const removeRef: (client: ScaiClient, args: RemoveRefArgs) => Promise<RemoveRefResult>;

package/dist/scripting/helpers/multilist.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.removeRef = void 0;
+const errors_1 = require("../../shared/errors");
+/**
+ * Multilist field utilities — composable helpers for the
+ * pipe-delimited GUID lists Sitecore uses for Multilist / Treelist /
+ * Droplink-list fields. CLI `cleanup find-replace` is regex-shaped and
+ * can't safely target a single GUID inside a delimited list (escape and
+ * trailing-pipe edge cases bite). These helpers parse the field, mutate
+ * the parsed form, and write the rejoined value back.
+ *
+ * Safe-by-default: every mutator takes `allowWrite: boolean`. When
+ * false (the default), the helper returns the diff without making the
+ * Authoring API call. Callers wire their own consent — script authors
+ * decide when to flip the flag.
+ */
+const GUID_DELIMITER = "|";
+const normalizeGuid = (raw) => raw.replace(/[{}]/g, "").trim().toLowerCase();
+const parseMultilist = (raw) => {
+    if (!raw)
+        return [];
+    return raw
+        .split(GUID_DELIMITER)
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+};
+const formatMultilist = (entries) => entries.join(GUID_DELIMITER);
+/**
+ * Remove a specific GUID from a multilist-shaped field on a single
+ * item. The match is case-insensitive and brace-tolerant — both
+ * `{ABC...}` and `abc...` shapes resolve to the same entry.
+ *
+ * Returns `changed: true` when the GUID was present in the field
+ * (regardless of `allowWrite`). `applied: true` only when the
+ * mutation actually reached the Authoring API.
+ */
+const removeRef = async (client, args) => {
+    if (!args.itemId) {
+        throw (0, errors_1.createScaiError)("removeRef requires itemId.", "INPUT_INVALID");
+    }
+    if (!args.fieldName) {
+        throw (0, errors_1.createScaiError)("removeRef requires fieldName.", "INPUT_INVALID");
+    }
+    if (!args.refToRemove) {
+        throw (0, errors_1.createScaiError)("removeRef requires refToRemove.", "INPUT_INVALID");
+    }
+    const fields = await client.hygiene.getItemFields({ itemId: args.itemId });
+    if (!fields) {
+        throw (0, errors_1.createScaiError)(`Item ${args.itemId} not found.`, "INPUT_INVALID");
+    }
+    const field = fields.find((f) => f.name === args.fieldName);
+    if (!field) {
+        throw (0, errors_1.createScaiError)(`Field '${args.fieldName}' not found on item ${args.itemId}.`, "INPUT_INVALID", {
+            hint: `Available fields: ${fields.map((f) => f.name).join(", ")}.`,
+        });
+    }
+    const before = field.value ?? "";
+    const target = normalizeGuid(args.refToRemove);
+    const entries = parseMultilist(before);
+    const filtered = entries.filter((entry) => normalizeGuid(entry) !== target);
+    const after = formatMultilist(filtered);
+    if (after === before) {
+        return { changed: false, before, after, applied: false };
+    }
+    if (!args.allowWrite) {
+        return { changed: true, before, after, applied: false };
+    }
+    await client.hygiene.updateItemFields({
+        itemId: args.itemId,
+        fields: [{ name: args.fieldName, value: after }],
+    });
+    return { changed: true, before, after, applied: true };
+};
+exports.removeRef = removeRef;

package/dist/scripting/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Public entry for `@sitecoreai-labs/sitecoreai-cli/unstable/scripting`.
+ *
+ * Ergonomic surface for ad-hoc TypeScript scripts against a scai-
+ * configured Sitecore environment. Distinct from `scai/hygiene`,
+ * `scai/deploy`, etc., which expose raw API clients — `scai/scripting`
+ * wires auth + config in one call and adds composable helpers shaped
+ * for the kinds of one-off investigations and surgical edits that
+ * don't fit any CLI command (reverse-dependency scans, multilist GUID
+ * surgery, composite cleanup flows).
+ *
+ * UNSTABLE entry: this ships under `./unstable/scripting` and carries
+ * no SemVer stability promise. `connect()` currently wires only the
+ * `hygiene` area; its return shape will grow and the helper pattern is
+ * still settling. It graduates to a stable entry in a later release.
+ *
+ * See `docs/scripting.md` for examples.
+ */
+export { connect, type ScaiClient, type ConnectOptions } from "./connect";
+export * as multilist from "./helpers/multilist";

package/dist/scripting/index.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * Public entry for `@sitecoreai-labs/sitecoreai-cli/unstable/scripting`.
+ *
+ * Ergonomic surface for ad-hoc TypeScript scripts against a scai-
+ * configured Sitecore environment. Distinct from `scai/hygiene`,
+ * `scai/deploy`, etc., which expose raw API clients — `scai/scripting`
+ * wires auth + config in one call and adds composable helpers shaped
+ * for the kinds of one-off investigations and surgical edits that
+ * don't fit any CLI command (reverse-dependency scans, multilist GUID
+ * surgery, composite cleanup flows).
+ *
+ * UNSTABLE entry: this ships under `./unstable/scripting` and carries
+ * no SemVer stability promise. `connect()` currently wires only the
+ * `hygiene` area; its return shape will grow and the helper pattern is
+ * still settling. It graduates to a stable entry in a later release.
+ *
+ * See `docs/scripting.md` for examples.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.multilist = exports.connect = void 0;
+var connect_1 = require("./connect");
+Object.defineProperty(exports, "connect", { enumerable: true, get: function () { return connect_1.connect; } });
+exports.multilist = __importStar(require("./helpers/multilist"));

package/dist/serialization/api/auth.d.ts

@@ -0,0 +1,57 @@
+import type { SitecoreApiClientOptions } from "./types";
+export type AccessTokenResult = {
+    accessToken: string;
+    refreshToken?: string;
+    expiresIn?: number;
+    tokenType?: string;
+};
+export type DeviceAuthorizationResult = {
+    deviceCode: string;
+    userCode?: string;
+    verificationUri: string;
+    verificationUriComplete?: string;
+    expiresIn: number;
+    interval: number;
+    message?: string;
+};
+export declare const requestDeviceAuthorization: (environment: SitecoreApiClientOptions, scope?: string) => Promise<DeviceAuthorizationResult>;
+export declare const pollDeviceToken: (environment: SitecoreApiClientOptions, device: DeviceAuthorizationResult) => Promise<AccessTokenResult>;
+/**
+ * Default OAuth audience for Sitecore Cloud APIs (Deploy + Authoring +
+ * Sites). When the env profile doesn't pin an explicit `audience`,
+ * Auth0 falls back to whatever default is configured for the M2M
+ * client. Some org-scoped clients are configured with internal-only
+ * audiences they aren't authorized to mint tokens for, so we always
+ * send this audience explicitly on the request.
+ */
+export declare const DEFAULT_SITECORE_API_AUDIENCE = "https://api.sitecorecloud.io";
+export declare const requestClientCredentialsToken: (environment: SitecoreApiClientOptions, scope?: string) => Promise<AccessTokenResult>;
+export declare const requestPasswordToken: (environment: SitecoreApiClientOptions, username: string, password: string, scope?: string) => Promise<AccessTokenResult>;
+/**
+ * Pure OAuth acquisition: refresh-token-on-env, then client-credentials.
+ * Does NOT touch the keychain token cache, and does NOT return the env's
+ * embedded `accessToken` literal — callers wanting the literal-or-acquired
+ * union should check `environment.accessToken` themselves first.
+ *
+ * The client-credentials mint fires whenever a `{ clientId, clientSecret }`
+ * pair resolves through the shared three-tier chain — the
+ * `SITECOREAI_ENV_<ENV>_CLIENT_SECRET` env var (bring-your-own-client),
+ * the env-scoped automation client (`automationClient` block + the
+ * `cm-client:<env>` keychain secret), or the org-scoped automation
+ * client. A resolvable automation client IS the acquisition path: there
+ * is no separate opt-in flag. `useClientCredentials` survives only as a
+ * config-file marker for the bring-your-own-client hatch — `setup env`
+ * mints an automation client without it, and that client must still
+ * work. (This was the bug: the mint was gated on `useClientCredentials`,
+ * so a scai-minted automation client could never produce a CM token.)
+ *
+ * Resolving that pair reads the OS keychain for the long-lived client
+ * secret — the one keychain touch here; the short-lived token cache is
+ * never read or written by this function (that is `getAccessToken`'s job).
+ *
+ * Library callers (orchestrators, MCP servers, tests) that bring their
+ * own token cache should call this directly. The CLI uses `getAccessToken`
+ * which adds keychain-backed caching on top.
+ */
+export declare const acquireAccessToken: (environment: SitecoreApiClientOptions) => Promise<AccessTokenResult | undefined>;
+export declare const getAccessToken: (environment: SitecoreApiClientOptions) => Promise<string | undefined>;