sf-plugin-cms 0.1.0 → 0.3.0

package/lib/services/bulk-export-workspaces.js

@@ -0,0 +1,272 @@
+import { createHash } from 'node:crypto';
+import { mkdir, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { assertCmsEnvelope, MAX_DIAGNOSTICS_PER_KIND, sanitizeDiagnostics, } from '../contracts/shared.js';
+import { assertWorkspaceExportSetResult, WORKSPACE_EXPORT_MANIFEST_CONTRACT, WORKSPACE_EXPORT_SET_CONTRACT, } from '../contracts/workspace-export.js';
+import { redactSecrets } from '../transport/redact-secrets.js';
+import { exportWorkspace, safeWorkspaceDirectoryName } from './export-workspace.js';
+import { getWorkspace } from './read.js';
+import { enumerateWorkspaces } from './resolve-workspace.js';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function nonemptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+function folded(value) {
+    return value.normalize('NFKC').toLocaleLowerCase('en-US');
+}
+function actualWorkspaceType(workspace) {
+    const spaceType = workspace.spaceType;
+    if (typeof spaceType === 'string')
+        return normalizeWorkspaceType(spaceType);
+    if (isRecord(spaceType) && typeof spaceType.apiName === 'string') {
+        return normalizeWorkspaceType(spaceType.apiName);
+    }
+    return normalizeWorkspaceType();
+}
+export function normalizeWorkspaceType(value) {
+    if (typeof value === 'string') {
+        const normalized = value.toLocaleLowerCase('en-US');
+        if (normalized === 'marketing')
+            return 'Marketing';
+        if (normalized === 'content')
+            return 'Content';
+    }
+    throw new Error('Workspace type must be Marketing or Content.');
+}
+async function exists(candidate) {
+    try {
+        await stat(candidate);
+        return true;
+    }
+    catch (error) {
+        if (isRecord(error) && error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+async function assertParentCompatible(parent) {
+    let cursor = path.resolve(parent);
+    for (;;) {
+        try {
+            const information = await stat(cursor);
+            if (!information.isDirectory()) {
+                throw new Error(`Bulk output parent is not a directory: ${cursor}`);
+            }
+            return;
+        }
+        catch (error) {
+            if (!isRecord(error) || error.code !== 'ENOENT')
+                throw error;
+        }
+        const next = path.dirname(cursor);
+        if (next === cursor)
+            throw new Error(`Bulk output parent is not usable: ${parent}`);
+        cursor = next;
+    }
+}
+function normalizedError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return (redactSecrets(message)
+        .replaceAll(/[\r\n]+/gu, ' ')
+        .trim() || 'Workspace export failed.');
+}
+function portableOutputPath(value) {
+    const portable = value.split(path.sep).join('/');
+    if (/^[A-Za-z]:/u.test(portable) || portable.startsWith('/'))
+        return path.basename(value);
+    return portable.startsWith('./') ? portable : `./${portable}`;
+}
+function relativeArtifactPath(outputDirectory, destination) {
+    return path.relative(outputDirectory, destination).split(path.sep).join('/');
+}
+function hashExportSet(result) {
+    return `export-set:${createHash('sha256').update(JSON.stringify(result)).digest('hex')}`;
+}
+export async function preflightBulkWorkspaceExport(connection, outputDirectory, workspaceType, options = {}) {
+    const listed = await enumerateWorkspaces(connection, options);
+    const canonical = [];
+    const canonicalNames = new Map();
+    for (const summary of listed) {
+        const workspace = await getWorkspace(connection, summary.id, options);
+        if (workspace.id !== summary.id || !nonemptyString(workspace.name)) {
+            throw new Error(`Canonical workspace ${summary.id} returned a malformed or mismatched ID/name.`);
+        }
+        const nameKey = folded(workspace.name);
+        const existingNameId = canonicalNames.get(nameKey);
+        if (existingNameId !== undefined && existingNameId !== summary.id) {
+            throw new Error(`Workspace names for IDs ${existingNameId} and ${summary.id} differ only by case or Unicode normalization and are ambiguous.`);
+        }
+        canonicalNames.set(nameKey, summary.id);
+        const type = actualWorkspaceType(workspace);
+        if (workspaceType !== undefined && type !== workspaceType)
+            continue;
+        canonical.push({
+            id: summary.id,
+            name: workspace.name,
+            type,
+            destination: path.join(outputDirectory, safeWorkspaceDirectoryName(workspace.name)),
+        });
+    }
+    canonical.sort((left, right) => left.id.localeCompare(right.id, 'en-US'));
+    await assertParentCompatible(outputDirectory);
+    const destinations = new Map();
+    for (const workspace of canonical) {
+        if (await exists(workspace.destination)) {
+            throw new Error(`Export destination already exists: ${workspace.destination}`);
+        }
+        const destinationKey = folded(path.resolve(workspace.destination));
+        const existing = destinations.get(destinationKey);
+        if (existing !== undefined) {
+            throw new Error(`Workspace destinations collide after sanitization: ${existing.id} (${existing.name}) and ${workspace.id} (${workspace.name}).`);
+        }
+        destinations.set(destinationKey, workspace);
+    }
+    return { discoveredCount: listed.length, selected: canonical };
+}
+export async function exportAllWorkspaces(connection, outputDirectory, workspaceType, options = {}) {
+    const generatedAt = options.generatedAt ?? new Date().toISOString();
+    const pluginVersion = options.pluginVersion ?? '0.3.0';
+    const sourceOrgId = options.sourceOrgId ?? 'unknown-org';
+    const preflight = await preflightBulkWorkspaceExport(connection, outputDirectory, workspaceType, options);
+    if (preflight.selected.length > 0)
+        await mkdir(outputDirectory, { recursive: true });
+    const workspaces = [];
+    const externalReferenceCorrelations = [];
+    for (const workspace of preflight.selected) {
+        const artifactPath = relativeArtifactPath(outputDirectory, workspace.destination);
+        try {
+            const exported = await exportWorkspace(connection, workspace.id, workspace.destination, {
+                ...options,
+                generatedAt,
+                pluginVersion,
+                sourceOrgId,
+            });
+            const partial = exported.manifest.completeness === 'partial';
+            for (const reference of exported.manifest.externalReferences) {
+                if (reference.resolution !== 'included' || reference.kind !== 'cms.content')
+                    continue;
+                externalReferenceCorrelations.push({
+                    sourceWorkspaceId: workspace.id,
+                    sourceReference: reference.portableKey.value,
+                    referenceKind: reference.kind,
+                    referenceId: reference.referenceId,
+                    packageManifestSha256: exported.manifestSha256,
+                });
+            }
+            const warnings = partial
+                ? exported.manifest.warnings.map(({ code, message }) => ({ code, message }))
+                : [];
+            workspaces.push({
+                source: {
+                    kind: 'cms.workspace',
+                    sourceId: workspace.id,
+                    name: workspace.name,
+                    workspaceType: workspace.type,
+                },
+                status: partial ? 'partial' : 'success',
+                artifact: {
+                    path: artifactPath,
+                    manifestPath: `${artifactPath}/manifest.json`,
+                    manifestContract: WORKSPACE_EXPORT_MANIFEST_CONTRACT,
+                    manifestContractVersion: '1.0.0',
+                    manifestSha256: exported.manifestSha256,
+                },
+                diagnostics: { warnings, errors: [] },
+            });
+        }
+        catch (error) {
+            workspaces.push({
+                source: {
+                    kind: 'cms.workspace',
+                    sourceId: workspace.id,
+                    name: workspace.name,
+                    workspaceType: workspace.type,
+                },
+                status: 'failed',
+                artifact: null,
+                diagnostics: {
+                    warnings: [],
+                    errors: [{ code: 'WORKSPACE_EXPORT_FAILED', message: normalizedError(error) }],
+                },
+            });
+        }
+    }
+    externalReferenceCorrelations.sort((left, right) => [
+        left.sourceWorkspaceId,
+        left.sourceReference,
+        left.referenceKind,
+        left.referenceId,
+        left.packageManifestSha256,
+    ]
+        .join('\u0000')
+        .localeCompare([
+        right.sourceWorkspaceId,
+        right.sourceReference,
+        right.referenceKind,
+        right.referenceId,
+        right.packageManifestSha256,
+    ].join('\u0000')));
+    const result = {
+        workspaceType,
+        outputDirectory: portableOutputPath(outputDirectory),
+        selection: {
+            mode: 'all',
+            discoveredCount: preflight.discoveredCount,
+            selectedCount: workspaces.length,
+        },
+        summary: {
+            succeededCount: workspaces.filter(({ status }) => status === 'success').length,
+            partialCount: workspaces.filter(({ status }) => status === 'partial').length,
+            failedCount: workspaces.filter(({ status }) => status === 'failed').length,
+        },
+        externalReferenceCorrelations,
+        workspaces,
+    };
+    let status = 'success';
+    if (result.summary.failedCount === workspaces.length && workspaces.length > 0)
+        status = 'failed';
+    else if (result.summary.failedCount > 0 || result.summary.partialCount > 0)
+        status = 'partial';
+    const errors = aggregateDiagnostics(workspaces, 'errors');
+    const warnings = aggregateDiagnostics(workspaces, 'warnings');
+    const envelope = {
+        contract: WORKSPACE_EXPORT_SET_CONTRACT,
+        contractVersion: '1.0.0',
+        status,
+        metadata: {
+            operation: 'workspace.export.bulk',
+            plugin: { name: 'sf-plugin-cms', version: pluginVersion },
+            apiVersion: options.apiVersion ?? '67.0',
+        },
+        diagnostics: { warnings, errors },
+        provenance: {
+            producer: 'sf-plugin-cms',
+            sourceOrgId,
+            pluginVersion,
+            exportSetId: hashExportSet(result),
+            command: 'sf cms export workspace',
+            generatedAt,
+        },
+        result,
+    };
+    assertCmsEnvelope(envelope, assertWorkspaceExportSetResult);
+    return envelope;
+}
+function aggregateDiagnostics(workspaces, kind) {
+    const diagnostics = workspaces.flatMap(({ source, diagnostics: workspaceDiagnostics }) => workspaceDiagnostics[kind].map((diagnostic) => ({ ...diagnostic, scope: source.sourceId })));
+    if (diagnostics.length <= MAX_DIAGNOSTICS_PER_KIND) {
+        return sanitizeDiagnostics(diagnostics, `diagnostics.${kind}`);
+    }
+    const omitted = diagnostics.length - MAX_DIAGNOSTICS_PER_KIND + 1;
+    return sanitizeDiagnostics([
+        ...diagnostics.slice(0, MAX_DIAGNOSTICS_PER_KIND - 1),
+        {
+            code: 'DIAGNOSTICS_TRUNCATED',
+            message: `${omitted} additional ${kind} omitted from aggregate diagnostics; per-workspace diagnostics remain complete.`,
+            retryable: false,
+        },
+    ], `diagnostics.${kind}`);
+}
+//# sourceMappingURL=bulk-export-workspaces.js.map

package/lib/services/bulk-export-workspaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bulk-export-workspaces.js","sourceRoot":"","sources":["../../src/services/bulk-export-workspaces.ts"],"names":[],"mappings":"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"}

package/lib/services/export-references.d.ts

@@ -0,0 +1,21 @@
+import type { OpaqueCmsReference } from '../contracts/shared.js';
+import type { CmsRecord } from './read.js';
+export type ExportReferenceWarning = {
+    code: 'REFERENCE_UNRESOLVED' | 'REFERENCE_UNSUPPORTED';
+    message: string;
+    variantIds: string[];
+};
+export type ExportReferenceInventory = {
+    dependencies: string[];
+    externalReferences: OpaqueCmsReference[];
+    itemReferenceIds: ReadonlyMap<string, string>;
+    warnings: ExportReferenceWarning[];
+};
+/**
+ * Inventories only the CMS content identity fields retained in exported variant payloads.
+ * Unknown payload fields are deliberately not interpreted as relationships.
+ * @param {string} workspaceId - Canonical source CMS workspace identifier.
+ * @param {ReadonlyMap<string, CmsRecord>} details - Exported variants keyed by variant ID.
+ * @returns {ExportReferenceInventory} Deterministic included and unresolved reference evidence.
+ */
+export declare function inventoryExportReferences(workspaceId: string, details: ReadonlyMap<string, CmsRecord>): ExportReferenceInventory;

package/lib/services/export-references.js

@@ -0,0 +1,150 @@
+import { createHash } from 'node:crypto';
+function nonemptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+function referenceId(workspaceId, kind, sourceId) {
+    const identity = JSON.stringify({ kind, sourceId, workspaceId });
+    return `ref:${createHash('sha256').update(identity).digest('hex')}`;
+}
+function containsCmsContentBodyReference(value) {
+    if (Array.isArray(value))
+        return value.some((item_) => containsCmsContentBodyReference(item_));
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const record = value;
+    if (typeof record.ref === 'object' &&
+        record.ref !== null &&
+        nonemptyString(record.ref.contentKey)) {
+        return true;
+    }
+    return Object.values(record).some((item_) => containsCmsContentBodyReference(item_));
+}
+function compareReferences(left, right) {
+    return [left.kind, left.referenceId, left.portableKey.value]
+        .join('\u0000')
+        .localeCompare([right.kind, right.referenceId, right.portableKey.value].join('\u0000'));
+}
+/**
+ * Inventories only the CMS content identity fields retained in exported variant payloads.
+ * Unknown payload fields are deliberately not interpreted as relationships.
+ * @param {string} workspaceId - Canonical source CMS workspace identifier.
+ * @param {ReadonlyMap<string, CmsRecord>} details - Exported variants keyed by variant ID.
+ * @returns {ExportReferenceInventory} Deterministic included and unresolved reference evidence.
+ */
+export function inventoryExportReferences(workspaceId, details) {
+    const candidates = [];
+    const externalReferences = [];
+    const itemReferenceIds = new Map();
+    const warnings = [];
+    const includedById = new Map();
+    for (const [variantId, detail] of details) {
+        if ('references' in detail ||
+            'referencesList' in detail ||
+            containsCmsContentBodyReference(detail.contentBody)) {
+            const id = referenceId(workspaceId, 'cms.relationship', variantId);
+            externalReferences.push({
+                referenceId: id,
+                owner: 'cms',
+                kind: 'cms.relationship',
+                source: { workspaceId, sourceId: variantId },
+                portableKey: { scheme: 'cms-opaque-v1', value: variantId },
+                required: true,
+                resolution: 'unsupported',
+            });
+            warnings.push({
+                code: 'REFERENCE_UNSUPPORTED',
+                message: 'The exported CMS payload contains a relationship class without an evidenced portable resolver.',
+                variantIds: [variantId],
+            });
+        }
+        if (!nonemptyString(detail.contentKey))
+            continue;
+        candidates.push({
+            contentId: nonemptyString(detail.contentId) ? detail.contentId : undefined,
+            contentKey: detail.contentKey,
+            variantId,
+        });
+    }
+    const idsByKey = new Map();
+    const keysById = new Map();
+    const incompleteKeys = new Set();
+    for (const candidate of candidates) {
+        if (candidate.contentId === undefined) {
+            incompleteKeys.add(candidate.contentKey);
+            continue;
+        }
+        const ids = idsByKey.get(candidate.contentKey) ?? new Set();
+        ids.add(candidate.contentId);
+        idsByKey.set(candidate.contentKey, ids);
+        const keys = keysById.get(candidate.contentId) ?? new Set();
+        keys.add(candidate.contentKey);
+        keysById.set(candidate.contentId, keys);
+    }
+    for (const candidate of candidates.toSorted((left, right) => left.variantId.localeCompare(right.variantId))) {
+        const conflicting = candidate.contentId !== undefined &&
+            ((idsByKey.get(candidate.contentKey)?.size ?? 0) > 1 ||
+                incompleteKeys.has(candidate.contentKey) ||
+                (keysById.get(candidate.contentId)?.size ?? 0) > 1);
+        if (conflicting) {
+            const id = referenceId(workspaceId, 'cms.unknown', candidate.variantId);
+            externalReferences.push({
+                referenceId: id,
+                owner: 'cms',
+                kind: 'cms.unknown',
+                source: { workspaceId, sourceId: candidate.variantId },
+                portableKey: { scheme: 'cms-opaque-v1', value: candidate.contentKey },
+                required: true,
+                resolution: 'unsupported',
+            });
+            warnings.push({
+                code: 'REFERENCE_UNSUPPORTED',
+                message: 'A CMS content reference has conflicting retained identity evidence.',
+                variantIds: [candidate.variantId],
+            });
+            continue;
+        }
+        if (candidate.contentId === undefined) {
+            const id = referenceId(workspaceId, 'cms.unknown', candidate.variantId);
+            externalReferences.push({
+                referenceId: id,
+                owner: 'cms',
+                kind: 'cms.unknown',
+                source: { workspaceId, sourceId: candidate.variantId },
+                portableKey: { scheme: 'cms-opaque-v1', value: candidate.contentKey },
+                required: true,
+                resolution: 'unresolved',
+            });
+            warnings.push({
+                code: 'REFERENCE_UNRESOLVED',
+                message: 'A CMS content reference lacks retained canonical content identity.',
+                variantIds: [candidate.variantId],
+            });
+            continue;
+        }
+        const id = referenceId(workspaceId, 'cms.content', candidate.contentId);
+        itemReferenceIds.set(candidate.variantId, id);
+        if (!includedById.has(candidate.contentId)) {
+            includedById.set(candidate.contentId, {
+                referenceId: id,
+                owner: 'cms',
+                kind: 'cms.content',
+                source: { workspaceId, sourceId: candidate.contentId },
+                portableKey: { scheme: 'cms-opaque-v1', value: candidate.contentKey },
+                required: true,
+                resolution: 'included',
+            });
+        }
+    }
+    externalReferences.push(...includedById.values());
+    externalReferences.sort(compareReferences);
+    warnings.sort((left, right) => [left.code, left.variantIds.join('\u0000')]
+        .join('\u0000')
+        .localeCompare([right.code, right.variantIds.join('\u0000')].join('\u0000')));
+    return {
+        dependencies: [],
+        externalReferences,
+        itemReferenceIds,
+        warnings,
+    };
+}
+//# sourceMappingURL=export-references.js.map

package/lib/services/export-references.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"export-references.js","sourceRoot":"","sources":["../../src/services/export-references.ts"],"names":[],"mappings":"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"}

package/lib/services/export-workspace.d.ts

@@ -1,7 +1,9 @@
 import type { Connection } from '@salesforce/core';
+import { type WorkspaceExportManifest } from '../contracts/workspace-export.js';
+export type { WorkspaceExportManifest } from '../contracts/workspace-export.js';
 import { type JsonRequestOptions } from '../transport/json-request.js';
 export type WorkspaceExportWarning = {
-    code: 'COUNT_MISMATCH' | 'DETAIL_FAILED' | 'DUPLICATE_VARIANTS' | 'OWNERSHIP_MISMATCH' | 'PREMATURE_EMPTY_PAGE' | 'UNSUPPORTED_WILDCARD';
+    code: 'COUNT_MISMATCH' | 'DETAIL_FAILED' | 'DUPLICATE_VARIANTS' | 'OWNERSHIP_MISMATCH' | 'PREMATURE_EMPTY_PAGE' | 'REFERENCE_UNRESOLVED' | 'REFERENCE_UNSUPPORTED' | 'UNSUPPORTED_WILDCARD';
     message: string;
     variantIds?: string[];
 };
@@ -9,29 +11,17 @@ export type WorkspaceExportEntry = {
     file: string;
     variantId: string;
 };
-export type WorkspaceExportManifest = {
-    schemaVersion: 1;
-    mode: 'experimental-best-effort';
-    workspaceId: string;
-    search: {
-        contentSpaceOrFolderIds: [string];
-        languages: ['All'];
-        pageSize: 250;
-        queryTerm: '*';
-    };
-    expectedCount: number;
-    foundCount: number;
-    exportedCount: number;
-    pagesRequested: number;
-    entries: WorkspaceExportEntry[];
-    rejectedVariantIds: string[];
-    failedVariantIds: string[];
-    warnings: WorkspaceExportWarning[];
-};
 export type ExportWorkspaceResult = {
     destination: string;
     manifest: WorkspaceExportManifest;
+    manifestSha256: string;
+};
+export type ExportWorkspaceOptions = JsonRequestOptions & {
+    sourceOrgId?: string;
+    pluginVersion?: string;
+    generatedAt?: string;
 };
 type RequestConnection = Pick<Connection, 'request'>;
-export declare function exportWorkspace(connection: RequestConnection, workspaceId: string, destination: string, options?: JsonRequestOptions): Promise<ExportWorkspaceResult>;
-export {};
+export declare function safeWorkspaceDirectoryName(workspaceName: string): string;
+export declare function defaultWorkspaceDestination(workspaceName: string): string;
+export declare function exportWorkspace(connection: RequestConnection, workspaceId: string, destination: string, options?: ExportWorkspaceOptions): Promise<ExportWorkspaceResult>;

package/lib/services/export-workspace.js

@@ -1,6 +1,9 @@
-import { mkdir, open, rename, rm, stat } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { lstat, mkdir, open, readdir, readFile, rename, rm, stat } from 'node:fs/promises';
 import path from 'node:path';
+import { assertWorkspaceExportManifest, WORKSPACE_EXPORT_MANIFEST_CONTRACT, } from '../contracts/workspace-export.js';
 import { getSelectedOperation, requestJson, } from '../transport/json-request.js';
+import { inventoryExportReferences } from './export-references.js';
 import { getVariant } from './read.js';
 const PAGE_SIZE = 250;
 const ABSOLUTE_PAGE_CAP = 1000;
@@ -39,6 +42,31 @@ function detailWorkspaceId(detail) {
 function jsonBytes(value) {
     return `${JSON.stringify(value, null, 2)}\n`;
 }
+function sha256(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+const WINDOWS_RESERVED_NAME = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\..*)?$/iu;
+export function safeWorkspaceDirectoryName(workspaceName) {
+    const replaced = [...workspaceName]
+        .map((character) => {
+        const codePoint = character.codePointAt(0) ?? 0;
+        return codePoint <= 31 || codePoint === 127 || /[\\/<>:"|?*]/u.test(character)
+            ? '_'
+            : character;
+    })
+        .join('');
+    const safeName = replaced.replaceAll(/[. ]+$/gu, '');
+    if (safeName.length === 0 ||
+        safeName === '.' ||
+        safeName === '..' ||
+        WINDOWS_RESERVED_NAME.test(safeName)) {
+        throw new Error(`Workspace name ${workspaceName} cannot be used as a portable directory name. Pass --output-dir explicitly.`);
+    }
+    return safeName;
+}
+export function defaultWorkspaceDestination(workspaceName) {
+    return path.join('.', 'cms', safeWorkspaceDirectoryName(workspaceName));
+}
 async function exists(path) {
     try {
         await stat(path);
@@ -59,6 +87,34 @@ async function writeExclusive(path, value) {
         await handle.close();
     }
 }
+async function assertRegularPackageFiles(root, expectedPaths) {
+    const found = new Set();
+    const visit = async (directory) => {
+        const entries = await readdir(directory, { withFileTypes: true });
+        for (const entry of entries) {
+            const absolute = path.join(directory, entry.name);
+            const relative = path.relative(root, absolute).split(path.sep).join('/');
+            const information = await lstat(absolute);
+            if (information.isSymbolicLink())
+                throw new Error(`Package entry is a symlink: ${relative}`);
+            if (information.isDirectory()) {
+                await visit(absolute);
+            }
+            else if (information.isFile()) {
+                if (relative !== 'manifest.json')
+                    found.add(relative);
+            }
+            else {
+                throw new Error(`Package entry is not a regular file or directory: ${relative}`);
+            }
+        }
+    };
+    await visit(root);
+    if (found.size !== expectedPaths.size ||
+        [...found].some((itemPath) => !expectedPaths.has(itemPath))) {
+        throw new Error('Package regular files do not exactly match manifest items.');
+    }
+}
 export async function exportWorkspace(connection, workspaceId, destination, options = {}) {
     if (!nonemptyString(workspaceId))
         throw new TypeError('workspaceId must be a nonempty string');
@@ -175,6 +231,22 @@ export async function exportWorkspace(connection, workspaceId, destination, opti
         file: `items/${variantId}.json`,
         variantId,
     }));
+    const referenceInventory = inventoryExportReferences(workspaceId, details);
+    warnings.push(...referenceInventory.warnings);
+    const completeness = warnings.some(({ code }) => code !== 'UNSUPPORTED_WILDCARD') ||
+        rejected.size > 0 ||
+        failedIds.length > 0
+        ? 'partial'
+        : 'complete';
+    const manifestItems = entries.map((entry) => {
+        const referenceId = referenceInventory.itemReferenceIds.get(entry.variantId);
+        return {
+            path: entry.file,
+            sha256: sha256(jsonBytes(details.get(entry.variantId))),
+            kind: 'cms.content',
+            ...(referenceId === undefined ? {} : { referenceId }),
+        };
+    });
     const manifest = {
         schemaVersion: 1,
         mode: 'experimental-best-effort',
@@ -193,8 +265,23 @@ export async function exportWorkspace(connection, workspaceId, destination, opti
         rejectedVariantIds: [...rejected].toSorted(),
         failedVariantIds: failedIds.toSorted(),
         warnings,
+        contract: WORKSPACE_EXPORT_MANIFEST_CONTRACT,
+        contractVersion: '1.0.0',
+        provenance: {
+            producer: 'sf-plugin-cms',
+            sourceOrgId: options.sourceOrgId ?? 'unknown-org',
+            sourceWorkspaceId: workspaceId,
+            pluginVersion: options.pluginVersion ?? '0.3.0',
+            generatedAt: options.generatedAt ?? new Date().toISOString(),
+        },
+        completeness,
+        dependencies: referenceInventory.dependencies,
+        externalReferences: referenceInventory.externalReferences,
+        items: manifestItems,
     };
+    assertWorkspaceExportManifest(manifest);
     const parent = path.dirname(destination);
+    await mkdir(parent, { recursive: true });
     const temporary = path.join(parent, `.${path.basename(destination)}.tmp-${process.pid}-${Date.now()}`);
     try {
         await mkdir(temporary);
@@ -202,6 +289,7 @@ export async function exportWorkspace(connection, workspaceId, destination, opti
         for (const entry of entries) {
             await writeExclusive(path.join(temporary, entry.file), details.get(entry.variantId));
         }
+        await assertRegularPackageFiles(temporary, new Set(manifest.items.map(({ path }) => path)));
         await writeExclusive(path.join(temporary, 'manifest.json'), manifest);
         await rename(temporary, destination);
     }
@@ -209,6 +297,7 @@ export async function exportWorkspace(connection, workspaceId, destination, opti
         await rm(temporary, { force: true, recursive: true });
         throw error;
     }
-    return { destination, manifest };
+    const manifestSha256 = sha256(await readFile(path.join(destination, 'manifest.json')));
+    return { destination, manifest, manifestSha256 };
 }
 //# sourceMappingURL=export-workspace.js.map