sf-plugin-cms 0.1.0 → 0.3.0

package/lib/contracts/shared.d.ts

@@ -0,0 +1,81 @@
+export declare const CMS_CONTRACT_MAJOR: 1;
+export declare const CMS_CONTRACT_VERSION: "1.0.0";
+export declare const CMS_PLUGIN_NAME: "sf-plugin-cms";
+export declare const CMS_STATUSES: readonly ["success", "partial", "failed", "blocked"];
+export declare const CMS_OPERATIONS: readonly ["cms.info", "workspace.export.bulk", "workspace.import"];
+export declare const CMS_REFERENCE_RESOLUTIONS: readonly ["included", "unresolved", "unsupported", "external"];
+export declare const MAX_DIAGNOSTICS_PER_KIND = 100;
+export declare const MAX_DIAGNOSTIC_MESSAGE_LENGTH = 1024;
+export type CmsStatus = (typeof CMS_STATUSES)[number];
+export type CmsOperation = (typeof CMS_OPERATIONS)[number];
+export type CmsReferenceResolution = (typeof CMS_REFERENCE_RESOLUTIONS)[number];
+export type CmsDiagnostic = {
+    code: string;
+    message: string;
+    scope?: string;
+    reference?: string;
+    retryable?: boolean;
+};
+export type CmsWarning = CmsDiagnostic;
+export type CmsError = CmsDiagnostic;
+export type CmsDiagnostics = {
+    warnings: CmsWarning[];
+    errors: CmsError[];
+};
+export type OpaqueCmsReference = {
+    referenceId: string;
+    owner: 'cms';
+    kind: string;
+    source: {
+        workspaceId: string;
+        sourceId: string;
+    };
+    portableKey: {
+        scheme: 'cms-opaque-v1';
+        value: string;
+    };
+    required: boolean;
+    resolution: CmsReferenceResolution;
+};
+export type CmsMetadata = {
+    operation: CmsOperation;
+    plugin: {
+        name: typeof CMS_PLUGIN_NAME;
+        version: string;
+    };
+    apiVersion: string | null;
+};
+export type CmsProvenance = {
+    producer: typeof CMS_PLUGIN_NAME;
+    sourceOrgId: string;
+    pluginVersion: string;
+    exportSetId?: string;
+    command: string;
+    generatedAt: string;
+};
+export type CmsEnvelope<T> = {
+    contract: string;
+    contractVersion: typeof CMS_CONTRACT_VERSION;
+    status: CmsStatus;
+    metadata: CmsMetadata;
+    diagnostics: CmsDiagnostics;
+    provenance: CmsProvenance;
+    result: T | null;
+};
+export type CmsEnvelopeFinalizer = {
+    emit: (envelope: CmsEnvelope<unknown>) => void;
+    setExitCode?: (exitCode: 0 | 1 | 2) => void;
+};
+export declare function assertSupportedMajor(version: unknown, label?: string): asserts version is 1;
+export declare function assertExactKeys(value: unknown, keys: readonly string[], label: string): asserts value is Record<string, unknown>;
+export declare function assertNonemptyString(value: unknown, label: string): asserts value is string;
+export declare function assertIdentifier(value: unknown, label: string): asserts value is string;
+export declare function assertReferenceId(value: unknown, label: string): asserts value is string;
+export declare function assertSha256(value: unknown, label: string): asserts value is string;
+export declare function assertRelativePosixPath(value: unknown, label: string): asserts value is string;
+export declare function sanitizeDiagnostics(diagnostics: readonly CmsDiagnostic[], label: string): CmsDiagnostic[];
+export declare function assertDiagnostics(value: unknown, label?: string): asserts value is CmsDiagnostics;
+export declare function assertOpaqueCmsReference(value: unknown, label?: string): asserts value is OpaqueCmsReference;
+export declare function assertCmsEnvelope<T>(value: unknown, resultValidator: (result: unknown, provenance?: CmsProvenance, status?: CmsStatus) => asserts result is T): asserts value is CmsEnvelope<T>;
+export declare function serializeCmsEnvelope<T>(envelope: CmsEnvelope<T>, resultValidator: (result: unknown, provenance?: CmsProvenance) => asserts result is T): string;
+export declare function finalizeCmsEnvelope<T>(envelope: CmsEnvelope<T>, resultValidator: (result: unknown, provenance?: CmsProvenance) => asserts result is T, finalizer: CmsEnvelopeFinalizer): CmsEnvelope<T>;

package/lib/contracts/shared.js

@@ -0,0 +1,218 @@
+import { redactSecrets } from '../transport/redact-secrets.js';
+export const CMS_CONTRACT_MAJOR = 1;
+export const CMS_CONTRACT_VERSION = '1.0.0';
+export const CMS_PLUGIN_NAME = 'sf-plugin-cms';
+export const CMS_STATUSES = ['success', 'partial', 'failed', 'blocked'];
+export const CMS_OPERATIONS = ['cms.info', 'workspace.export.bulk', 'workspace.import'];
+export const CMS_REFERENCE_RESOLUTIONS = [
+    'included',
+    'unresolved',
+    'unsupported',
+    'external',
+];
+export const MAX_DIAGNOSTICS_PER_KIND = 100;
+export const MAX_DIAGNOSTIC_MESSAGE_LENGTH = 1024;
+export function assertSupportedMajor(version, label = 'contractVersion') {
+    if (version !== CMS_CONTRACT_MAJOR)
+        throw new TypeError(`${label} must be supported major 1`);
+}
+export function assertExactKeys(value, keys, label) {
+    if (!isRecord(value))
+        throw new TypeError(`${label} must be an object`);
+    const actual = Object.keys(value).toSorted();
+    const expected = [...keys].toSorted();
+    if (JSON.stringify(actual) !== JSON.stringify(expected)) {
+        throw new TypeError(`${label} must contain exactly: ${expected.join(', ')}`);
+    }
+}
+export function assertNonemptyString(value, label) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new TypeError(`${label} must be a nonempty string`);
+    }
+}
+export function assertIdentifier(value, label) {
+    assertNonemptyString(value, label);
+    if (value.includes('/') ||
+        value.includes('\\') ||
+        [...value].some((character) => {
+            const codePoint = character.codePointAt(0) ?? 0;
+            return codePoint <= 31 || codePoint === 127;
+        })) {
+        throw new TypeError(`${label} is invalid`);
+    }
+}
+export function assertReferenceId(value, label) {
+    if (typeof value !== 'string' || !/^ref:[a-f\d]{64}$/u.test(value)) {
+        throw new TypeError(`${label} must be a canonical reference ID`);
+    }
+}
+export function assertSha256(value, label) {
+    if (typeof value !== 'string' || !/^[a-f\d]{64}$/u.test(value)) {
+        throw new TypeError(`${label} must be a lowercase SHA-256`);
+    }
+}
+export function assertRelativePosixPath(value, label) {
+    assertNonemptyString(value, label);
+    if (value.includes('\\') || value.startsWith('/') || /^[A-Za-z]:/u.test(value)) {
+        throw new TypeError(`${label} must be a relative POSIX path`);
+    }
+    const portable = value.startsWith('./') ? value.slice(2) : value;
+    if (portable.length === 0 ||
+        portable.split('/').some((segment) => segment === '' || segment === '.' || segment === '..')) {
+        throw new TypeError(`${label} must not contain empty or traversal segments`);
+    }
+}
+export function sanitizeDiagnostics(diagnostics, label) {
+    if (diagnostics.length > MAX_DIAGNOSTICS_PER_KIND) {
+        throw new TypeError(`${label} exceeds ${MAX_DIAGNOSTICS_PER_KIND} entries`);
+    }
+    return diagnostics.map((diagnostic, index) => {
+        assertDiagnostic(diagnostic, `${label}[${index}]`);
+        const message = redactSecrets(diagnostic.message);
+        if (message.length > MAX_DIAGNOSTIC_MESSAGE_LENGTH) {
+            throw new TypeError(`${label}[${index}].message exceeds ${MAX_DIAGNOSTIC_MESSAGE_LENGTH} characters`);
+        }
+        return { ...diagnostic, message };
+    });
+}
+export function assertDiagnostics(value, label = 'diagnostics') {
+    assertExactKeys(value, ['warnings', 'errors'], label);
+    if (!Array.isArray(value.warnings) || !Array.isArray(value.errors)) {
+        throw new TypeError(`${label} arrays are required`);
+    }
+    sanitizeDiagnostics(value.warnings, `${label}.warnings`);
+    sanitizeDiagnostics(value.errors, `${label}.errors`);
+    for (const [kind, entries] of [
+        ['warnings', value.warnings],
+        ['errors', value.errors],
+    ]) {
+        for (const [index, diagnostic] of entries.entries()) {
+            if (redactSecrets(diagnostic.message) !== diagnostic.message) {
+                throw new TypeError(`${label}.${kind}[${index}].message must already be redacted`);
+            }
+        }
+    }
+}
+export function assertOpaqueCmsReference(value, label = 'reference') {
+    assertExactKeys(value, ['referenceId', 'owner', 'kind', 'source', 'portableKey', 'required', 'resolution'], label);
+    assertReferenceId(value.referenceId, `${label}.referenceId`);
+    if (value.owner !== 'cms')
+        throw new TypeError(`${label}.owner must be cms`);
+    assertIdentifier(value.kind, `${label}.kind`);
+    assertExactKeys(value.source, ['workspaceId', 'sourceId'], `${label}.source`);
+    assertIdentifier(value.source.workspaceId, `${label}.source.workspaceId`);
+    assertIdentifier(value.source.sourceId, `${label}.source.sourceId`);
+    assertExactKeys(value.portableKey, ['scheme', 'value'], `${label}.portableKey`);
+    if (value.portableKey.scheme !== 'cms-opaque-v1') {
+        throw new TypeError(`${label}.portableKey.scheme is unsupported`);
+    }
+    assertNonemptyString(value.portableKey.value, `${label}.portableKey.value`);
+    if (typeof value.required !== 'boolean')
+        throw new TypeError(`${label}.required must be boolean`);
+    if (!CMS_REFERENCE_RESOLUTIONS.includes(value.resolution)) {
+        throw new TypeError(`${label}.resolution is unsupported`);
+    }
+}
+export function assertCmsEnvelope(value, resultValidator) {
+    assertExactKeys(value, ['contract', 'contractVersion', 'status', 'metadata', 'diagnostics', 'provenance', 'result'], 'envelope');
+    assertNonemptyString(value.contract, 'envelope.contract');
+    if (value.contractVersion !== CMS_CONTRACT_VERSION) {
+        throw new TypeError('envelope.contractVersion must be 1.0.0');
+    }
+    if (!CMS_STATUSES.includes(value.status))
+        throw new TypeError('envelope.status is invalid');
+    assertMetadata(value.metadata);
+    const expectedContract = new Map([
+        ['cms.info', 'sf-cms-info'],
+        ['workspace.export.bulk', 'sf-cms-workspace-export-set'],
+        ['workspace.import', 'sf-cms-workspace-import'],
+    ]);
+    if (value.contract !== expectedContract.get(value.metadata.operation)) {
+        throw new TypeError('envelope.contract does not match metadata.operation');
+    }
+    assertDiagnostics(value.diagnostics);
+    assertProvenance(value.provenance);
+    if (value.provenance.pluginVersion !== value.metadata.plugin.version) {
+        throw new TypeError('envelope provenance pluginVersion must match metadata.plugin.version');
+    }
+    if (value.result === null) {
+        if (value.status !== 'failed' && value.status !== 'blocked') {
+            throw new TypeError('envelope.result may be null only for failed or blocked status');
+        }
+    }
+    else {
+        resultValidator(value.result, value.provenance, value.status);
+    }
+}
+export function serializeCmsEnvelope(envelope, resultValidator) {
+    assertCmsEnvelope(envelope, resultValidator);
+    return `${JSON.stringify(envelope, null, 2)}\n`;
+}
+export function finalizeCmsEnvelope(envelope, resultValidator, finalizer) {
+    assertCmsEnvelope(envelope, resultValidator);
+    finalizer.emit(envelope);
+    finalizer.setExitCode?.(exitCodeForStatus(envelope.status));
+    return envelope;
+}
+function exitCodeForStatus(status) {
+    if (status === 'success')
+        return 0;
+    if (status === 'partial')
+        return 2;
+    return 1;
+}
+function assertDiagnostic(value, label) {
+    if (!isRecord(value))
+        throw new TypeError(`${label} must be an object`);
+    const allowed = new Set(['code', 'message', 'scope', 'reference', 'retryable']);
+    if (Object.keys(value).some((key) => !allowed.has(key))) {
+        throw new TypeError(`${label} contains an unknown key`);
+    }
+    assertNonemptyString(value.code, `${label}.code`);
+    assertNonemptyString(value.message, `${label}.message`);
+    for (const key of ['scope', 'reference']) {
+        if (value[key] !== undefined)
+            assertNonemptyString(value[key], `${label}.${key}`);
+    }
+    if (value.retryable !== undefined && typeof value.retryable !== 'boolean') {
+        throw new TypeError(`${label}.retryable must be boolean`);
+    }
+}
+function assertMetadata(value) {
+    assertExactKeys(value, ['operation', 'plugin', 'apiVersion'], 'envelope.metadata');
+    if (!CMS_OPERATIONS.includes(value.operation)) {
+        throw new TypeError('envelope.metadata.operation is invalid');
+    }
+    assertExactKeys(value.plugin, ['name', 'version'], 'envelope.metadata.plugin');
+    if (value.plugin.name !== CMS_PLUGIN_NAME)
+        throw new TypeError('envelope.metadata.plugin.name is invalid');
+    assertNonemptyString(value.plugin.version, 'envelope.metadata.plugin.version');
+    if (value.apiVersion !== null)
+        assertNonemptyString(value.apiVersion, 'envelope.metadata.apiVersion');
+}
+function assertProvenance(value) {
+    if (!isRecord(value))
+        throw new TypeError('envelope.provenance must be an object');
+    const required = ['producer', 'sourceOrgId', 'pluginVersion', 'command', 'generatedAt'];
+    const allowed = new Set([...required, 'exportSetId']);
+    if (required.some((key) => !(key in value)) ||
+        Object.keys(value).some((key) => !allowed.has(key))) {
+        throw new TypeError('envelope.provenance has invalid keys');
+    }
+    if (value.producer !== CMS_PLUGIN_NAME)
+        throw new TypeError('envelope.provenance.producer is invalid');
+    assertIdentifier(value.sourceOrgId, 'envelope.provenance.sourceOrgId');
+    assertNonemptyString(value.pluginVersion, 'envelope.provenance.pluginVersion');
+    assertNonemptyString(value.command, 'envelope.provenance.command');
+    assertNonemptyString(value.generatedAt, 'envelope.provenance.generatedAt');
+    if (Number.isNaN(Date.parse(value.generatedAt)))
+        throw new TypeError('envelope.provenance.generatedAt is invalid');
+    if (value.exportSetId !== undefined &&
+        !/^export-set:[a-f\d]{64}$/u.test(value.exportSetId)) {
+        throw new TypeError('envelope.provenance.exportSetId is invalid');
+    }
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=shared.js.map

package/lib/contracts/shared.js.map

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

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

@@ -0,0 +1,91 @@
+import { type CmsDiagnostics, type CmsProvenance, type OpaqueCmsReference } from './shared.js';
+export declare const WORKSPACE_EXPORT_SET_CONTRACT: "sf-cms-workspace-export-set";
+export declare const WORKSPACE_EXPORT_MANIFEST_CONTRACT: "sf-cms-workspace-export";
+export declare const EXTERNAL_REFERENCE_CORRELATIONS_CONTRACT: "sf-cms-external-reference-correlations@1";
+export type WorkspaceExportManifestItem = {
+    path: string;
+    sha256: string;
+    kind: string;
+    referenceId?: 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: Array<{
+        file: string;
+        variantId: string;
+    }>;
+    rejectedVariantIds: string[];
+    failedVariantIds: string[];
+    warnings: Array<{
+        code: 'COUNT_MISMATCH' | 'DETAIL_FAILED' | 'DUPLICATE_VARIANTS' | 'OWNERSHIP_MISMATCH' | 'PREMATURE_EMPTY_PAGE' | 'REFERENCE_UNRESOLVED' | 'REFERENCE_UNSUPPORTED' | 'UNSUPPORTED_WILDCARD';
+        message: string;
+        variantIds?: string[];
+    }>;
+    contract: typeof WORKSPACE_EXPORT_MANIFEST_CONTRACT;
+    contractVersion: '1.0.0';
+    provenance: {
+        producer: 'sf-plugin-cms';
+        sourceOrgId: string;
+        sourceWorkspaceId: string;
+        pluginVersion: string;
+        generatedAt: string;
+    };
+    completeness: 'complete' | 'partial';
+    dependencies: string[];
+    externalReferences: OpaqueCmsReference[];
+    items: WorkspaceExportManifestItem[];
+};
+export type ExternalReferenceCorrelation = {
+    sourceWorkspaceId: string;
+    sourceReference: string;
+    referenceKind: string;
+    referenceId: string;
+    packageManifestSha256: string;
+};
+export type WorkspaceExportSetEntry = {
+    source: {
+        kind: 'cms.workspace';
+        sourceId: string;
+        name: string;
+        workspaceType: 'Marketing' | 'Content';
+    };
+    status: 'success' | 'partial' | 'failed';
+    artifact: {
+        path: string;
+        manifestPath: string;
+        manifestContract: typeof WORKSPACE_EXPORT_MANIFEST_CONTRACT;
+        manifestContractVersion: '1.0.0';
+        manifestSha256: string;
+    } | null;
+    diagnostics: CmsDiagnostics;
+};
+export type WorkspaceExportSetResult = {
+    workspaceType: 'Marketing' | 'Content';
+    outputDirectory: string;
+    selection: {
+        mode: 'all';
+        discoveredCount: number;
+        selectedCount: number;
+    };
+    summary: {
+        succeededCount: number;
+        partialCount: number;
+        failedCount: number;
+    };
+    externalReferenceCorrelations: ExternalReferenceCorrelation[];
+    workspaces: WorkspaceExportSetEntry[];
+};
+export declare function assertWorkspaceExportManifest(value: unknown): asserts value is WorkspaceExportManifest;
+export declare function assertWorkspaceExportSetResult(value: unknown, provenance?: CmsProvenance, status?: 'success' | 'partial' | 'failed' | 'blocked'): asserts value is WorkspaceExportSetResult;