@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

package/dist/publishing/tasks/all.js

@@ -0,0 +1,234 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runPublishAll = void 0;
+const logger_1 = require("../../shared/logger");
+const errors_1 = require("../../shared/errors");
+const environment_1 = require("../../policy/environment");
+const prompt_1 = require("../../shared/prompt");
+const auth_1 = require("../api/auth");
+const client_1 = require("../api/client");
+const languages_1 = require("../api/languages");
+const publish_consent_1 = require("../../shared/publish-consent");
+const publish_audit_1 = require("../../shared/publish-audit");
+const job_watcher_1 = require("../job-watcher");
+const toLogger = (options) => new logger_1.Logger(Boolean(options.verbose), Boolean(options.trace), Boolean(options.json), Boolean(options.quiet), options.logFile ?? process.env.SITECOREAI_LOG_FILE);
+/**
+ * Find the most recent successfully-completed whole-environment publish
+ * job for an env. Used in the dry-run pre-flight to surface the
+ * "modified since" baseline for Smart mode.
+ *
+ * Filters server-side by `source=scai` + `system.status=Completed`,
+ * then client-side by whole-env shape (`xmc.site` set, `xmc.items`
+ * unset) and finally takes the freshest `finishTime`. Returns
+ * `undefined` when no eligible job exists (first-ever publish to the
+ * env), in which case the dry-run prints a gentle "no prior publish"
+ * note instead of a misleading baseline.
+ *
+ * Failure during the lookup is non-fatal — the dry-run continues with
+ * a "could not resolve" note, since this is advisory information.
+ */
+const findLastWholeEnvPublish = async (client) => {
+    const completed = await (0, client_1.listPublishJobs)(client, {
+        statuses: ["Completed"],
+        source: ["scai"],
+        pageSize: 50,
+    });
+    // The API normalizes our `xmc: { site: { mode } }` request body into
+    // a flattened `xmc: { type: "Site", mode, locales }` discriminator on
+    // the response side. Match on either shape to handle both submitted-
+    // by-scai jobs (nested) and re-read jobs (flat); the discriminator
+    // that holds across both is `type === "Site"` OR the nested `site`
+    // object.
+    const wholeEnv = completed.filter((j) => {
+        const xmc = j.raw.options?.xmc;
+        if (!xmc)
+            return false;
+        if (xmc.items)
+            return false;
+        return Boolean(xmc.site) || xmc.type === "Site";
+    });
+    if (wholeEnv.length === 0) {
+        return undefined;
+    }
+    return wholeEnv.reduce((latest, candidate) => {
+        const latestT = latest.completedAt ?? latest.raw.system?.finishTime ?? "";
+        const candT = candidate.completedAt ?? candidate.raw.system?.finishTime ?? "";
+        return candT > latestT ? candidate : latest;
+    });
+};
+const formatItemsSent = (job) => {
+    const stats = (job.raw.statistics ?? {});
+    const itemsSent = typeof stats.itemsSent === "number"
+        ? stats.itemsSent
+        : typeof stats.processedCount === "number"
+            ? stats.processedCount
+            : undefined;
+    return itemsSent !== undefined ? String(itemsSent) : undefined;
+};
+const runPublishAll = async (options) => {
+    const logger = toLogger(options);
+    const { envName, environment, timeoutMs } = (0, environment_1.resolveEnvironment)(options);
+    const mode = options.mode ?? "Republish";
+    const target = "Edge";
+    const languages = await (0, languages_1.resolvePublishingLocales)(logger, environment, options);
+    const scope = {
+        envName,
+        resolvedTenantId: environment.tenantId,
+        target,
+        kind: "full",
+        languages,
+    };
+    const scopeHash = (0, publish_consent_1.computeScopeHash)(scope);
+    const whatIf = options.allowWrite ? Boolean(options.whatIf) : true;
+    if (whatIf) {
+        logger.warn(`⚠️  publish all is a whole-environment republish to ${target}. This will republish EVERY item across every site in env '${envName}'.`, "yellow");
+        logger.info(`Environment:   ${envName}`, "cyan");
+        if (environment.tenantId) {
+            logger.info(`Tenant:        ${environment.tenantId}`, "gray");
+        }
+        logger.info(`Mode:          ${mode}`, "gray");
+        logger.info(`Languages:     ${languages.length > 0 ? languages.join(", ") : "(default)"}`, "gray");
+        // Pre-flight: (1) surface the most recent whole-env publish as a
+        // "modified since" baseline for Smart mode; (2) warn when another
+        // whole-env publish is already queued or running, since the API
+        // serializes these (verified 2026-05-14 — second submission waited
+        // ~80s behind the first). Both checks share one token acquisition;
+        // failure is non-fatal (advisory information only).
+        try {
+            const accessToken = await (0, auth_1.acquirePublishingToken)({ envName, environment });
+            const client = { accessToken, timeoutMs };
+            const lastPublish = await findLastWholeEnvPublish(client);
+            if (lastPublish) {
+                const itemsSent = formatItemsSent(lastPublish);
+                const ts = lastPublish.completedAt ?? lastPublish.raw.system?.finishTime ?? "(time unknown)";
+                logger.info(`Last publish:  ${ts} (${lastPublish.id})`, "gray");
+                if (itemsSent !== undefined) {
+                    logger.info(`               sent ${itemsSent} item(s) — Smart mode will re-emit items modified since`, "gray");
+                }
+            }
+            else {
+                logger.info(`Last publish:  (no prior whole-env publish recorded for this env)`, "gray");
+            }
+            const inflight = await (0, client_1.listPublishJobs)(client, {
+                statuses: ["Queued", "Running"],
+            });
+            const inflightWholeEnv = inflight.find((j) => {
+                const xmc = j.raw.options?.xmc;
+                if (!xmc || xmc.items)
+                    return false;
+                return Boolean(xmc.site) || xmc.type === "Site";
+            });
+            if (inflightWholeEnv) {
+                logger.warn(`⚠️  Another whole-env publish is already ${inflightWholeEnv.state} (${inflightWholeEnv.id}). The API serializes these; your job will queue behind it.`, "yellow");
+            }
+        }
+        catch {
+            // Couldn't acquire token or list jobs — skip the pre-flight
+            // info. Dry-run is still useful without it.
+        }
+        const token = (0, publish_consent_1.mintScopeToken)(scope);
+        logger.info("", "gray");
+        logger.info(`Scope token (TTL ${publish_consent_1.SCOPE_TOKEN_TTL_MS / 1000}s):`, "gray");
+        process.stdout.write(`${token}\n`);
+        logger.info("", "gray");
+        logger.info(`To execute: rerun with --allow-write --confirm-token ${token}.`, "gray");
+        logger.info(`You will also be prompted to type the env name '${envName}' verbatim.`, "yellow");
+        return;
+    }
+    // Real call — Tier 2 always requires --confirm-token AND an env-name
+    // echo. No --yes fallback, regardless of whether the env is flagged
+    // production: typing "all" instead of "item" is itself a failure
+    // mode this gate catches.
+    if (!options.confirmToken) {
+        throw (0, errors_1.createScaiError)(`publish all always requires --confirm-token, even on non-production envs.`, "INPUT_INVALID", {
+            hint: "Run the same command without --allow-write to get a scope token, then pass --confirm-token <token>.",
+        });
+    }
+    const verification = (0, publish_consent_1.verifyScopeToken)(options.confirmToken, scope);
+    if (!verification.ok) {
+        throw (0, errors_1.createScaiError)(`Scope token rejected (${verification.reason}).`, "INPUT_INVALID", {
+            hint: "Re-run the dry-run to mint a fresh token.",
+        });
+    }
+    // Env-name typed confirmation. CI can bypass via --yes (still
+    // requires --confirm-token; the env-name echo is the additional
+    // operator-attention check).
+    if (!options.yes) {
+        if (options.nonInteractive) {
+            throw (0, errors_1.createScaiError)("publish all (whole-environment) in non-interactive mode requires --yes alongside --confirm-token.", "INPUT_INVALID");
+        }
+        const typed = await (0, prompt_1.promptText)(`Type the env name '${envName}' to confirm a whole-environment republish:`);
+        if (typed !== envName) {
+            throw (0, errors_1.createScaiError)(`Confirmation mismatch: typed '${typed}', expected '${envName}'. Aborting.`, "INPUT_INVALID");
+        }
+    }
+    const accessToken = await (0, auth_1.acquirePublishingToken)({ envName, environment });
+    const client = { accessToken, timeoutMs };
+    const caller = { type: "human", via: "cli" };
+    const request = {
+        name: options.name ?? `scai content publish all (${envName})`,
+        source: options.source ?? "scai",
+        options: {
+            xmc: {
+                locales: languages.length > 0 ? languages : undefined,
+                site: { mode },
+            },
+        },
+    };
+    try {
+        const job = await (0, client_1.submitPublishJob)(client, request);
+        (0, publish_audit_1.recordPublishAudit)({
+            ts: new Date().toISOString(),
+            command: "publish all",
+            caller,
+            scope,
+            risk: "high",
+            scopeHash,
+            scopeToken: options.confirmToken,
+            jobId: job.id,
+            outcome: "ok",
+        });
+        if (!logger.isJson()) {
+            logger.info(`Submitted publish-all job ${job.id} (${job.state}).`, "green");
+        }
+        // In non-interactive mode, watch the job by default so CI surfaces
+        // failures. The bare `--no-wait` flag opts out for the rare fire-
+        // and-forget case. Interactive operators get the original behavior
+        // (submit + tracking hint) so they can detach and check later.
+        if (options.nonInteractive && !options.noWait) {
+            if (!logger.isJson()) {
+                logger.info(`Watching until terminal (--no-wait to skip). Re-check manually: scai content publish status ${job.id} -n ${envName}`, "gray");
+            }
+            const terminal = await (0, job_watcher_1.watchPublishJob)(logger, client, job.id, (0, job_watcher_1.clampPollInterval)(options.pollIntervalS), options.timeoutS ?? job_watcher_1.DEFAULT_WATCH_TIMEOUT_S);
+            if (logger.isJson()) {
+                process.stdout.write(`${JSON.stringify({ terminal: true, ...terminal }, null, 2)}\n`);
+            }
+            else {
+                (0, job_watcher_1.printJobSummary)(logger, terminal);
+            }
+            (0, job_watcher_1.throwOnTerminalFailure)(terminal);
+            return;
+        }
+        if (logger.isJson()) {
+            process.stdout.write(`${JSON.stringify(job, null, 2)}\n`);
+            return;
+        }
+        logger.info(`Track with: scai content publish status ${job.id} -n ${envName}`, "gray");
+    }
+    catch (err) {
+        (0, publish_audit_1.recordPublishAudit)({
+            ts: new Date().toISOString(),
+            command: "publish all",
+            caller,
+            scope,
+            risk: "high",
+            scopeHash,
+            scopeToken: options.confirmToken,
+            outcome: "error",
+            errorCode: err instanceof Error && "code" in err ? String(err.code) : "UNKNOWN",
+            errorMessage: err instanceof Error ? err.message : String(err),
+        });
+        throw err;
+    }
+};
+exports.runPublishAll = runPublishAll;

package/dist/publishing/tasks/cancel.d.ts

@@ -0,0 +1,18 @@
+export interface RunPublishCancelOptions {
+    config?: string;
+    environmentName?: string;
+    jobId?: string;
+    /** Cancel every queued+running job in the env. Mutually exclusive
+     *  with a positional jobId. Always requires a typed env-name
+     *  confirmation (skippable with --yes in CI). */
+    allQueued?: boolean;
+    /** Skip the typed env-name prompt on --all-queued (CI use). */
+    yes?: boolean;
+    verbose?: boolean;
+    trace?: boolean;
+    quiet?: boolean;
+    json?: boolean;
+    logFile?: string;
+    nonInteractive?: boolean;
+}
+export declare const runPublishCancel: (options: RunPublishCancelOptions) => Promise<void>;

package/dist/publishing/tasks/cancel.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runPublishCancel = void 0;
+const logger_1 = require("../../shared/logger");
+const errors_1 = require("../../shared/errors");
+const environment_1 = require("../../policy/environment");
+const prompt_1 = require("../../shared/prompt");
+const auth_1 = require("../api/auth");
+const client_1 = require("../api/client");
+const publish_audit_1 = require("../../shared/publish-audit");
+const toLogger = (options) => new logger_1.Logger(Boolean(options.verbose), Boolean(options.trace), Boolean(options.json), Boolean(options.quiet), options.logFile ?? process.env.SITECOREAI_LOG_FILE);
+const cancelOne = async (client, envName, envTenantId, job) => {
+    const caller = { type: "human", via: "cli" };
+    // API returns a flattened `xmc.type: "Site"` discriminator on response,
+    // but submitted-side jobs may still carry the nested `xmc.site` shape.
+    // Treat either as "whole-env" for audit + risk classification.
+    const xmc = job.raw.options?.xmc;
+    const isWholeEnv = Boolean(xmc?.site) || xmc?.type === "Site";
+    const auditScope = {
+        envName,
+        resolvedTenantId: envTenantId,
+        target: "Edge",
+        kind: (isWholeEnv ? "full" : "item"),
+    };
+    const risk = isWholeEnv ? "high" : "normal";
+    try {
+        await (0, client_1.cancelPublishJob)(client, job.id);
+        (0, publish_audit_1.recordPublishAudit)({
+            ts: new Date().toISOString(),
+            command: "publish cancel",
+            caller,
+            scope: auditScope,
+            risk,
+            scopeHash: "n/a",
+            jobId: job.id,
+            outcome: "cancelled",
+        });
+        return { jobId: job.id, state: job.state, outcome: "cancelled" };
+    }
+    catch (err) {
+        const errorCode = err instanceof Error && "code" in err ? String(err.code) : "UNKNOWN";
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        (0, publish_audit_1.recordPublishAudit)({
+            ts: new Date().toISOString(),
+            command: "publish cancel",
+            caller,
+            scope: auditScope,
+            risk,
+            scopeHash: "n/a",
+            jobId: job.id,
+            outcome: "error",
+            errorCode,
+            errorMessage,
+        });
+        return { jobId: job.id, state: job.state, outcome: "error", errorCode, errorMessage };
+    }
+};
+const runPublishCancel = async (options) => {
+    const logger = toLogger(options);
+    if (options.allQueued && options.jobId) {
+        throw (0, errors_1.createScaiError)("publish cancel: pass either <jobId> OR --all-queued, not both.", "INPUT_INVALID");
+    }
+    if (!options.allQueued && !options.jobId) {
+        throw (0, errors_1.createScaiError)("publish cancel requires a job id (or --all-queued).", "INPUT_INVALID", {
+            hint: "Pass the job id from `scai content publish item` / `scai content publish status`, or --all-queued to sweep the whole env.",
+        });
+    }
+    const { envName, environment, timeoutMs } = (0, environment_1.resolveEnvironment)(options);
+    const accessToken = await (0, auth_1.acquirePublishingToken)({ envName, environment });
+    const client = { accessToken, timeoutMs };
+    if (options.allQueued) {
+        const inflight = await (0, client_1.listPublishJobs)(client, { statuses: ["Queued", "Running"] });
+        if (inflight.length === 0) {
+            logger.info(`No queued or running publish jobs in env '${envName}'.`, "yellow");
+            if (logger.isJson()) {
+                process.stdout.write(`${JSON.stringify({ cancelled: [], skipped: [] }, null, 2)}\n`);
+            }
+            return;
+        }
+        if (!logger.isJson()) {
+            logger.warn(`⚠️  About to cancel ${inflight.length} publish job(s) in env '${envName}'.`, "yellow");
+            for (const j of inflight) {
+                logger.info(`  ${j.id} (${j.state})${j.startedAt ? `  started ${j.startedAt}` : ""}`, "gray");
+            }
+        }
+        if (!options.yes) {
+            if (options.nonInteractive) {
+                throw (0, errors_1.createScaiError)("publish cancel --all-queued in non-interactive mode requires --yes.", "INPUT_INVALID");
+            }
+            const typed = await (0, prompt_1.promptText)(`Type the env name '${envName}' to confirm cancelling ${inflight.length} job(s):`);
+            if (typed !== envName) {
+                throw (0, errors_1.createScaiError)(`Confirmation mismatch: typed '${typed}', expected '${envName}'. Aborting.`, "INPUT_INVALID");
+            }
+        }
+        const outcomes = [];
+        for (const job of inflight) {
+            // Only cancellable states pass to cancelOne; the rest get skipped
+            // silently (a job that's been racing to a terminal state between
+            // list and cancel shouldn't fail the whole sweep).
+            if (!job.canCancel) {
+                outcomes.push({
+                    jobId: job.id,
+                    state: job.state,
+                    outcome: "error",
+                    errorCode: "NOT_CANCELLABLE",
+                });
+                continue;
+            }
+            outcomes.push(await cancelOne(client, envName, environment.tenantId, job));
+        }
+        const successes = outcomes.filter((o) => o.outcome === "cancelled");
+        const failures = outcomes.filter((o) => o.outcome === "error");
+        if (logger.isJson()) {
+            process.stdout.write(`${JSON.stringify({ cancelled: successes, errors: failures, total: outcomes.length }, null, 2)}\n`);
+            return;
+        }
+        logger.info(`Cancel requested for ${successes.length}/${outcomes.length} job(s).`, successes.length === outcomes.length ? "green" : "yellow");
+        if (failures.length > 0) {
+            logger.warn(`${failures.length} job(s) could not be cancelled:`, "yellow");
+            for (const f of failures) {
+                logger.warn(`  ${f.jobId} (${f.errorCode ?? "?"})${f.errorMessage ? ` — ${f.errorMessage}` : ""}`, "yellow");
+            }
+        }
+        return;
+    }
+    // Single-job path (unchanged behavior).
+    const jobId = options.jobId;
+    const job = await (0, client_1.getPublishJob)(client, jobId);
+    if (!job.canCancel) {
+        throw (0, errors_1.createScaiError)(`Job ${jobId} is not cancellable (state '${job.state}').`, "INPUT_INVALID", {
+            hint: "Only Queued / Running jobs can be cancelled; Completed / Failed / already-Cancelled jobs cannot.",
+        });
+    }
+    const outcome = await cancelOne(client, envName, environment.tenantId, job);
+    if (outcome.outcome === "error") {
+        throw (0, errors_1.createScaiError)(`Failed to cancel ${jobId}: ${outcome.errorMessage}`, "NETWORK", {
+            hint: outcome.errorCode,
+        });
+    }
+    if (logger.isJson()) {
+        process.stdout.write(`${JSON.stringify({ id: jobId, outcome: "cancellation-requested" }, null, 2)}\n`);
+        return;
+    }
+    logger.info(`Cancel requested for job ${jobId}.`, "green");
+    logger.info(`Track with: scai content publish status ${jobId} -n ${envName}`, "gray");
+};
+exports.runPublishCancel = runPublishCancel;

package/dist/publishing/tasks/history.d.ts

@@ -0,0 +1,22 @@
+import { type PublishAuditEntry } from "../../shared/publish-audit";
+export interface RunPublishHistoryOptions {
+    /** Filter to entries from this env name. */
+    env?: string;
+    /** ISO 8601 timestamp OR relative spec (e.g. `7d`, `24h`, `30m`). */
+    since?: string;
+    /** Substring match against the `command` field
+     *  (e.g. `"item"`, `"unpublish"`, `"content version"`). */
+    command?: string;
+    /** Filter by outcome. */
+    outcome?: PublishAuditEntry["outcome"];
+    /** Max entries to read from disk before filtering. Default 500. */
+    scanLimit?: number;
+    /** Max entries to print after filtering. Default 50. */
+    limit?: number;
+    verbose?: boolean;
+    trace?: boolean;
+    quiet?: boolean;
+    json?: boolean;
+    logFile?: string;
+}
+export declare const runPublishHistory: (options: RunPublishHistoryOptions) => Promise<void>;

package/dist/publishing/tasks/history.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runPublishHistory = void 0;
+const logger_1 = require("../../shared/logger");
+const errors_1 = require("../../shared/errors");
+const publish_audit_1 = require("../../shared/publish-audit");
+const toLogger = (options) => new logger_1.Logger(Boolean(options.verbose), Boolean(options.trace), Boolean(options.json), Boolean(options.quiet), options.logFile ?? process.env.SITECOREAI_LOG_FILE);
+/**
+ * Parse `--since`. Accepts:
+ *   - ISO 8601 (`2026-05-14T00:00:00Z`)
+ *   - Relative (`24h`, `7d`, `30m`) — interpreted as "this much time ago"
+ *
+ * Returns the absolute ISO timestamp to compare against, or `undefined`
+ * if the spec is empty. Throws INPUT_INVALID on a malformed spec rather
+ * than silently returning everything — operators shouldn't think their
+ * filter is in effect when it isn't.
+ */
+const parseSince = (raw) => {
+    if (!raw || raw.trim().length === 0) {
+        return undefined;
+    }
+    const value = raw.trim();
+    const relative = value.match(/^(\d+)\s*(m|h|d)$/i);
+    if (relative) {
+        const n = Number.parseInt(relative[1], 10);
+        const unit = relative[2].toLowerCase();
+        const ms = unit === "m" ? n * 60000 : unit === "h" ? n * 3600000 : n * 86400000;
+        return new Date(Date.now() - ms).toISOString();
+    }
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime())) {
+        throw (0, errors_1.createScaiError)(`Could not parse --since '${value}'.`, "INPUT_INVALID", {
+            hint: "Pass an ISO 8601 timestamp (e.g. 2026-05-01T00:00:00Z) or a relative spec like 24h / 7d / 30m.",
+        });
+    }
+    return date.toISOString();
+};
+const formatRow = (entry) => {
+    const ts = entry.ts;
+    const env = (entry.scope?.envName ?? "?").padEnd(12);
+    const cmd = entry.command.padEnd(34);
+    const outcome = entry.outcome === "ok" ? "ok" : entry.outcome === "error" ? "ERROR" : "cxl";
+    const job = entry.jobId ? entry.jobId.slice(0, 14) : "—";
+    const err = entry.outcome === "error" && entry.errorCode ? `  ${entry.errorCode}` : "";
+    return `${ts}  ${env}  ${cmd}  ${outcome.padEnd(5)}  ${job.padEnd(14)}${err}`;
+};
+const runPublishHistory = async (options) => {
+    const logger = toLogger(options);
+    const since = parseSince(options.since);
+    const scanLimit = options.scanLimit ?? 500;
+    const limit = options.limit ?? 50;
+    const all = (0, publish_audit_1.readRecentPublishAudit)(scanLimit);
+    const filtered = all.filter((entry) => {
+        if (since && entry.ts < since) {
+            return false;
+        }
+        if (options.env && entry.scope?.envName !== options.env) {
+            return false;
+        }
+        if (options.command && !entry.command.includes(options.command)) {
+            return false;
+        }
+        if (options.outcome && entry.outcome !== options.outcome) {
+            return false;
+        }
+        return true;
+    });
+    const trimmed = filtered.slice(-limit);
+    if (logger.isJson()) {
+        for (const entry of trimmed) {
+            process.stdout.write(`${JSON.stringify(entry)}\n`);
+        }
+        return;
+    }
+    if (trimmed.length === 0) {
+        logger.info("No matching audit entries.", "yellow");
+        return;
+    }
+    logger.info(`Publishing audit (${trimmed.length} entr${trimmed.length === 1 ? "y" : "ies"}):`, "cyan");
+    logger.info(`${"timestamp".padEnd(24)}  ${"env".padEnd(12)}  ${"command".padEnd(34)}  ${"out".padEnd(5)}  ${"jobId".padEnd(14)}`, "gray");
+    for (const entry of trimmed) {
+        logger.info(formatRow(entry));
+    }
+};
+exports.runPublishHistory = runPublishHistory;

package/dist/publishing/tasks/item.d.ts

@@ -0,0 +1,69 @@
+import type { PublishItemsMode } from "../api/types";
+export interface RunPublishItemOptions {
+    config?: string;
+    environmentName?: string;
+    /** Item IDs (GUIDs) to publish. At least one of `itemIds` or
+     *  `paths` is required. The API accepts an array; scai bundles all
+     *  IDs into a single publishing job (one POST /jobs, one job id,
+     *  one audit entry). For large batches consider tenant rate limits
+     *  — the API documents no hard cap but treats each item as a unit
+     *  of work. */
+    itemIds?: string[];
+    /** Content-tree paths (e.g. `/sitecore/content/Home`). Resolved to
+     *  item IDs via Authoring GraphQL before submission. Merged into
+     *  the same job as `itemIds`; paths that don't resolve fail the
+     *  whole call before any API write. */
+    paths?: string[];
+    /** Site name. Resolves to the site's content-tree root item via
+     *  Sites + Authoring GraphQL, and adds that item to the publish
+     *  target list. Composable with `itemIds` and `paths` (target list
+     *  is the union). Combine with `--include-subitems` to publish the
+     *  whole site subtree; omit to publish just the root item. */
+    site?: string;
+    /** ItemModel.type — defaults to "item". The Publishing API accepts
+     *  a free-form string here; if your tenant uses a different value
+     *  (e.g. "Item" or "ContentItem"), pass it explicitly. */
+    itemType?: string;
+    /** Literal language list (e.g. `["en-US", "fr-CA"]`). Mapped to
+     *  `xmc.locales`. Mutually exclusive with `languagesFromSite` and
+     *  `allTenantLanguages` — set exactly one of the three. When none
+     *  is set, scai auto-resolves the tenant-wide language inventory
+     *  and logs it; the Publishing API has no implicit default. */
+    languages?: string[];
+    /** Resolve the language list from the named site's configuration via
+     *  the Sites API. Explicit — the verb logs the resolved set before
+     *  submitting. */
+    languagesFromSite?: string;
+    /** Resolve the language list to every language registered in the
+     *  tenant (via the Sites API `listLanguages` endpoint). */
+    allTenantLanguages?: boolean;
+    /** Map to xmc.items.publishChildren — matches dotnet --subitems. */
+    includeSubitems?: boolean;
+    /** Map to xmc.items.publishRelatedItems — matches dotnet --related. */
+    includeRelated?: boolean;
+    /** Publish mode. Per the Publishing API spec, items-level publish
+     *  supports only `Smart` (default) and `Republish` — Incremental
+     *  is whole-environment only and lives on `publish all`. */
+    mode?: PublishItemsMode;
+    /** Dry-run; default true. Real publish requires --allow-write. */
+    whatIf?: boolean;
+    /** Required to actually call the API. */
+    allowWrite?: boolean;
+    /** Scope token issued by a previous dry-run; required on prod tier. */
+    confirmToken?: string;
+    /** Skip the interactive prompt on non-prod envs. */
+    yes?: boolean;
+    /** Override the job name in the API request. */
+    name?: string;
+    /** Override the source field in the API request. */
+    source?: string;
+    /** Output / verbosity. */
+    verbose?: boolean;
+    trace?: boolean;
+    quiet?: boolean;
+    json?: boolean;
+    logFile?: string;
+    /** Non-interactive (e.g. CI) — refuse the [y/N] fallback path. */
+    nonInteractive?: boolean;
+}
+export declare const runPublishItem: (options: RunPublishItemOptions) => Promise<void>;