@sitecoreai-labs/sitecoreai-cli 0.0.4 → 0.1.0

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

@@ -0,0 +1,166 @@
+/**
+ * Shape types for the SAI Publishing REST API.
+ *
+ * Spec: https://api-docs.sitecore.com/sai/publishing-api
+ * OpenAPI YAML (raw, fetchable): https://api-docs.sitecore.com/_bundle/sai/publishing-api/index.yaml
+ *
+ * Host: `https://edge-platform.sitecorecloud.io`
+ * Path prefix on the wire: `/authoring/publishing/v1/jobs`
+ *   (Internal route also responds at `/api/publishing/v1/jobs` —
+ *   both paths reach the same handler.)
+ *
+ * Auth: Bearer JWT minted via env-level automation client; scopes
+ * `xmcpub.jobs.t:r/w` + `xmcpub.queue:r` (`.t` = tenant tier; `.a`
+ * admin variants are for Pages-UI user tokens only).
+ */
+/**
+ * Lifecycle states from the `system.status` field on PublishJobResponse.
+ * Note `Canceled` (US) and `Canceling` (US) — the API uses US spelling
+ * in this enum. Internally we normalize "Canceled" → "cancelled" so
+ * the rest of the codebase carries one consistent vocabulary, but we
+ * preserve the wire form here so callers reading raw responses see
+ * what the API actually sent.
+ */
+export type PublishJobStatusWire = "Queued" | "Running" | "Completed" | "Failed" | "Canceled" | "Canceling";
+export type PublishJobState = "queued" | "running" | "completed" | "failed" | "cancelled" | "cancelling";
+/** A single item in the Tier 1 (`publish item`) request body. */
+export interface PublishItemModel {
+    /** Item GUID. Required, 1–50 chars. */
+    id: string;
+    /** Item type / kind — see `ItemModel.type` in the OpenAPI spec.
+     *  Required, 1–256 chars. scai sends "item" by default; the exact
+     *  enum / accepted values are spec-documented as a free string. */
+    type: string;
+    /** Language code (e.g. "en-US"). Optional, 0–20 chars. */
+    locale?: string;
+}
+/**
+ * Mode for whole-environment publish (Tier 2). Empirically verified
+ * 2026-05-14 via `publish all --mode Smart` against the agents env:
+ * one job considered ~76K items across every site in the env (4
+ * locales), with `statistics.itemsSkipped` reflecting the full
+ * publishable corpus — the publish target is the environment's Edge
+ * endpoint, not a single Sitecore site. The API field is named
+ * `xmc.site` for legacy XM reasons (one-instance = one-site = one-DB)
+ * and has NO site-identifier field by design.
+ *
+ * Concurrency (verified 2026-05-14): the API accepts overlapping
+ * whole-env submissions but processes them serially. A second
+ * `publish all` queued while one is running waited ~80s behind the
+ * first; both completed, neither was rejected or coalesced. Submission
+ * itself is non-blocking (POST returns immediately with Queued).
+ *
+ * Stats shape (verified 2026-05-14): `statistics.itemsSent` /
+ * `itemsProcessed` / `xmc.itemsDeleted` / `xmc.itemsSkipped` are
+ * scalar aggregates summed across all locales. The response has NO
+ * `locales: [{...}]` per-locale breakdown — for per-locale visibility
+ * an operator must submit separate per-locale jobs and compare totals.
+ */
+export type PublishSiteMode = "Republish" | "Incremental" | "Smart";
+/** Mode for item / subtree publish (Tier 1). */
+export type PublishItemsMode = "Republish" | "Smart";
+export interface PublishSiteOptions {
+    mode: PublishSiteMode;
+}
+export interface PublishItemsOptions {
+    mode: PublishItemsMode;
+    /** Publish items referenced by the targeted items (matches the
+     *  legacy dotnet `--related` flag). Default false. */
+    publishRelatedItems?: boolean;
+    /** Publish descendants of the targeted items (matches `--subitems`).
+     *  Default false. */
+    publishChildren?: boolean;
+}
+export interface XmcPublishingOptions {
+    /** Languages to publish. When omitted, defaults to the env's
+     *  configured publish languages. */
+    locales?: string[];
+    /** Whole-environment publish (Tier 2). The OpenAPI field is named
+     *  `site` for historical reasons but operates tenant-wide — see
+     *  `PublishSiteMode` docstring. Mutually exclusive with `items`. */
+    site?: PublishSiteOptions;
+    /** Set for Tier 1 (`publish item`). */
+    items?: PublishItemsOptions;
+}
+export interface PublishOptionsModel {
+    /** Explicit per-item list (Tier 1). Optional in the spec; in
+     *  practice scai sets `items` for Tier 1 and `xmc.site` for
+     *  Tier 2, never both. */
+    items?: PublishItemModel[];
+    /** XM Cloud-specific publish controls — mode, locales, etc. */
+    xmc?: XmcPublishingOptions;
+}
+/** Body for `POST /authoring/publishing/v1/jobs`. */
+export interface CreatePublishJobRequest {
+    name: string;
+    source: string;
+    description?: string;
+    options: PublishOptionsModel;
+}
+export interface PublishJobUserRef {
+    id?: string | null;
+    name?: string | null;
+}
+export interface PublishJobSystem {
+    organizationId?: string | null;
+    tenantId: string;
+    tenantJobId?: string | null;
+    status: PublishJobStatusWire;
+    queuedTime?: string | null;
+    startTime?: string | null;
+    finishTime?: string | null;
+    createdBy: PublishJobUserRef;
+    canceledBy?: PublishJobUserRef | null;
+}
+export interface PublishJobPermissions {
+    canViewDetails: boolean;
+    canCancel: boolean;
+}
+export interface PublishJobResponse {
+    id: string;
+    name?: string | null;
+    description?: string | null;
+    source?: string | null;
+    options: PublishOptionsModel;
+    statistics?: Record<string, unknown> | null;
+    system: PublishJobSystem;
+    permissions: PublishJobPermissions;
+}
+/**
+ * Normalized job shape consumed by scai's CLI / library callers.
+ * Smaller surface than the raw API response — the rest is kept on
+ * the `raw` field for callers that need it.
+ */
+export interface PublishJob {
+    id: string;
+    state: PublishJobState;
+    name?: string;
+    source?: string;
+    /** Number of items processed so far — when statistics expose it. */
+    processedCount?: number;
+    /** Number of items total — when statistics expose it. */
+    totalCount?: number;
+    startedAt?: string;
+    completedAt?: string;
+    /** Whether the API permits cancelling this job. */
+    canCancel: boolean;
+    /** Full raw response, for callers that need fields not in this
+     *  normalized shape. */
+    raw: PublishJobResponse;
+}
+export interface PublishingApiClientOptions {
+    /** Bearer JWT with the publishing-scope grants. */
+    accessToken: string;
+    /** Base host override. Default `https://edge-platform.sitecorecloud.io`. */
+    baseUrl?: string;
+    /** Per-call timeout in ms. */
+    timeoutMs?: number;
+}
+export interface ListPublishJobsQuery {
+    pageNumber?: number;
+    pageSize?: number;
+    /** Filter to jobs in these states (using wire form). */
+    statuses?: PublishJobStatusWire[];
+    /** Free-form source filter; matches the `source` query param. */
+    source?: string[];
+}

package/dist/publishing/api/types.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * Shape types for the SAI Publishing REST API.
+ *
+ * Spec: https://api-docs.sitecore.com/sai/publishing-api
+ * OpenAPI YAML (raw, fetchable): https://api-docs.sitecore.com/_bundle/sai/publishing-api/index.yaml
+ *
+ * Host: `https://edge-platform.sitecorecloud.io`
+ * Path prefix on the wire: `/authoring/publishing/v1/jobs`
+ *   (Internal route also responds at `/api/publishing/v1/jobs` —
+ *   both paths reach the same handler.)
+ *
+ * Auth: Bearer JWT minted via env-level automation client; scopes
+ * `xmcpub.jobs.t:r/w` + `xmcpub.queue:r` (`.t` = tenant tier; `.a`
+ * admin variants are for Pages-UI user tokens only).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/publishing/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Public entry for `@sitecoreai-labs/sitecoreai-cli/publishing`.
+ *
+ * The Sitecore AI Publishing API (XM Cloud publish jobs) plus the
+ * library-layer safety primitives that gate every destructive call:
+ * the `PublishConsent` argument, the typed scope-token flow, and the
+ * append-only audit log. See `docs/parity-with-devex.md` for the
+ * three-layer safety model.
+ *
+ * Library consumers that wrap publishing for an MCP host, CI pipeline,
+ * or higher-level agent are expected to construct a `PublishConsent`
+ * before calling the HTTP primitives — the CLI's `runPublishItem` task
+ * shows the canonical assembly.
+ */
+export { submitPublishJob, getPublishJob, cancelPublishJob, listPublishJobs } from "./api/client";
+export type { CreatePublishJobRequest, ListPublishJobsQuery, PublishItemModel, PublishItemsMode, PublishItemsOptions, PublishJob, PublishJobPermissions, PublishJobResponse, PublishJobState, PublishJobStatusWire, PublishJobSystem, PublishJobUserRef, PublishOptionsModel, PublishSiteMode, PublishSiteOptions, PublishingApiClientOptions, XmcPublishingOptions, } from "./api/types";
+export { PUBLISHING_SCOPES_REQUESTED, acquirePublishingToken, type AcquirePublishingTokenOptions, } from "./api/auth";
+export { SCOPE_TOKEN_TTL_MS, computeScopeHash, mintScopeToken, verifyScopeToken, type PublishConsent, type ScopeTokenVerification, type ScopeTokenVerificationFailure, } from "../shared/publish-consent";
+export { recordPublishAudit, readRecentPublishAudit, type PublishAuditCaller, type PublishAuditEntry, type PublishAuditScope, } from "../shared/publish-audit";
+export { isProductionTier } from "../shared/env-tier";
+export { runPublishStatus, type RunPublishStatusOptions } from "./tasks/status";
+export { runPublishItem, type RunPublishItemOptions } from "./tasks/item";
+export { runPublishAll, type RunPublishAllOptions } from "./tasks/all";
+export { runPublishCancel, type RunPublishCancelOptions } from "./tasks/cancel";
+export { runPublishUnpublish, type RunPublishUnpublishOptions } from "./tasks/unpublish";

package/dist/publishing/index.js

@@ -0,0 +1,51 @@
+"use strict";
+/**
+ * Public entry for `@sitecoreai-labs/sitecoreai-cli/publishing`.
+ *
+ * The Sitecore AI Publishing API (XM Cloud publish jobs) plus the
+ * library-layer safety primitives that gate every destructive call:
+ * the `PublishConsent` argument, the typed scope-token flow, and the
+ * append-only audit log. See `docs/parity-with-devex.md` for the
+ * three-layer safety model.
+ *
+ * Library consumers that wrap publishing for an MCP host, CI pipeline,
+ * or higher-level agent are expected to construct a `PublishConsent`
+ * before calling the HTTP primitives — the CLI's `runPublishItem` task
+ * shows the canonical assembly.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runPublishUnpublish = exports.runPublishCancel = exports.runPublishAll = exports.runPublishItem = exports.runPublishStatus = exports.isProductionTier = exports.readRecentPublishAudit = exports.recordPublishAudit = exports.verifyScopeToken = exports.mintScopeToken = exports.computeScopeHash = exports.SCOPE_TOKEN_TTL_MS = exports.acquirePublishingToken = exports.PUBLISHING_SCOPES_REQUESTED = exports.listPublishJobs = exports.cancelPublishJob = exports.getPublishJob = exports.submitPublishJob = void 0;
+// --- HTTP client primitives --------------------------------------------
+var client_1 = require("./api/client");
+Object.defineProperty(exports, "submitPublishJob", { enumerable: true, get: function () { return client_1.submitPublishJob; } });
+Object.defineProperty(exports, "getPublishJob", { enumerable: true, get: function () { return client_1.getPublishJob; } });
+Object.defineProperty(exports, "cancelPublishJob", { enumerable: true, get: function () { return client_1.cancelPublishJob; } });
+Object.defineProperty(exports, "listPublishJobs", { enumerable: true, get: function () { return client_1.listPublishJobs; } });
+// --- Auth --------------------------------------------------------------
+var auth_1 = require("./api/auth");
+Object.defineProperty(exports, "PUBLISHING_SCOPES_REQUESTED", { enumerable: true, get: function () { return auth_1.PUBLISHING_SCOPES_REQUESTED; } });
+Object.defineProperty(exports, "acquirePublishingToken", { enumerable: true, get: function () { return auth_1.acquirePublishingToken; } });
+// --- Consent + scope tokens --------------------------------------------
+var publish_consent_1 = require("../shared/publish-consent");
+Object.defineProperty(exports, "SCOPE_TOKEN_TTL_MS", { enumerable: true, get: function () { return publish_consent_1.SCOPE_TOKEN_TTL_MS; } });
+Object.defineProperty(exports, "computeScopeHash", { enumerable: true, get: function () { return publish_consent_1.computeScopeHash; } });
+Object.defineProperty(exports, "mintScopeToken", { enumerable: true, get: function () { return publish_consent_1.mintScopeToken; } });
+Object.defineProperty(exports, "verifyScopeToken", { enumerable: true, get: function () { return publish_consent_1.verifyScopeToken; } });
+// --- Audit log ----------------------------------------------------------
+var publish_audit_1 = require("../shared/publish-audit");
+Object.defineProperty(exports, "recordPublishAudit", { enumerable: true, get: function () { return publish_audit_1.recordPublishAudit; } });
+Object.defineProperty(exports, "readRecentPublishAudit", { enumerable: true, get: function () { return publish_audit_1.readRecentPublishAudit; } });
+// --- Environment-tier heuristic ----------------------------------------
+var env_tier_1 = require("../shared/env-tier");
+Object.defineProperty(exports, "isProductionTier", { enumerable: true, get: function () { return env_tier_1.isProductionTier; } });
+// --- Task runners -------------------------------------------------------
+var status_1 = require("./tasks/status");
+Object.defineProperty(exports, "runPublishStatus", { enumerable: true, get: function () { return status_1.runPublishStatus; } });
+var item_1 = require("./tasks/item");
+Object.defineProperty(exports, "runPublishItem", { enumerable: true, get: function () { return item_1.runPublishItem; } });
+var all_1 = require("./tasks/all");
+Object.defineProperty(exports, "runPublishAll", { enumerable: true, get: function () { return all_1.runPublishAll; } });
+var cancel_1 = require("./tasks/cancel");
+Object.defineProperty(exports, "runPublishCancel", { enumerable: true, get: function () { return cancel_1.runPublishCancel; } });
+var unpublish_1 = require("./tasks/unpublish");
+Object.defineProperty(exports, "runPublishUnpublish", { enumerable: true, get: function () { return unpublish_1.runPublishUnpublish; } });

package/dist/publishing/job-diagnostics.d.ts

@@ -0,0 +1,44 @@
+import type { PublishJob } from "./api/types";
+/**
+ * Structured failure information extracted from a `PublishJob`'s
+ * normalized + raw payloads. The Publishing API does not document a
+ * single canonical "failure detail" field — observed shapes include:
+ *
+ *   - `statistics.itemsFailed` (count of failed items)
+ *   - `statistics.xmc.errors[]` (per-item error messages — observed
+ *     shape: `{ itemId, locale?, message }`, defensive parsing only)
+ *   - `system.failureReason` (free-text, sometimes present)
+ *   - `system.canceledBy.name` / `system.canceledBy.id` (set on cancel,
+ *     not failure, but useful in the same diagnostic block)
+ *
+ * Callers should treat every field as optional — older XM Cloud
+ * deployments and certain failure classes don't populate all of them.
+ *
+ * This module is the single source of truth for "how do we explain a
+ * failed publish to the operator." Both `publish status` and the
+ * `publish status --watch` exit path consume it; future surfaces (MCP
+ * `publishing_lifecycle`, audit-log readers) should reuse it rather
+ * than re-derive the same fields.
+ */
+export interface PublishJobFailureDiagnostics {
+    /** Free-text failure reason from `system.failureReason` if present. */
+    reason?: string;
+    /** Count of failed items, when statistics expose it. */
+    failedItemCount?: number;
+    /** Per-item failure messages, defensively parsed. */
+    itemFailures?: Array<{
+        itemId?: string;
+        locale?: string;
+        message: string;
+    }>;
+    /** Last statistics-update timestamp; helps gauge how stale stats are. */
+    lastReportTime?: string;
+}
+export declare const extractFailureDiagnostics: (job: PublishJob) => PublishJobFailureDiagnostics;
+/**
+ * Render the diagnostics as a list of human-readable lines suitable
+ * for sequential `logger.info()` calls. Returns `[]` when nothing
+ * useful can be said — the caller should not print a "Failure:"
+ * header in that case.
+ */
+export declare const formatFailureDiagnostics: (diag: PublishJobFailureDiagnostics) => string[];

package/dist/publishing/job-diagnostics.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatFailureDiagnostics = exports.extractFailureDiagnostics = void 0;
+const asRecord = (value) => value && typeof value === "object" && !Array.isArray(value)
+    ? value
+    : undefined;
+const asString = (value) => typeof value === "string" && value.length > 0 ? value : undefined;
+const asNumber = (value) => typeof value === "number" && Number.isFinite(value) ? value : undefined;
+const parseItemFailures = (stats) => {
+    // Two candidate shapes — defensive, neither guaranteed:
+    //   stats.errors:      [{ itemId, locale, message }]
+    //   stats.xmc.errors:  same
+    const candidates = [];
+    if (Array.isArray(stats.errors)) {
+        candidates.push(...stats.errors);
+    }
+    const xmc = asRecord(stats.xmc);
+    if (xmc && Array.isArray(xmc.errors)) {
+        candidates.push(...xmc.errors);
+    }
+    if (candidates.length === 0) {
+        return undefined;
+    }
+    const parsed = candidates
+        .map((c) => {
+        const rec = asRecord(c);
+        if (!rec) {
+            return undefined;
+        }
+        const message = asString(rec.message) ?? asString(rec.error) ?? asString(rec.detail);
+        if (!message) {
+            return undefined;
+        }
+        return {
+            itemId: asString(rec.itemId) ?? asString(rec.id),
+            locale: asString(rec.locale) ?? asString(rec.language),
+            message,
+        };
+    })
+        .filter((v) => v !== undefined);
+    return parsed.length > 0 ? parsed : undefined;
+};
+const extractFailureDiagnostics = (job) => {
+    const raw = job.raw;
+    const stats = asRecord(raw.statistics) ?? {};
+    const system = asRecord(raw.system) ?? {};
+    return {
+        reason: asString(system.failureReason) ??
+            asString(stats.xmc?.failureReason),
+        failedItemCount: asNumber(stats.itemsFailed) ?? asNumber(stats.failedCount),
+        itemFailures: parseItemFailures(stats),
+        lastReportTime: asString(stats.lastReportTime),
+    };
+};
+exports.extractFailureDiagnostics = extractFailureDiagnostics;
+/**
+ * Render the diagnostics as a list of human-readable lines suitable
+ * for sequential `logger.info()` calls. Returns `[]` when nothing
+ * useful can be said — the caller should not print a "Failure:"
+ * header in that case.
+ */
+const formatFailureDiagnostics = (diag) => {
+    const lines = [];
+    if (diag.reason) {
+        lines.push(`Reason: ${diag.reason}`);
+    }
+    if (diag.failedItemCount !== undefined && diag.failedItemCount > 0) {
+        lines.push(`Failed items: ${diag.failedItemCount}`);
+    }
+    if (diag.itemFailures && diag.itemFailures.length > 0) {
+        const max = 10;
+        for (const f of diag.itemFailures.slice(0, max)) {
+            const tag = f.itemId
+                ? `${f.itemId}${f.locale ? ` (${f.locale})` : ""}`
+                : (f.locale ?? "(unknown item)");
+            lines.push(`  ${tag}: ${f.message}`);
+        }
+        if (diag.itemFailures.length > max) {
+            lines.push(`  (and ${diag.itemFailures.length - max} more)`);
+        }
+    }
+    if (diag.lastReportTime) {
+        lines.push(`Last statistics update: ${diag.lastReportTime}`);
+    }
+    return lines;
+};
+exports.formatFailureDiagnostics = formatFailureDiagnostics;

package/dist/publishing/job-watcher.d.ts

@@ -0,0 +1,33 @@
+import type { Logger } from "../shared/logger";
+import type { PublishJob, PublishingApiClientOptions } from "./api/types";
+export declare const DEFAULT_POLL_INTERVAL_S = 5;
+export declare const DEFAULT_WATCH_TIMEOUT_S = 1800;
+export declare const clampPollInterval: (raw: number | undefined) => number;
+/**
+ * Watch a job until it reaches a terminal state. Emits one log line
+ * per state change (or per processedCount delta in verbose mode);
+ * in --json mode, writes one JSON object per emitted change to stdout.
+ *
+ * Returns the terminal job. Caller decides whether to throw on
+ * failed/cancelled — different verbs have different exit-code
+ * conventions.
+ *
+ * Throws ScaiError on the watch timeout (NETWORK) so CI pipelines fail
+ * loudly instead of swallowing a hung publish.
+ */
+export declare const watchPublishJob: (logger: Logger, client: PublishingApiClientOptions, jobId: string, pollIntervalS: number, timeoutS: number) => Promise<PublishJob>;
+/**
+ * Print the human-readable summary for a single job, including
+ * failure diagnostics when the job ended in `failed`. Used by both
+ * the one-shot status path and the final transition in --watch.
+ */
+export declare const printJobSummary: (logger: Logger, job: PublishJob) => void;
+/**
+ * Translate a terminal job state into a ScaiError throw (or pass-through
+ * for `completed`). Centralizes the exit-code mapping so every verb that
+ * watches a job exits consistently:
+ *   - completed → no throw, caller proceeds
+ *   - failed    → DEPLOY_FAILED (exit 6)
+ *   - cancelled → CANCELLED (exit 130, matches POSIX SIGINT convention)
+ */
+export declare const throwOnTerminalFailure: (job: PublishJob) => void;

package/dist/publishing/job-watcher.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.throwOnTerminalFailure = exports.printJobSummary = exports.watchPublishJob = exports.clampPollInterval = exports.DEFAULT_WATCH_TIMEOUT_S = exports.DEFAULT_POLL_INTERVAL_S = void 0;
+const errors_1 = require("../shared/errors");
+const client_1 = require("./api/client");
+const job_diagnostics_1 = require("./job-diagnostics");
+/**
+ * Job-watch + summary printing helpers. Used by `scai content publish status
+ * --watch` and by `scai content publish all` in non-interactive mode (where
+ * "submit and exit" leaves CI blind to job failure). Single source of
+ * truth so the two surfaces emit identical event streams.
+ */
+const TERMINAL_STATES = new Set(["completed", "failed", "cancelled"]);
+exports.DEFAULT_POLL_INTERVAL_S = 5;
+exports.DEFAULT_WATCH_TIMEOUT_S = 1800;
+const clampPollInterval = (raw) => {
+    const v = typeof raw === "number" && Number.isFinite(raw) ? raw : exports.DEFAULT_POLL_INTERVAL_S;
+    return Math.min(60, Math.max(2, v));
+};
+exports.clampPollInterval = clampPollInterval;
+const sleep = (ms) => new Promise((resolve) => {
+    setTimeout(resolve, ms);
+});
+/**
+ * Watch a job until it reaches a terminal state. Emits one log line
+ * per state change (or per processedCount delta in verbose mode);
+ * in --json mode, writes one JSON object per emitted change to stdout.
+ *
+ * Returns the terminal job. Caller decides whether to throw on
+ * failed/cancelled — different verbs have different exit-code
+ * conventions.
+ *
+ * Throws ScaiError on the watch timeout (NETWORK) so CI pipelines fail
+ * loudly instead of swallowing a hung publish.
+ */
+const watchPublishJob = async (logger, client, jobId, pollIntervalS, timeoutS) => {
+    const deadlineMs = Date.now() + timeoutS * 1000;
+    let lastState;
+    let lastProcessed;
+    for (;;) {
+        if (Date.now() > deadlineMs) {
+            throw (0, errors_1.createScaiError)(`Watch timed out after ${timeoutS}s waiting for job ${jobId} to reach a terminal state.`, "NETWORK", {
+                hint: `Re-check manually: scai content publish status ${jobId}. Increase --timeout-s if the publish is genuinely longer-running.`,
+            });
+        }
+        const job = await (0, client_1.getPublishJob)(client, jobId);
+        const stateChanged = job.state !== lastState;
+        const processedChanged = job.processedCount !== undefined && job.processedCount !== lastProcessed;
+        if (stateChanged || (processedChanged && logger.isVerbose())) {
+            if (logger.isJson()) {
+                process.stdout.write(`${JSON.stringify({ ts: new Date().toISOString(), ...job })}\n`);
+            }
+            else {
+                logger.info(`[${new Date().toISOString()}] ${job.id} → ${job.state}${job.processedCount !== undefined ? `  (${job.processedCount} processed)` : ""}`, stateChanged ? "cyan" : "gray");
+            }
+            lastState = job.state;
+            lastProcessed = job.processedCount;
+        }
+        if (TERMINAL_STATES.has(job.state)) {
+            return job;
+        }
+        await sleep(pollIntervalS * 1000);
+    }
+};
+exports.watchPublishJob = watchPublishJob;
+/**
+ * Print the human-readable summary for a single job, including
+ * failure diagnostics when the job ended in `failed`. Used by both
+ * the one-shot status path and the final transition in --watch.
+ */
+const printJobSummary = (logger, job) => {
+    logger.info(`Job ${job.id}: ${job.state}`, "cyan");
+    if (job.processedCount !== undefined) {
+        logger.info(`  Processed: ${job.processedCount}`);
+    }
+    if (job.totalCount !== undefined) {
+        logger.info(`  Total:     ${job.totalCount}`);
+    }
+    if (job.startedAt) {
+        logger.info(`  Started:   ${job.startedAt}`);
+    }
+    if (job.completedAt) {
+        logger.info(`  Completed: ${job.completedAt}`);
+    }
+    if (job.state === "failed") {
+        const diag = (0, job_diagnostics_1.extractFailureDiagnostics)(job);
+        const formatted = (0, job_diagnostics_1.formatFailureDiagnostics)(diag);
+        if (formatted.length > 0) {
+            logger.info("  Failure:", "red");
+            for (const line of formatted) {
+                logger.info(`    ${line}`, "red");
+            }
+        }
+    }
+};
+exports.printJobSummary = printJobSummary;
+/**
+ * Translate a terminal job state into a ScaiError throw (or pass-through
+ * for `completed`). Centralizes the exit-code mapping so every verb that
+ * watches a job exits consistently:
+ *   - completed → no throw, caller proceeds
+ *   - failed    → DEPLOY_FAILED (exit 6)
+ *   - cancelled → CANCELLED (exit 130, matches POSIX SIGINT convention)
+ */
+const throwOnTerminalFailure = (job) => {
+    if (job.state === "failed") {
+        const diag = (0, job_diagnostics_1.extractFailureDiagnostics)(job);
+        throw (0, errors_1.createScaiError)(`Publish job ${job.id} ended in state 'failed'.`, "DEPLOY_FAILED", {
+            hint: diag.reason ?? "Inspect statistics on the raw job for failure detail.",
+        });
+    }
+    if (job.state === "cancelled") {
+        throw (0, errors_1.createScaiError)(`Publish job ${job.id} was cancelled.`, "CANCELLED", {
+            hint: "The job did not complete. Re-submit if needed.",
+        });
+    }
+};
+exports.throwOnTerminalFailure = throwOnTerminalFailure;

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

@@ -0,0 +1,41 @@
+export interface RunPublishAllOptions {
+    config?: string;
+    environmentName?: string;
+    /** Literal language list. See `PublishLocaleOptions`. */
+    languages?: string[];
+    /** Resolve locales from the named site's language config via Sites
+     *  API. NOTE: the publish itself is still whole-environment — the
+     *  Publishing API has no site-scoping field for Tier 2 (verified
+     *  2026-05-14 against the agents env). This flag scopes locales
+     *  only. */
+    languagesFromSite?: string;
+    /** Resolve locales to every language registered in the tenant. */
+    allTenantLanguages?: boolean;
+    mode?: "Republish" | "Smart" | "Incremental";
+    /** Required to actually call the API. */
+    allowWrite?: boolean;
+    whatIf?: boolean;
+    confirmToken?: string;
+    /** Operator must echo env name back interactively unless --yes is set
+     *  alongside --confirm-token (CI path). */
+    yes?: boolean;
+    name?: string;
+    source?: string;
+    /** In non-interactive mode, after submitting, watch the job until it
+     *  reaches a terminal state. Default `true` (CI safety: if the job
+     *  fails, the command should exit non-zero so the pipeline notices).
+     *  Pass `noWait: true` to opt out and get fire-and-forget submit. */
+    noWait?: boolean;
+    /** Poll interval in seconds when watching. Clamped to [2, 60]. */
+    pollIntervalS?: number;
+    /** Watch timeout in seconds. Default 1800 (30 min). Throws NETWORK
+     *  if the job hasn't reached a terminal state by then. */
+    timeoutS?: number;
+    verbose?: boolean;
+    trace?: boolean;
+    quiet?: boolean;
+    json?: boolean;
+    logFile?: string;
+    nonInteractive?: boolean;
+}
+export declare const runPublishAll: (options: RunPublishAllOptions) => Promise<void>;