@riverbankcms/sdk 0.95.0 → 0.98.0

package/dist/_dts/sdk/src/cli/content/reader.d.ts

@@ -4,6 +4,7 @@
  * Reads content from the file system for push operations.
  * Mirrors the structure created by writer.ts.
  */
+import { type ContentMetadataTarget } from './metadataStore';
 import type { NavigationAuthoringLinkInput, NavigationLocalItemInput } from '../../../../api/src/navigation';
 import type { SdkEventPricingInput } from '../../../../api/src/sdk-event-pricing';
 import type { EventPaymentTermsInput } from '../../client/management/types';
@@ -233,7 +234,7 @@ export declare function findLegacyEntryFiles(contentDir: string): Promise<string
  * @param contentType - Optional specific content type to read
  * @returns Map of content type to entries
  */
-export declare function readEntries(contentDir: string, contentType?: string): Promise<Map<string, LocalEntry[]>>;
+export declare function readEntries(contentDir: string, contentType?: string, metadataTarget?: ContentMetadataTarget): Promise<Map<string, LocalEntry[]>>;
 /**
  * Read pages from content directory
  *
@@ -350,7 +351,7 @@ export interface LocalContent {
     events: LocalEvent[];
     courses: LocalCourse[];
 }
-export declare function readAllContent(contentDir: string): Promise<LocalContent>;
+export declare function readAllContent(contentDir: string, metadataTarget?: ContentMetadataTarget): Promise<LocalContent>;
 /**
  * Check if content directory exists and has content
  */
@@ -387,6 +388,7 @@ export interface EntryMetadata {
         createdAt?: string;
         updatedAt?: string;
         publishedAt?: string;
+        hasUnpublishedChanges?: boolean;
     }>;
 }
 export interface PagesMetadata {
@@ -414,35 +416,35 @@ export interface SettingsMetadata {
  * @param contentType - Content type to read metadata for
  * @returns Metadata or null if not found
  */
-export declare function readEntriesMeta(contentDir: string, contentType: string): Promise<EntryMetadata | null>;
+export declare function readEntriesMeta(contentDir: string, contentType: string, metadataTarget?: ContentMetadataTarget): Promise<EntryMetadata | null>;
 /**
  * Read all entry metadata files from .meta/ directory
  *
  * @param contentDir - Base content directory
  * @returns Map of content type to metadata
  */
-export declare function readAllMeta(contentDir: string): Promise<Map<string, EntryMetadata>>;
+export declare function readAllMeta(contentDir: string, metadataTarget?: ContentMetadataTarget): Promise<Map<string, EntryMetadata>>;
 /**
  * Read settings metadata from .meta/settings.json
  *
  * @param contentDir - Base content directory
  * @returns Settings metadata or null if not found
  */
-export declare function readSettingsMeta(contentDir: string): Promise<SettingsMetadata | null>;
+export declare function readSettingsMeta(contentDir: string, metadataTarget?: ContentMetadataTarget): Promise<SettingsMetadata | null>;
 /**
  * Read pages metadata from .meta/pages.json
  *
  * @param contentDir - Base content directory
  * @returns Pages metadata or null if not found
  */
-export declare function readPagesMeta(contentDir: string): Promise<PagesMetadata | null>;
+export declare function readPagesMeta(contentDir: string, metadataTarget?: ContentMetadataTarget): Promise<PagesMetadata | null>;
 /**
  * Read navigation metadata from .meta/navigation.json
  *
  * @param contentDir - Base content directory
  * @returns Navigation metadata or null if not found
  */
-export declare function readNavigationMeta(contentDir: string): Promise<NavigationMetadata | null>;
+export declare function readNavigationMeta(contentDir: string, metadataTarget?: ContentMetadataTarget): Promise<NavigationMetadata | null>;
 export interface FormsMetadata {
     pulledAt: string;
     forms: Record<string, {
@@ -456,7 +458,7 @@ export interface FormsMetadata {
  * @param contentDir - Base content directory
  * @returns Forms metadata or null if not found
  */
-export declare function readFormsMeta(contentDir: string): Promise<FormsMetadata | null>;
+export declare function readFormsMeta(contentDir: string, metadataTarget?: ContentMetadataTarget): Promise<FormsMetadata | null>;
 export interface ThemesMetadata {
     pulledAt: string;
     themes: Record<string, {
@@ -471,7 +473,7 @@ export interface ThemesMetadata {
  * @param contentDir - Base content directory
  * @returns Themes metadata or null if not found
  */
-export declare function readThemesMeta(contentDir: string): Promise<ThemesMetadata | null>;
+export declare function readThemesMeta(contentDir: string, metadataTarget?: ContentMetadataTarget): Promise<ThemesMetadata | null>;
 export interface VenuesMetadata {
     pulledAt: string;
     venues: Record<string, {
@@ -485,7 +487,7 @@ export interface VenuesMetadata {
  * @param contentDir - Base content directory
  * @returns Venues metadata or null if not found
  */
-export declare function readVenuesMeta(contentDir: string): Promise<VenuesMetadata | null>;
+export declare function readVenuesMeta(contentDir: string, metadataTarget?: ContentMetadataTarget): Promise<VenuesMetadata | null>;
 export interface EventCategoriesMetadata {
     pulledAt: string;
     eventCategories: Record<string, {
@@ -499,7 +501,7 @@ export interface EventCategoriesMetadata {
  * @param contentDir - Base content directory
  * @returns Event categories metadata or null if not found
  */
-export declare function readEventCategoriesMeta(contentDir: string): Promise<EventCategoriesMetadata | null>;
+export declare function readEventCategoriesMeta(contentDir: string, metadataTarget?: ContentMetadataTarget): Promise<EventCategoriesMetadata | null>;
 export interface EventsMetadata {
     pulledAt: string;
     events: Record<string, {
@@ -520,14 +522,14 @@ export interface CoursesMetadata {
  * @param contentDir - Base content directory
  * @returns Events metadata or null if not found
  */
-export declare function readEventsMeta(contentDir: string): Promise<EventsMetadata | null>;
+export declare function readEventsMeta(contentDir: string, metadataTarget?: ContentMetadataTarget): Promise<EventsMetadata | null>;
 /**
  * Read courses metadata from .meta/courses.json
  *
  * @param contentDir - Base content directory
  * @returns Courses metadata or null if not found
  */
-export declare function readCoursesMeta(contentDir: string): Promise<CoursesMetadata | null>;
+export declare function readCoursesMeta(contentDir: string, metadataTarget?: ContentMetadataTarget): Promise<CoursesMetadata | null>;
 export interface FooterMetadata {
     pulledAt: string;
     updatedAt?: string;
@@ -538,4 +540,4 @@ export interface FooterMetadata {
  * @param contentDir - Base content directory
  * @returns Footer metadata or null if not found
  */
-export declare function readFooterMeta(contentDir: string): Promise<FooterMetadata | null>;
+export declare function readFooterMeta(contentDir: string, metadataTarget?: ContentMetadataTarget): Promise<FooterMetadata | null>;

package/dist/_dts/sdk/src/cli/content/writer.d.ts

@@ -5,15 +5,19 @@
  */
 import type { PulledEntries, PulledPages, PulledNavigation, PulledSettings, PulledForms, PulledTheme, PulledFooter, PulledVenues, PulledEventCategories, PulledEvents, PulledCourses } from '../../client/management/types';
 import type { Theme } from '../../contracts';
-import { type PulledEntryOutput } from '../helpers';
+import { type EntryForOutput } from '../helpers';
 import type { EntryBaseSnapshotTarget } from '../merge-remote/entrySnapshots';
+import type { PageBaseSnapshotTarget } from '../merge-remote/pageSnapshots';
+import { type ContentMetadataTarget } from './metadataStore';
 export interface WriterOptions {
     skipMeta?: boolean;
     cleanupMissing?: boolean;
+    metadataTarget?: ContentMetadataTarget;
     entryBaseSnapshot?: EntryBaseSnapshotTarget;
+    pageBaseSnapshot?: PageBaseSnapshotTarget;
 }
 type WritablePulledEntries = Omit<PulledEntries, 'entries'> & {
-    entries: PulledEntryOutput[];
+    entries: EntryForOutput[];
 };
 /**
  * Write entries to content directory
@@ -90,7 +94,7 @@ export declare function writeThemesMeta(contentDir: string, meta: {
         selectionId: string;
         updatedAt: string;
     }>;
-}): Promise<void>;
+}, options?: Pick<WriterOptions, 'metadataTarget'>): Promise<void>;
 /**
  * Write a pulled theme to content directory with metadata
  *
@@ -205,7 +209,7 @@ export declare function updateMetadataAfterPush(contentDir: string, remoteConten
         updatedAt: string;
         createdAt?: string;
     }>;
-}): Promise<void>;
+}, options?: Pick<WriterOptions, 'metadataTarget'>): Promise<void>;
 export declare function writeAllContent(contentDir: string, content: {
     entries: Record<string, PulledEntries['entries']>;
     pages: PulledPages;

package/dist/_dts/sdk/src/cli/env-scope.d.ts

@@ -0,0 +1,2 @@
+import type { EnvTarget } from './helpers';
+export declare function withRiverbankEnv<T>(target: EnvTarget, run: () => Promise<T>): Promise<T>;

package/dist/_dts/sdk/src/cli/helpers.d.ts

@@ -85,17 +85,16 @@ export interface ParsedPagination {
  */
 export type RowFormatter<T> = (item: T) => string[];
 /**
- * Entry format for SDK pull operations.
- * Matches the server-side PulledEntry type.
+ * Entry format written to content/entries/*.json.
+ * Operational fields such as manual ordering and unpublished state live in
+ * metadata so entry files remain authoring-focused.
  */
-export interface PulledEntryOutput {
+export interface EntryContentFileOutput {
     identifier: string;
     data: Record<string, unknown>;
     status: 'draft' | 'published';
-    hasUnpublishedChanges: boolean;
     /** Slug for URL routing - only present for routable content types */
     slug?: string;
-    manualOrder?: number;
     blocks?: Record<string, Array<{
         identifier: string | null;
         kind: string;
@@ -114,9 +113,9 @@ export interface EntryForOutput {
     slug?: string;
     title?: string;
     manualOrder?: number;
-    blocks?: PulledEntryOutput['blocks'];
+    blocks?: EntryContentFileOutput['blocks'];
 }
-export declare function mapEntryForOutput<T extends EntryForOutput>(entry: T): PulledEntryOutput;
+export declare function mapEntryForOutput<T extends EntryForOutput>(entry: T): EntryContentFileOutput;
 /**
  * Parse pagination options from command flags.
  *

package/dist/_dts/sdk/src/cli/merge-remote/entryMergePush.d.ts

@@ -1,5 +1,6 @@
 import { type SiteId } from '../../../../core/src/index';
 import type { ManagementClient } from '../../client/management/types';
+import type { ContentMetadataTarget } from '../content/metadataStore';
 import type { LocalEntry } from '../content/reader';
 import type { EnvTarget } from '../helpers';
 import type { OutputContext } from '../output';
@@ -12,6 +13,7 @@ export declare function planAndReportRemoteEntryMerge(input: Readonly<{
     contentDir: string;
     target: EnvTarget;
     siteId: SiteId;
+    metadataTarget: ContentMetadataTarget;
     contentType?: string;
     identifier?: string;
     localEntries: ReadonlyMap<string, readonly LocalEntry[]>;

package/dist/_dts/sdk/src/cli/merge-remote/mergeFieldChanges.d.ts

@@ -0,0 +1,22 @@
+export type ScalarMergeChangeValue = string | number | boolean | null | undefined;
+export type MergeChange = Readonly<{
+    path: string;
+}> & (Readonly<{
+    value: ScalarMergeChangeValue;
+    containerKind: 'scalar' | 'null';
+}> | Readonly<{
+    value: Record<string, unknown>;
+    containerKind: 'object';
+}> | Readonly<{
+    value: readonly unknown[];
+    containerKind: 'array';
+}>);
+export type ScalarMergeChange = Extract<MergeChange, {
+    containerKind: 'scalar' | 'null';
+}>;
+export declare function collectMergeChanges(currentPath: string, base: unknown, next: unknown, changes: Map<string, MergeChange>): void;
+export declare function firstNestedContainerChange<TChange extends MergeChange>(localChanges: ReadonlyMap<string, TChange>, remoteChanges: ReadonlyMap<string, TChange>): TChange | null;
+export declare function firstSameFieldConflictPath(localChanges: ReadonlyMap<string, MergeChange>, remoteChanges: ReadonlyMap<string, MergeChange>): string | null;
+export declare function scalarMergeChanges<TChange extends MergeChange>(changes: ReadonlyMap<string, TChange>, label: string): readonly Extract<TChange, {
+    containerKind: 'scalar' | 'null';
+}>[];

package/dist/_dts/sdk/src/cli/merge-remote/pageLocal.d.ts

@@ -0,0 +1,3 @@
+import type { PulledPages } from '../../client/management/types';
+import type { LocalPage } from '../content/reader';
+export declare function pulledPageToLocalPage(page: PulledPages['pages'][number]): LocalPage;

package/dist/_dts/sdk/src/cli/merge-remote/pageMerge.d.ts

@@ -0,0 +1,78 @@
+import type { LocalPage } from '../content/reader';
+export type PageMergeSubject = Readonly<{
+    identifier: string;
+}>;
+export type PageMergeInputs = Readonly<{
+    subject: PageMergeSubject;
+    base: LocalPage | null;
+    local: LocalPage | null;
+    remote: LocalPage | null;
+}>;
+export type PageMergeConflict = Readonly<{
+    code: 'missing_base';
+    subject: PageMergeSubject;
+    message: string;
+}> | Readonly<{
+    code: 'same_field_changed';
+    subject: PageMergeSubject;
+    fieldPath: string;
+    message: string;
+}> | Readonly<{
+    code: 'local_delete_unsupported';
+    subject: PageMergeSubject;
+    message: string;
+}> | Readonly<{
+    code: 'remote_delete_local_edit';
+    subject: PageMergeSubject;
+    message: string;
+}> | Readonly<{
+    code: 'unsupported_nested_merge';
+    subject: PageMergeSubject;
+    fieldPath: string;
+    message: string;
+}>;
+export type PageMergeDecision = Readonly<{
+    kind: 'unchanged';
+    subject: PageMergeSubject;
+    desired: LocalPage | null;
+}> | Readonly<{
+    kind: 'bootstrap_base';
+    subject: PageMergeSubject;
+    desired: LocalPage;
+}> | Readonly<{
+    kind: 'preserve_remote';
+    subject: PageMergeSubject;
+    desired: LocalPage | null;
+}> | Readonly<{
+    kind: 'apply_local_create' | 'apply_local_update';
+    subject: PageMergeSubject;
+    desired: LocalPage;
+}> | Readonly<{
+    kind: 'auto_merge';
+    subject: PageMergeSubject;
+    desired: LocalPage;
+    localFieldPaths: readonly string[];
+    remoteFieldPaths: readonly string[];
+}> | Readonly<{
+    kind: 'conflict';
+    subject: PageMergeSubject;
+    conflict: PageMergeConflict;
+}>;
+export type ComparablePage = Readonly<{
+    identifier: string;
+    title: string;
+    path: string;
+    status?: LocalPage['status'];
+    hasUnpublishedChanges?: boolean;
+    seoTitle?: string;
+    seoDescription?: string;
+    blocks?: ReadonlyArray<Readonly<{
+        identifier: string;
+        kind: string;
+        position?: number;
+        data: Readonly<Record<string, unknown>>;
+    }>>;
+}>;
+export declare function planPageMerge(input: PageMergeInputs): PageMergeDecision;
+export declare function comparablePage(page: LocalPage | null): ComparablePage | null;
+export declare function pagesEqual(left: LocalPage | null, right: LocalPage | null): boolean;

package/dist/_dts/sdk/src/cli/merge-remote/pageMergePlan.d.ts

@@ -0,0 +1,36 @@
+import type { PulledPages } from '../../client/management/types';
+import type { LocalPage } from '../content/reader';
+import { type PageMergeDecision } from './pageMerge';
+import { type PageBaseSnapshotTarget } from './pageSnapshots';
+export type PageMergePushScope = Readonly<{
+    kind: 'all_pages';
+}> | Readonly<{
+    kind: 'single_page';
+    identifier: string;
+}>;
+export type RemotePageMergePlan = Readonly<{
+    scope: PageMergePushScope;
+    decisions: readonly PageMergeDecision[];
+    summary: RemotePageMergePlanSummary;
+}>;
+export type RemotePageMergePlanSummary = Readonly<{
+    unchanged: number;
+    bootstrapBase: number;
+    preserveRemote: number;
+    applyLocalCreate: number;
+    applyLocalUpdate: number;
+    autoMerge: number;
+    conflicts: number;
+}>;
+export type RemotePageMergePlanInput = Readonly<{
+    contentDir: string;
+    target: PageBaseSnapshotTarget;
+    scope: PageMergePushScope;
+    localPages: readonly LocalPage[];
+    remotePages: readonly PulledPages['pages'][number][];
+}>;
+export declare function buildRemotePageMergePlan(input: RemotePageMergePlanInput): Promise<RemotePageMergePlan>;
+export declare function summarizePageMergeDecisions(decisions: readonly PageMergeDecision[]): RemotePageMergePlanSummary;
+export declare function pageMergePushScope(input: Readonly<{
+    identifier?: string;
+}>): PageMergePushScope;

package/dist/_dts/sdk/src/cli/merge-remote/pageMergePush.d.ts

@@ -0,0 +1,23 @@
+import type { SiteId } from '../../../../core/src/index';
+import type { ManagementClient } from '../../client/management/types';
+import type { ContentMetadataTarget } from '../content/metadataStore';
+import type { LocalPage } from '../content/reader';
+import type { EnvTarget } from '../helpers';
+import type { OutputContext } from '../output';
+export type RemotePageMergePushResult = Readonly<{
+    success: boolean;
+}>;
+export declare function planAndReportRemotePageMerge(input: Readonly<{
+    output: OutputContext;
+    client: Pick<ManagementClient, 'pages' | 'blocks' | 'pull'>;
+    contentDir: string;
+    target: EnvTarget;
+    siteId: SiteId;
+    metadataTarget: ContentMetadataTarget;
+    identifier?: string;
+    localPages: readonly LocalPage[];
+    dryRun: boolean;
+    jsonOutput: boolean;
+    jsonDiff: boolean;
+    skipMeta: boolean;
+}>): Promise<RemotePageMergePushResult>;

package/dist/_dts/sdk/src/cli/merge-remote/pageMergeReport.d.ts

@@ -0,0 +1,29 @@
+import type { OutputContext } from '../output';
+import type { PageMergeConflict, PageMergeDecision } from './pageMerge';
+import type { RemotePageMergePlan } from './pageMergePlan';
+export type RemotePageMergeJsonReport = Readonly<{
+    kind: 'push';
+    scope: 'pages';
+    mergeRemote: true;
+    dryRun: boolean;
+    summary: RemotePageMergePlan['summary'];
+    decisions: readonly RemotePageMergeDecisionReport[];
+}>;
+export type RemotePageMergeDecisionReport = Readonly<{
+    kind: PageMergeDecision['kind'];
+    identifier: string;
+    localFieldPaths?: readonly string[];
+    remoteFieldPaths?: readonly string[];
+    conflict?: Readonly<{
+        code: PageMergeConflict['code'];
+        fieldPath?: string;
+        message: string;
+    }>;
+}>;
+export declare function remotePageMergeJsonReport(input: Readonly<{
+    plan: RemotePageMergePlan;
+    dryRun: boolean;
+}>): RemotePageMergeJsonReport;
+export declare function writeRemotePageMergeHumanReport(output: Pick<OutputContext, 'info'>, plan: RemotePageMergePlan, options: Readonly<{
+    dryRun: boolean;
+}>): void;

package/dist/_dts/sdk/src/cli/merge-remote/pageSnapshots.d.ts

@@ -0,0 +1,48 @@
+import type { PulledPages } from '../../client/management/types';
+import type { EnvTarget } from '../helpers';
+import type { LocalPage } from '../content/reader';
+export type PageBaseSnapshotTarget = Readonly<{
+    env: EnvTarget;
+    siteId: string;
+}>;
+export type PageBaseSnapshotSubject = Readonly<{
+    identifier: string;
+}>;
+export type PageBaseSnapshot = Readonly<{
+    version: 'page-base.v1';
+    target: Readonly<{
+        env: EnvTarget;
+        siteIdHash: string;
+    }>;
+    subject: PageBaseSnapshotSubject;
+    pulledAt: string;
+    remoteVersion: Readonly<{
+        createdAt?: string;
+        updatedAt?: string;
+        publishedAt?: string | null;
+    }>;
+    page: LocalPage;
+}>;
+export type WritePageBaseSnapshotsInput = Readonly<{
+    contentDir: string;
+    target: PageBaseSnapshotTarget;
+    pages: PulledPages['pages'];
+    meta: PulledPages['meta'];
+    cleanupMissing?: boolean;
+}>;
+export type WritePageBaseSnapshotsResult = Readonly<{
+    rootDir: string;
+    count: number;
+}>;
+export declare function pageBaseSnapshotRoot(contentDir: string): string;
+export declare function pageBaseSnapshotPath(input: Readonly<{
+    contentDir: string;
+    target: PageBaseSnapshotTarget;
+    subject: PageBaseSnapshotSubject;
+}>): string;
+export declare function writePageBaseSnapshots(input: WritePageBaseSnapshotsInput): Promise<WritePageBaseSnapshotsResult>;
+export declare function readPageBaseSnapshot(input: Readonly<{
+    contentDir: string;
+    target: PageBaseSnapshotTarget;
+    subject: PageBaseSnapshotSubject;
+}>): Promise<PageBaseSnapshot | null>;

package/dist/_dts/sdk/src/cli/push-config.d.ts

@@ -11,18 +11,29 @@ interface PushConfigOptions {
     apiKey?: string;
     dashboard: string;
     forceContentTypes?: boolean;
+    dryRun?: boolean;
 }
+export type PushConfigActionResult = Readonly<{
+    success: true;
+}> | Readonly<{
+    success: false;
+}>;
 type PushConfigResponse = NonNullable<APIEndpoints['pushSdkConfig']['response']>;
 type PushConfigSync = NonNullable<PushConfigResponse['configSync']>;
 type LegacyPushConfigSync = NonNullable<PushConfigResponse['sync']>;
 type PushConfigDisplaySync = PushConfigSync | LegacyPushConfigSync;
 type PushConfigSyncArea = 'contentTypes' | 'customBlocks' | 'templateBlocks' | 'settings' | 'ignoredDocuments' | 'pages' | 'entries' | 'navigationMenus';
-type PushConfigSyncMessage = {
+export type PushConfigSyncMessage = {
     area: PushConfigSyncArea;
     message: string;
 };
 export declare function collectPushConfigSyncErrors(sync: PushConfigDisplaySync): PushConfigSyncMessage[];
 export declare function collectPushConfigSyncWarnings(sync: PushConfigDisplaySync): PushConfigSyncMessage[];
+export declare function groupPushConfigSyncWarningsForHuman(warnings: readonly PushConfigSyncMessage[]): PushConfigSyncMessage[];
+export declare function isPushConfigActionSuccess(result: PushConfigActionResult): result is Extract<PushConfigActionResult, {
+    success: true;
+}>;
+export declare function markFailedPushConfigCommandResult(result: PushConfigActionResult): void;
 /**
  * Main push-config action.
  * Exported for reuse by `push --with-config`.
@@ -30,7 +41,7 @@ export declare function collectPushConfigSyncWarnings(sync: PushConfigDisplaySyn
 export declare function pushConfigAction(output: OutputContext, options: PushConfigOptions & {
     isRemote: boolean;
     isJsonOutput?: boolean;
-}): Promise<void>;
+}): Promise<PushConfigActionResult>;
 /**
  * push-config command definition
  */

package/dist/_dts/sdk/src/cli/setup/setupPlan.d.ts

@@ -0,0 +1,51 @@
+import type { EnvTarget } from '../helpers';
+export type SetupOperation = 'create_site' | 'create_management_key' | 'grant_user_access' | 'configure_env' | 'verify_access';
+export type SetupAuthority = 'dashboard_admin' | 'cms_repo_script' | 'sdk_management_key';
+export type SetupPlanStep = Readonly<{
+    tag: 'admin_action';
+    operation: Exclude<SetupOperation, 'configure_env' | 'verify_access'>;
+    title: string;
+    detail: string;
+    allowedAuthorities: readonly Exclude<SetupAuthority, 'sdk_management_key'>[];
+}> | Readonly<{
+    tag: 'local_env';
+    operation: 'configure_env';
+    title: string;
+    detail: string;
+    missingVariables: readonly string[];
+    exampleLines: readonly string[];
+}> | Readonly<{
+    tag: 'cli_check';
+    operation: 'verify_access';
+    title: string;
+    detail: string;
+    commands: readonly string[];
+}>;
+export type SetupCapability = Readonly<{
+    authority: 'dashboard_admin';
+    can: readonly ('create_site' | 'create_management_key' | 'grant_user_access')[];
+}> | Readonly<{
+    authority: 'cms_repo_script';
+    can: readonly ('create_site' | 'create_management_key' | 'grant_user_access')[];
+    requirement: string;
+}> | Readonly<{
+    authority: 'sdk_management_key';
+    can: readonly ('verify_access')[];
+    cannot: readonly ('create_site' | 'create_management_key' | 'grant_user_access')[];
+}>;
+export interface SetupTargetStatus {
+    target: EnvTarget;
+    siteId: string | null;
+    dashboardUrl: string | null;
+    managementApiKeySet: boolean;
+}
+export interface SdkSetupPlan {
+    target: EnvTarget;
+    configured: boolean;
+    canMutatePrivilegedResources: false;
+    capabilities: readonly SetupCapability[];
+    steps: readonly SetupPlanStep[];
+    securityNotes: readonly string[];
+}
+export declare function planSdkSetup(status: SetupTargetStatus): SdkSetupPlan;
+export declare function formatSdkSetupPlan(plan: SdkSetupPlan): string;

package/dist/_dts/sdk/src/cli/site-commands/commandRuntime.d.ts

@@ -1,5 +1,6 @@
 import { type Result, type SiteId } from '../../../../core/src/index';
 import { type DryRunReport, type SiteCommandBatch, type SiteCommandExecutionSuccess, type SiteCommandOf, type SiteCommandPlanFor, type SiteCommandRef, type SiteCommandType, type SiteCommandValidationError } from '../../../../site-commands/src/index';
+import { type ManagementApiErrorRequest } from '../../client/management';
 import type { EnvTarget } from '../helpers';
 export type CliCommandBatchRefInput<TSource extends string = string> = Readonly<{
     source: TSource;
@@ -11,6 +12,22 @@ export type CliCommandExecutionError<TCommandType extends SiteCommandType> = Rea
     commandRef: SiteCommandRef;
     commandType: TCommandType;
     message: string;
+    detail?: CliCommandFailureDetail;
+}>;
+export type CliCommandFailureFieldError = Readonly<{
+    field: string;
+    message: string;
+    code?: string;
+}>;
+export type CliCommandFailureDetail = Readonly<{
+    tag: 'management_api';
+    code: string;
+    statusCode?: number;
+    request?: ManagementApiErrorRequest;
+    fieldErrors: readonly CliCommandFailureFieldError[];
+    details?: unknown;
+}> | Readonly<{
+    tag: 'unknown';
 }>;
 export type CliCommandExecutionResult<TCommandType extends SiteCommandType> = Readonly<{
     status: 'applied';
@@ -43,6 +60,7 @@ export type CliCommandReportedPlannedCommand<TCommand extends Readonly<{
 export type CliCommandExecutionReportFailure<TSubject> = Readonly<{
     identifier: string;
     message: string;
+    detail?: CliCommandFailureDetail;
     subject?: TSubject;
 }>;
 export type CliCommandOutcome<TSubject> = Readonly<{
@@ -56,6 +74,7 @@ export type CliCommandOutcome<TSubject> = Readonly<{
     commandType: SiteCommandType;
     identifier: string;
     message: string;
+    detail?: CliCommandFailureDetail;
     subject?: TSubject;
 }> | Readonly<{
     status: 'skipped_by_stop_policy';
@@ -97,6 +116,7 @@ export declare function createCliCommandBatchRef(input: CliCommandBatchRefInput)
 export declare function formatSiteCommandValidationErrors(errors: readonly {
     message: string;
 }[]): string;
+export declare function managementErrorDetail(error: unknown): CliCommandFailureDetail;
 export declare function formatManagementError(error: unknown): string;
 export declare function planCliCommandBatchForTypes<TCommandType extends SiteCommandType>(input: CliCommandBatchRefInput & Readonly<{
     commands: readonly SiteCommandOf<TCommandType>[];
@@ -126,6 +146,7 @@ export declare function commandExecutionToReport<TCommand extends Readonly<{
 export declare function commandCompileFailureToReport<TSubject>(input: Readonly<{
     identifier: string;
     message: string;
+    detail?: CliCommandFailureDetail;
     subject?: TSubject;
     warnings?: readonly string[];
 }>): CliCommandExecutionReport<TSubject>;

package/dist/_dts/sdk/src/cli/sync/diff.d.ts

@@ -6,6 +6,8 @@
  */
 import type { LocalContent, LocalFooterContent } from '../content/reader';
 import type { PulledContent, ManagementFooterContent } from '../../client/management/types';
+import { type BuildFieldDiffOptions, type FieldChange } from './field-diff';
+export type { FieldChange } from './field-diff';
 export type DiffType = 'create' | 'update' | 'unchanged';
 export interface EntryDiff {
     type: DiffType | 'delete';
@@ -205,15 +207,10 @@ export declare function formatDiffDetail(diff: ContentDiff): string;
  * @returns Content diff showing what would be created/updated locally
  */
 export declare function calculatePullDiff(remote: PulledContent, local: LocalContent | null): ContentDiff;
-export interface FieldChange {
-    path: string;
-    before: unknown;
-    after: unknown;
-}
 /**
  * Find changed fields between two objects with their before/after values.
  */
-export declare function findChangedFieldsWithValues(local: Record<string, unknown>, remote: Record<string, unknown>, prefix?: string): FieldChange[];
+export declare function findChangedFieldsWithValues(local: Record<string, unknown>, remote: Record<string, unknown>, prefix?: string, options?: BuildFieldDiffOptions): FieldChange[];
 /**
  * Format a value for human-readable display.
  */