@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/publishing/api/auth.js

@@ -0,0 +1,173 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.acquirePublishingToken = exports.PUBLISHING_SCOPES_REQUESTED = void 0;
+const auth_1 = require("../../serialization/api/auth");
+const errors_1 = require("../../shared/errors");
+const keychain_1 = require("../../shared/keychain");
+/**
+ * OAuth scopes the SAI Publishing API requires.
+ *
+ * Per the Publishing API architect (2026-05-14):
+ *
+ *   - Every Sitecore Cloud **environment** has its own automation
+ *     client (Cloud Portal → Environments → [env] → Automation
+ *     Clients). Env-level clients carry the tenant-tier `.t` scopes
+ *     below by default. ORG-level clients (used for org/project/env
+ *     management) do NOT.
+ *   - The api-docs page lists both `.a` (admin-tier, for Pages-UI
+ *     user tokens with Organization Owner role) and `.t` (tenant-
+ *     tier, for automation clients). Use `.t` for any flow whose
+ *     credentials are scoped to a single environment.
+ *
+ *   - `xmcpub.jobs.t:r` — read publishing jobs
+ *   - `xmcpub.jobs.t:w` — create / cancel publishing jobs
+ *   - `xmcpub.queue:r`  — read the publish queue
+ *
+ * Audience: `https://api.sitecorecloud.io` (standard).
+ */
+exports.PUBLISHING_SCOPES_REQUESTED = [
+    "xmcpub.jobs.t:r",
+    "xmcpub.jobs.t:w",
+    "xmcpub.queue:r",
+];
+const M2M_SCOPE_PARAM = exports.PUBLISHING_SCOPES_REQUESTED.join(" ");
+const NO_CREDENTIALS_HINT = "Two paths work: (1) run `scai setup login -n <env>` against an env-level automation client (publishing scopes are part of the default scope set scai requests), or (2) put env-level `clientId`+`clientSecret` on this env's profile in sitecoreai.cli.json, or set `SITECOREAI_ENV_<NAME>_CLIENT_ID`/`_CLIENT_SECRET`. Create the env-level client in Cloud Portal → Environments → [env] → Automation Clients.";
+const decodeJwtPayload = (token) => {
+    const parts = token.split(".");
+    if (parts.length !== 3) {
+        return undefined;
+    }
+    const b64 = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+    const padded = b64 + "==".slice(0, (4 - (b64.length % 4)) % 4);
+    try {
+        return JSON.parse(Buffer.from(padded, "base64").toString("utf8"));
+    }
+    catch {
+        return undefined;
+    }
+};
+const extractScopes = (token) => {
+    const payload = decodeJwtPayload(token);
+    if (!payload)
+        return [];
+    const raw = typeof payload.scope === "string"
+        ? payload.scope
+        : Array.isArray(payload.scp)
+            ? payload.scp.join(" ")
+            : "";
+    return raw.split(/\s+/).filter(Boolean);
+};
+const hasPublishingScopes = (token) => {
+    const granted = new Set(extractScopes(token));
+    return exports.PUBLISHING_SCOPES_REQUESTED.every((s) => granted.has(s));
+};
+/**
+ * 60-second safety margin: a token whose `exp` falls inside this window
+ * is treated as expired so we don't hand a soon-to-be-invalid Bearer to
+ * a long-running publish call. Bumped up from the typical 5-15s window
+ * because publish-API requests can hold the connection for tens of
+ * seconds and we'd rather mint fresh than 401 mid-request.
+ */
+const TOKEN_EXPIRY_MARGIN_S = 60;
+const isTokenExpired = (token) => {
+    const payload = decodeJwtPayload(token);
+    if (!payload) {
+        return false; // can't decode → trust the caller to handle 401
+    }
+    const exp = typeof payload.exp === "number" ? payload.exp : Number(payload.exp);
+    if (!Number.isFinite(exp)) {
+        return false;
+    }
+    const nowS = Math.floor(Date.now() / 1000);
+    return exp - nowS <= TOKEN_EXPIRY_MARGIN_S;
+};
+/** Cache entry is usable iff it has the publishing scopes AND isn't
+ *  inside the expiry safety margin. Either condition failing falls
+ *  through to the next resolution step (deploy-token reuse or fresh
+ *  M2M mint), not a throw — keeps a stale cache from blocking a valid
+ *  call when fresh credentials are available. */
+const isUsablePublishingToken = (token) => hasPublishingScopes(token) && !isTokenExpired(token);
+/**
+ * Build a specific, actionable error when a minted token lacks
+ * publishing scopes. Decodes the token, names what it DID get, and
+ * infers the likely credential class (org-level vs misconfigured)
+ * so the operator knows what to fix in the Cloud Portal.
+ */
+const buildScopeMissingError = (envName, token) => {
+    const granted = extractScopes(token);
+    const orgLevelMarkers = granted.filter((s) => s.startsWith("xmclouddeploy."));
+    const looksLikeOrg = orgLevelMarkers.some((s) => s.includes("organizations:") || s.includes("projects:")) &&
+        !granted.some((s) => s.startsWith("xmcpub."));
+    const grantSummary = granted.length > 0 ? granted.join(", ") : "(no scope claim in token)";
+    const inference = looksLikeOrg
+        ? "The credentials look like an ORG-LEVEL automation client (carries org/project management scopes but not xmcpub.*). The Publishing API requires an ENVIRONMENT-LEVEL automation client."
+        : "The credentials don't carry the expected publishing scopes for this environment.";
+    const envSlug = envName.toUpperCase().replace(/[^A-Z0-9]+/g, "_");
+    return (0, errors_1.createScaiError)(`Token minted for env '${envName}' but missing publishing scopes. Expected: ${exports.PUBLISHING_SCOPES_REQUESTED.join(", ")}. Granted: ${grantSummary}.`, "AUTH_REQUIRED", {
+        hint: `${inference} In the Sitecore Cloud Portal: Environments → ${envName} → Automation Clients → Create a new client (env-level), then re-run \`scai setup login -n ${envName}\` or set SITECOREAI_ENV_${envSlug}_CLIENT_ID and _CLIENT_SECRET.`,
+    });
+};
+/**
+ * Returns a Bearer JWT for the SAI Publishing API.
+ *
+ * Resolution order, cheapest first:
+ *
+ *   1. Cached publishing token in the keychain — set by a previous
+ *      successful mint via this function. Reused until expiry / clear.
+ *   2. The deploy token in the keychain, IF its scope claim already
+ *      includes `xmcpub.jobs.t:*`. This is the zero-config path:
+ *      operators who logged in interactively against an env-level
+ *      automation client get a single token covering both deploy
+ *      and publishing scopes (scai's default scope set requests
+ *      both — see `SCAI_API_SCOPES`).
+ *   3. Fresh M2M mint via the env's `clientId` + `clientSecret`,
+ *      explicitly requesting publishing scopes. Cached on success.
+ *
+ * Refuses with `AUTH_REQUIRED` when none of these paths produces a
+ * token carrying the required scopes. The error message decodes the
+ * granted-scope set and infers the credential class so operators know
+ * whether they need an env-level client or just need to re-login.
+ */
+const acquirePublishingToken = async (options) => {
+    // 1. Cached publishing-specific token.
+    const cachedPublishing = await (0, keychain_1.getPublishingToken)(options.envName);
+    if (cachedPublishing && isUsablePublishingToken(cachedPublishing)) {
+        return cachedPublishing;
+    }
+    // 2. Deploy token reused if it carries publishing scopes (i.e. the
+    //    operator logged in against an env-level automation client and
+    //    scai's default scope set picked up the `.t` grants).
+    const deployToken = await (0, keychain_1.getDeployToken)(options.envName);
+    if (deployToken && isUsablePublishingToken(deployToken)) {
+        return deployToken;
+    }
+    // 3. Fresh M2M mint via env-level client credentials.
+    const env = options.environment;
+    if (env.clientId && env.clientSecret && env.authority) {
+        let result;
+        try {
+            result = await (0, auth_1.requestClientCredentialsToken)(env, M2M_SCOPE_PARAM);
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            throw (0, errors_1.createScaiError)(`Auth0 refused the publishing scope request for env '${options.envName}'.`, "AUTH_REQUIRED", { hint: `Auth0 error: ${detail}. ${NO_CREDENTIALS_HINT}` });
+        }
+        if (!result.accessToken) {
+            throw (0, errors_1.createScaiError)(`Sitecore did not return an access token for env '${options.envName}'.`, "AUTH_REQUIRED", { hint: NO_CREDENTIALS_HINT });
+        }
+        if (!hasPublishingScopes(result.accessToken)) {
+            throw buildScopeMissingError(options.envName, result.accessToken);
+        }
+        await (0, keychain_1.setPublishingToken)(options.envName, result.accessToken);
+        return result.accessToken;
+    }
+    // Last-ditch: an existing token exists but lacks publishing scopes.
+    // Surface the scope-missing diagnostic against whichever token we
+    // have so the operator can act on it.
+    const diagToken = cachedPublishing ?? deployToken;
+    if (diagToken) {
+        throw buildScopeMissingError(options.envName, diagToken);
+    }
+    throw (0, errors_1.createScaiError)(`No publishing-scoped token available for env '${options.envName}'.`, "AUTH_REQUIRED", { hint: NO_CREDENTIALS_HINT });
+};
+exports.acquirePublishingToken = acquirePublishingToken;

package/dist/publishing/api/client.d.ts

@@ -0,0 +1,5 @@
+import type { CreatePublishJobRequest, ListPublishJobsQuery, PublishJob, PublishingApiClientOptions } from "./types";
+export declare const submitPublishJob: (client: PublishingApiClientOptions, request: CreatePublishJobRequest) => Promise<PublishJob>;
+export declare const getPublishJob: (client: PublishingApiClientOptions, jobId: string) => Promise<PublishJob>;
+export declare const cancelPublishJob: (client: PublishingApiClientOptions, jobId: string) => Promise<void>;
+export declare const listPublishJobs: (client: PublishingApiClientOptions, options?: ListPublishJobsQuery) => Promise<PublishJob[]>;

package/dist/publishing/api/client.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listPublishJobs = exports.cancelPublishJob = exports.getPublishJob = exports.submitPublishJob = void 0;
+const errors_1 = require("../../shared/errors");
+const DEFAULT_BASE_URL = "https://edge-platform.sitecorecloud.io";
+const JOBS_PATH = "/authoring/publishing/v1/jobs";
+const buildQueryString = (query) => {
+    if (!query)
+        return "";
+    const parts = [];
+    for (const [k, v] of Object.entries(query)) {
+        if (v === undefined)
+            continue;
+        if (Array.isArray(v)) {
+            for (const item of v) {
+                parts.push(`${encodeURIComponent(k)}=${encodeURIComponent(item)}`);
+            }
+        }
+        else {
+            parts.push(`${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`);
+        }
+    }
+    return parts.length > 0 ? `?${parts.join("&")}` : "";
+};
+const fetchPublishingApi = async (client, options) => {
+    const baseUrl = client.baseUrl ?? DEFAULT_BASE_URL;
+    const url = `${baseUrl}${JOBS_PATH}${options.path}${buildQueryString(options.query)}`;
+    const controller = client.timeoutMs ? new AbortController() : undefined;
+    const timer = controller && client.timeoutMs
+        ? setTimeout(() => controller.abort(), client.timeoutMs)
+        : undefined;
+    try {
+        const response = await fetch(url, {
+            method: options.method,
+            headers: {
+                Authorization: `Bearer ${client.accessToken}`,
+                Accept: "application/json",
+                ...(options.body ? { "Content-Type": "application/json" } : {}),
+            },
+            body: options.body ? JSON.stringify(options.body) : undefined,
+            signal: controller?.signal,
+        });
+        if (response.status === 202 || response.status === 204) {
+            return undefined;
+        }
+        const text = await response.text().catch(() => "");
+        if (!response.ok) {
+            const code = response.status === 401 || response.status === 403 ? "AUTH_REQUIRED" : "NETWORK";
+            const hint = response.status === 403
+                ? "The token is valid but the API refused the call. Verify the env-level automation client has xmcpub.jobs.t:r/w grants. Body: " +
+                    text.slice(0, 400)
+                : text.slice(0, 400) || response.statusText || undefined;
+            throw (0, errors_1.createScaiError)(`Publishing API ${options.method} ${url} returned ${response.status}.`, code, { hint });
+        }
+        if (!text)
+            return undefined;
+        return JSON.parse(text);
+    }
+    finally {
+        if (timer) {
+            clearTimeout(timer);
+        }
+    }
+};
+const STATUS_TO_STATE = {
+    Queued: "queued",
+    Running: "running",
+    Completed: "completed",
+    Failed: "failed",
+    Canceled: "cancelled",
+    Canceling: "cancelling",
+};
+const normalizeState = (raw) => STATUS_TO_STATE[(raw ?? "Queued")] ?? "queued";
+const normalizeJob = (raw) => {
+    const stats = (raw.statistics ?? {});
+    // The Publishing API exposes statistics under two field sets:
+    //   - flat `processedCount` / `totalCount` (older deployments)
+    //   - rich `itemsSent` / `itemsProcessed` / `itemsFailed` (observed
+    //     live against Agents 2026-05-14)
+    // Prefer the rich set; fall back to flat.
+    const itemsProcessed = typeof stats.itemsProcessed === "number" ? stats.itemsProcessed : undefined;
+    const itemsSent = typeof stats.itemsSent === "number" ? stats.itemsSent : undefined;
+    const flatProcessed = typeof stats.processedCount === "number" ? stats.processedCount : undefined;
+    const flatTotal = typeof stats.totalCount === "number" ? stats.totalCount : undefined;
+    const state = normalizeState(raw.system?.status);
+    // `permissions.canCancel` is a *permission* flag (caller has cancel
+    // rights), not a *state* flag (the job is currently cancellable).
+    // The API returns `true` even on completed jobs because permission
+    // doesn't change. Combine both so callers get a useful "actually
+    // cancellable now" signal.
+    const stateIsCancellable = state === "queued" || state === "running";
+    return {
+        id: raw.id,
+        state,
+        name: raw.name ?? undefined,
+        source: raw.source ?? undefined,
+        processedCount: itemsProcessed ?? flatProcessed,
+        totalCount: itemsSent ?? flatTotal,
+        startedAt: raw.system?.startTime ?? undefined,
+        completedAt: raw.system?.finishTime ?? undefined,
+        canCancel: Boolean(raw.permissions?.canCancel) && stateIsCancellable,
+        raw,
+    };
+};
+const submitPublishJob = async (client, request) => {
+    const raw = (await fetchPublishingApi(client, {
+        method: "POST",
+        path: "",
+        body: request,
+    }));
+    return normalizeJob(raw);
+};
+exports.submitPublishJob = submitPublishJob;
+const getPublishJob = async (client, jobId) => {
+    if (!jobId) {
+        throw (0, errors_1.createScaiError)("Publish job id is required.", "INPUT_INVALID");
+    }
+    const raw = (await fetchPublishingApi(client, {
+        method: "GET",
+        path: `/${encodeURIComponent(jobId)}`,
+    }));
+    return normalizeJob(raw);
+};
+exports.getPublishJob = getPublishJob;
+const cancelPublishJob = async (client, jobId) => {
+    if (!jobId) {
+        throw (0, errors_1.createScaiError)("Publish job id is required.", "INPUT_INVALID");
+    }
+    await fetchPublishingApi(client, {
+        method: "POST",
+        path: `/${encodeURIComponent(jobId)}/cancel`,
+    });
+};
+exports.cancelPublishJob = cancelPublishJob;
+const listPublishJobs = async (client, options = {}) => {
+    const query = {};
+    if (options.pageNumber !== undefined)
+        query.pageNumber = options.pageNumber;
+    if (options.pageSize !== undefined)
+        query.pageSize = options.pageSize;
+    if (options.statuses?.length)
+        query["system.status"] = options.statuses;
+    if (options.source?.length)
+        query.source = options.source;
+    const raw = (await fetchPublishingApi(client, {
+        method: "GET",
+        path: "",
+        query,
+    }));
+    const list = Array.isArray(raw) ? raw : (raw?.data ?? []);
+    return list.map(normalizeJob);
+};
+exports.listPublishJobs = listPublishJobs;

package/dist/publishing/api/languages.d.ts

@@ -0,0 +1,61 @@
+import type { EnvironmentConfiguration } from "../../config/types";
+import type { Logger } from "../../shared/logger";
+/**
+ * Sites API helpers for resolving per-site or tenant-wide publish
+ * languages. Used by `scai content publish *` verbs to back the explicit
+ * `--languages-from-site <name>` and `--all-tenant-languages` flags
+ * (no implicit resolution — each flag does exactly what its name
+ * says).
+ *
+ * Auth: the Sites API uses `xmcloud.cm:admin` (already in scai's
+ * deploy token scope set). No additional grants required — same
+ * credentials that mint the publishing token cover site lookups.
+ */
+/**
+ * Look up a single site by exact `name` and return its configured
+ * languages. Throws if the site doesn't exist in the env so the
+ * caller surfaces a clear error before any publish-API write.
+ */
+export declare const lookupSiteLanguages: (environment: EnvironmentConfiguration, siteName: string) => Promise<string[]>;
+/**
+ * Look up the env's tenant-wide language inventory (all languages
+ * registered in the tenant, regardless of which sites use them).
+ * Useful as a fallback when an operator wants "every language the
+ * tenant supports."
+ */
+/**
+ * The three mutually-exclusive locale-source flags every publish-side
+ * task accepts. Pass exactly one (or none, to let the Publishing API
+ * use the env's configured publish languages). `resolvePublishingLocales`
+ * enforces the exclusivity contract and surfaces the resolved set in
+ * non-quiet output so operators never wonder which locales the publish
+ * job will see.
+ */
+export interface PublishLocaleOptions {
+    /** Literal language list (e.g. `["en-US"]`). */
+    languages?: string[];
+    /** Resolve from the named site's `languages` array via Sites API. */
+    languagesFromSite?: string;
+    /** Resolve from the tenant-wide `listLanguages` set. */
+    allTenantLanguages?: boolean;
+}
+/**
+ * Pick the locale list for a publishing call.
+ *
+ * Exactly one of the three flags may be set. When none is set, scai
+ * auto-resolves the tenant-wide language inventory (same as
+ * `--all-tenant-languages`) and logs it as "auto-resolved" so the
+ * operator sees what's being sent. This default exists because the
+ * Publishing API rejects requests with no locales — empirically
+ * verified 2026-05-14 against the agents env, the request returns
+ * `400 "Publishing locales should be specified either in the job
+ * options or per item"`. The `[]` fall-through (claimed by the prior
+ * docstring to use "env-configured defaults") is a phantom path the
+ * API doesn't support, so we close it here.
+ *
+ * If the tenant truly has zero languages (misconfigured env), the
+ * function still returns `[]` and surfaces a warning — the publish
+ * will fail at the API with a clearer error than scai could synthesize.
+ */
+export declare const resolvePublishingLocales: (logger: Logger, environment: EnvironmentConfiguration, options: PublishLocaleOptions) => Promise<string[]>;
+export declare const lookupTenantLanguages: (environment: EnvironmentConfiguration) => Promise<string[]>;

package/dist/publishing/api/languages.js

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lookupTenantLanguages = exports.resolvePublishingLocales = exports.lookupSiteLanguages = void 0;
+const auth_1 = require("../../serialization/api/auth");
+const languages_1 = require("../../sites/api/languages");
+const sites_1 = require("../../sites/api/sites");
+const errors_1 = require("../../shared/errors");
+/**
+ * Sites API helpers for resolving per-site or tenant-wide publish
+ * languages. Used by `scai content publish *` verbs to back the explicit
+ * `--languages-from-site <name>` and `--all-tenant-languages` flags
+ * (no implicit resolution — each flag does exactly what its name
+ * says).
+ *
+ * Auth: the Sites API uses `xmcloud.cm:admin` (already in scai's
+ * deploy token scope set). No additional grants required — same
+ * credentials that mint the publishing token cover site lookups.
+ */
+/**
+ * Look up a single site by exact `name` and return its configured
+ * languages. Throws if the site doesn't exist in the env so the
+ * caller surfaces a clear error before any publish-API write.
+ */
+const lookupSiteLanguages = async (environment, siteName) => {
+    const accessToken = await (0, auth_1.getAccessToken)(environment);
+    if (!accessToken) {
+        throw (0, errors_1.createScaiError)(`Could not acquire an access token for site lookup.`, "AUTH_REQUIRED", {
+            hint: `Run 'scai setup login -n <env>' first; the Sites API needs the same xmcloud.cm:admin scope scai uses for deploy.`,
+        });
+    }
+    const sites = await (0, sites_1.listSites)({ accessToken });
+    const match = sites.find((s) => s.name === siteName);
+    if (!match) {
+        const available = sites
+            .map((s) => s.name)
+            .filter((n) => Boolean(n))
+            .slice(0, 12);
+        throw (0, errors_1.createScaiError)(`Site '${siteName}' not found in this env.`, "INPUT_INVALID", {
+            hint: `Available sites: ${available.join(", ")}${sites.length > available.length ? ` (and ${sites.length - available.length} more)` : ""}.`,
+        });
+    }
+    return (match.languages ?? []).filter((l) => Boolean(l));
+};
+exports.lookupSiteLanguages = lookupSiteLanguages;
+/**
+ * Pick the locale list for a publishing call.
+ *
+ * Exactly one of the three flags may be set. When none is set, scai
+ * auto-resolves the tenant-wide language inventory (same as
+ * `--all-tenant-languages`) and logs it as "auto-resolved" so the
+ * operator sees what's being sent. This default exists because the
+ * Publishing API rejects requests with no locales — empirically
+ * verified 2026-05-14 against the agents env, the request returns
+ * `400 "Publishing locales should be specified either in the job
+ * options or per item"`. The `[]` fall-through (claimed by the prior
+ * docstring to use "env-configured defaults") is a phantom path the
+ * API doesn't support, so we close it here.
+ *
+ * If the tenant truly has zero languages (misconfigured env), the
+ * function still returns `[]` and surfaces a warning — the publish
+ * will fail at the API with a clearer error than scai could synthesize.
+ */
+const resolvePublishingLocales = async (logger, environment, options) => {
+    const flagsSet = [
+        options.languages && options.languages.length > 0 ? "--languages" : null,
+        options.languagesFromSite ? "--languages-from-site" : null,
+        options.allTenantLanguages ? "--all-tenant-languages" : null,
+    ].filter((s) => s !== null);
+    if (flagsSet.length > 1) {
+        throw (0, errors_1.createScaiError)(`Locale source is over-specified: ${flagsSet.join(", ")}. Pass exactly one.`, "INPUT_INVALID");
+    }
+    if (options.languages && options.languages.length > 0) {
+        logger.info(`Locales: ${options.languages.join(", ")} (literal)`, "cyan");
+        return options.languages;
+    }
+    if (options.languagesFromSite) {
+        logger.info(`Locales: resolving from site '${options.languagesFromSite}' via Sites API...`, "gray");
+        const resolved = await (0, exports.lookupSiteLanguages)(environment, options.languagesFromSite);
+        if (resolved.length === 0) {
+            throw (0, errors_1.createScaiError)(`Site '${options.languagesFromSite}' has no configured languages.`, "INPUT_INVALID", { hint: "Add a language to the site or pass --languages explicitly." });
+        }
+        logger.info(`Locales: ${resolved.join(", ")} (from site '${options.languagesFromSite}')`, "cyan");
+        return resolved;
+    }
+    if (options.allTenantLanguages) {
+        logger.info(`Locales: resolving from tenant-wide listLanguages...`, "gray");
+        const resolved = await (0, exports.lookupTenantLanguages)(environment);
+        if (resolved.length === 0) {
+            throw (0, errors_1.createScaiError)("Tenant has no registered languages.", "INPUT_INVALID");
+        }
+        logger.info(`Locales: ${resolved.join(", ")} (tenant-wide)`, "cyan");
+        return resolved;
+    }
+    // No explicit flag → auto-resolve tenant languages. The Publishing
+    // API has no implicit default, so we make the default explicit and
+    // log it. Operator can override with --languages or scope with
+    // --languages-from-site.
+    logger.info(`Locales: no --languages flag — auto-resolving from tenant-wide listLanguages...`, "gray");
+    const resolved = await (0, exports.lookupTenantLanguages)(environment);
+    if (resolved.length === 0) {
+        logger.warn(`Tenant has no registered languages — the publish API will reject this request. Add at least one language to the tenant or pass --languages <list>.`, "yellow");
+        return [];
+    }
+    logger.info(`Locales: ${resolved.join(", ")} (auto-resolved tenant-wide; pass --languages to override or --languages-from-site to narrow)`, "cyan");
+    return resolved;
+};
+exports.resolvePublishingLocales = resolvePublishingLocales;
+const lookupTenantLanguages = async (environment) => {
+    const accessToken = await (0, auth_1.getAccessToken)(environment);
+    if (!accessToken) {
+        throw (0, errors_1.createScaiError)(`Could not acquire an access token for language lookup.`, "AUTH_REQUIRED");
+    }
+    const languages = await (0, languages_1.listLanguages)({ accessToken });
+    return languages.map((l) => l.name).filter((n) => Boolean(n));
+};
+exports.lookupTenantLanguages = lookupTenantLanguages;

package/dist/publishing/api/path-resolver.d.ts

@@ -0,0 +1,10 @@
+import type { EnvironmentConfiguration } from "../../config/types";
+interface ResolvedItem {
+    path: string;
+    itemId: string;
+}
+interface ResolveItemPathsResult {
+    resolved: ResolvedItem[];
+}
+export declare const resolveItemPathsToIds: (environment: EnvironmentConfiguration, paths: string[]) => Promise<ResolveItemPathsResult>;
+export {};

package/dist/publishing/api/path-resolver.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveItemPathsToIds = void 0;
+const graphql_1 = require("../../recipe/api/graphql");
+const errors_1 = require("../../shared/errors");
+/**
+ * Resolve Sitecore content-tree paths to item IDs via the Authoring
+ * GraphQL `item(where: { path: ... })` query.
+ *
+ * The Publishing API only accepts item IDs in `ItemModel.id`; this
+ * helper bridges path-based addressing so `scai content publish item --paths`
+ * works. Batches multiple paths into a single GraphQL request using
+ * field aliases (`i0: item(...) { itemId }`, `i1: ...`) — same
+ * pattern the recipe runtime uses internally (see
+ * `src/recipe/api/authoring-client.ts:getItemsByPaths`), but without
+ * the recipe workspace coupling.
+ *
+ * Errors with `INPUT_INVALID` listing every path that didn't resolve,
+ * so an operator publishing a batch sees all bad inputs at once
+ * rather than playing whack-a-mole.
+ */
+const BATCH_SIZE = 25;
+const buildBatchQuery = (count) => {
+    const aliases = [];
+    for (let i = 0; i < count; i += 1) {
+        aliases.push(`  i${i}: item(where: { path: $p${i} }) { itemId path }`);
+    }
+    const vars = Array.from({ length: count }, (_, i) => `$p${i}: String!`).join(", ");
+    return `query Batch(${vars}) {\n${aliases.join("\n")}\n}`;
+};
+const resolveItemPathsToIds = async (environment, paths) => {
+    if (paths.length === 0) {
+        return { resolved: [] };
+    }
+    // De-duplicate while preserving order so the returned map is
+    // predictable for the caller.
+    const seen = new Set();
+    const uniquePaths = [];
+    for (const p of paths) {
+        if (!seen.has(p)) {
+            seen.add(p);
+            uniquePaths.push(p);
+        }
+    }
+    const resolved = new Map();
+    const missing = [];
+    for (let offset = 0; offset < uniquePaths.length; offset += BATCH_SIZE) {
+        const batch = uniquePaths.slice(offset, offset + BATCH_SIZE);
+        const query = buildBatchQuery(batch.length);
+        const variables = {};
+        for (let i = 0; i < batch.length; i += 1) {
+            variables[`p${i}`] = batch[i];
+        }
+        const data = await (0, graphql_1.runAuthoringGraphQL)(environment, query, variables);
+        for (let i = 0; i < batch.length; i += 1) {
+            const node = data[`i${i}`];
+            if (node?.itemId) {
+                resolved.set(batch[i], node.itemId);
+            }
+            else {
+                missing.push(batch[i]);
+            }
+        }
+    }
+    if (missing.length > 0) {
+        throw (0, errors_1.createScaiError)(`Could not resolve ${missing.length} item path(s) to IDs.`, "INPUT_INVALID", {
+            hint: `Paths not found in the env's content tree: ${missing.join(", ")}. Verify the paths exist and that the authenticated client has read access.`,
+        });
+    }
+    // Re-emit in caller-input order so multi-item publishing audits in a
+    // predictable order.
+    return {
+        resolved: paths.map((path) => ({ path, itemId: resolved.get(path) })),
+    };
+};
+exports.resolveItemPathsToIds = resolveItemPathsToIds;

package/dist/publishing/api/sites.d.ts

@@ -0,0 +1,23 @@
+import type { EnvironmentConfiguration } from "../../config/types";
+/**
+ * Resolve a site name to its content-tree root item — the canonical
+ * target for "publish this site" or "unpublish this site." Composes
+ * scai's existing `discoverSites` (Authoring GraphQL tree walk for
+ * `/sitecore/content/<tenant>/<site>`) with the path → itemId
+ * resolver shipped in PR 2b.
+ *
+ * Two round trips total per call (one for the tenant/site walk, one
+ * for the path → itemId batch query). Callers using `--site` on a
+ * single command pay this once.
+ *
+ * Returns the resolved site, its content-tree path, and the item id.
+ * Throws `INPUT_INVALID` with a helpful hint listing available sites
+ * when the requested name doesn't exist in the tenant.
+ */
+export interface ResolvedSiteRoot {
+    siteName: string;
+    tenantName: string;
+    path: string;
+    itemId: string;
+}
+export declare const resolveSiteRoot: (environment: EnvironmentConfiguration, siteName: string) => Promise<ResolvedSiteRoot>;

package/dist/publishing/api/sites.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveSiteRoot = void 0;
+const site_discovery_1 = require("../../recipe/api/site-discovery");
+const errors_1 = require("../../shared/errors");
+const path_resolver_1 = require("./path-resolver");
+const resolveSiteRoot = async (environment, siteName) => {
+    const sites = await (0, site_discovery_1.discoverSites)(environment);
+    const match = sites.find((s) => s.name === siteName);
+    if (!match) {
+        const available = sites
+            .map((s) => s.name)
+            .filter((n) => Boolean(n))
+            .slice(0, 12);
+        throw (0, errors_1.createScaiError)(`Site '${siteName}' not found in the content tree.`, "INPUT_INVALID", {
+            hint: `Available sites: ${available.join(", ")}${sites.length > available.length ? ` (and ${sites.length - available.length} more)` : ""}. Site discovery walks /sitecore/content/<tenant>/<site> — make sure the site lives under that convention.`,
+        });
+    }
+    const { resolved } = await (0, path_resolver_1.resolveItemPathsToIds)(environment, [match.path]);
+    return {
+        siteName: match.name,
+        tenantName: match.tenantName,
+        path: match.path,
+        itemId: resolved[0].itemId,
+    };
+};
+exports.resolveSiteRoot = resolveSiteRoot;