@revoengine/cli 1.0.10 → 1.0.11

package/dist/src/resource-syncs/endpoint-sync.js

@@ -0,0 +1,1283 @@
+import path from 'node:path';
+import { hashPortableComponentSource, hashStable, readComponentLock, writeComponentLock } from "../component-lock.js";
+import { readConfiguredResourceMetadataStableKey, sanitizeUserMetadata } from "../resource-metadata.js";
+import { readJsonFile, sanitizeSegment } from "../utils.js";
+import { hydrateWorkspaceComponentElementDetails } from "../workspace-component.js";
+import { findManifestFiles, isRecord, localTargetPath, requireProjectLayout, stableKeySuffix, toPortableRelativePath, unwrapData, writePulledManifest, } from "./util.js";
+export const ENDPOINTS_DIRECTORY = 'Endpoints';
+export const ENDPOINT_MANIFEST_FILE = 'endpoint.json';
+const ENDPOINT_DEFAULT_TIMEOUT_SECONDS = 60;
+const ENDPOINT_DEFAULT_MEMORY_MB = 32;
+const ENDPOINT_PLAN_STATUS_ORDER = [
+    'create', 'restore', 'safe-update', 'remote-changed', 'conflict', 'missing-lock',
+    'restore-blocked', 'collision', 'clean', 'orphan', 'skipped',
+];
+function canonicalValue(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => canonicalValue(item));
+    }
+    if (!isRecord(value)) {
+        return value;
+    }
+    return Object.fromEntries(Object.keys(value).sort((left, right) => left.localeCompare(right))
+        .map((key) => [key, canonicalValue(value[key])]));
+}
+function endpointIdOf(record) {
+    return String(record.endpointId || record.id || '');
+}
+function componentIdOf(record) {
+    return String(record.componentId || record.id || '');
+}
+function canonicalMetadata(record, stableKeyName, stableKey) {
+    return canonicalValue({
+        ...sanitizeUserMetadata(record.resourceMetadata),
+        ...sanitizeUserMetadata(record.metaData),
+        ...sanitizeUserMetadata(record.metadata),
+        [stableKeyName]: stableKey,
+    });
+}
+function rawConfiguredStableKey(record, stableKeyName) {
+    for (const metadata of [record.metadata, record.metaData, record.resourceMetadata]) {
+        if (isRecord(metadata) && Object.hasOwn(metadata, stableKeyName)) {
+            return { present: true, value: metadata[stableKeyName] };
+        }
+    }
+    return { present: false, value: undefined };
+}
+function canonicalRoute(record) {
+    const method = typeof record.method === 'string' ? record.method.trim().toUpperCase() : '';
+    const rawPath = typeof record.path === 'string' ? record.path.trim() : '';
+    const pathValue = rawPath.replace(/\/{2,}/g, '/').replace(/\/+$/g, '') || '/';
+    if (!method || !rawPath) {
+        throw new Error(`Endpoint "${String(record.name || endpointIdOf(record) || 'unknown')}" has no complete route.`);
+    }
+    return { method, path: pathValue };
+}
+function portableOptions(record) {
+    if (record.options === undefined || record.options === null) {
+        return undefined;
+    }
+    if (!isRecord(record.options)) {
+        throw new Error(`Endpoint "${String(record.name || endpointIdOf(record) || 'unknown')}" has invalid options.`);
+    }
+    const options = { ...record.options };
+    delete options.componentSchemaId;
+    delete options.componentSchemaVersion;
+    delete options.componentSchemaElement;
+    return Object.keys(options).length > 0 ? canonicalValue(options) : undefined;
+}
+function canonicalPortableOptions(options) {
+    if (options === undefined) {
+        return undefined;
+    }
+    return canonicalValue({
+        ...options,
+        ...(options.memory === null ? { memory: ENDPOINT_DEFAULT_MEMORY_MB } : {}),
+    });
+}
+function endpointLabel(record, fallback = 'remote-id') {
+    const category = typeof record.category === 'string' && record.category.trim()
+        ? record.category.trim()
+        : 'Uncategorized';
+    const name = typeof record.name === 'string' && record.name.trim()
+        ? record.name.trim()
+        : fallback === 'remote-id'
+            ? endpointIdOf(record) || 'unknown'
+            : 'unknown';
+    return `${category}/${name}`;
+}
+function endpointManifestPath(workspaceRoot, manifest) {
+    const category = typeof manifest.category === 'string' && manifest.category.trim()
+        ? sanitizeSegment(manifest.category)
+        : 'Uncategorized';
+    return path.join(workspaceRoot, ENDPOINTS_DIRECTORY, category, `${sanitizeSegment(manifest.name)}-${stableKeySuffix(manifest.stableKey)}`, ENDPOINT_MANIFEST_FILE);
+}
+function portablePathIdentity(filePath) {
+    return path.resolve(filePath)
+        .normalize('NFC')
+        .split(path.sep)
+        .map((segment) => segment.replace(/[. ]+$/g, '').toLowerCase())
+        .join(path.sep);
+}
+function disambiguateManifestPath(filePath, stableKey) {
+    const directory = path.dirname(filePath);
+    return path.join(path.dirname(directory), `${path.basename(directory)}-${hashStable(stableKey).slice(0, 8)}`, path.basename(filePath));
+}
+const ENDPOINT_MANIFEST_FIELDS = new Set([
+    'kind', 'stableKey', 'name', 'category', 'description', 'metadata', 'active', 'timeout',
+    'route', 'options', 'execution', 'schema',
+]);
+const INSTANCE_LOCAL_SCHEMA_OPTION_FIELDS = new Set([
+    'componentSchemaId', 'componentSchemaVersion', 'componentSchemaElement',
+]);
+function hasOnlyKeys(value, allowed) {
+    return Object.keys(value).every((key) => allowed.has(key));
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function hasValidBinding(value) {
+    if (!isRecord(value) || !hasOnlyKeys(value, new Set(['stableKey', 'binding', 'pinnedDigest']))) {
+        return false;
+    }
+    if (!isNonEmptyString(value.stableKey) || (value.binding !== 'latest' && value.binding !== 'pinned')) {
+        return false;
+    }
+    if (value.binding === 'latest') {
+        return value.pinnedDigest === undefined;
+    }
+    return typeof value.pinnedDigest === 'string' && /^[0-9a-f]{64}$/i.test(value.pinnedDigest);
+}
+function hasValidSchemaBinding(value) {
+    if (!isRecord(value) || !hasOnlyKeys(value, new Set(['stableKey', 'binding', 'pinnedDigest', 'element']))) {
+        return false;
+    }
+    const { element, ...binding } = value;
+    return hasValidBinding(binding) && (element === undefined || isNonEmptyString(element));
+}
+function validateManifest(manifest, stableKeyName) {
+    if (!isRecord(manifest) || !hasOnlyKeys(manifest, ENDPOINT_MANIFEST_FIELDS)) {
+        return false;
+    }
+    if (manifest.kind !== 'endpoint' || !isNonEmptyString(manifest.stableKey) || !isNonEmptyString(manifest.name)) {
+        return false;
+    }
+    if (!isRecord(manifest.metadata) || typeof manifest.active !== 'boolean') {
+        return false;
+    }
+    if (manifest.category !== undefined && manifest.category !== null && typeof manifest.category !== 'string') {
+        return false;
+    }
+    if (manifest.description !== undefined && typeof manifest.description !== 'string') {
+        return false;
+    }
+    if (manifest.timeout !== undefined && (typeof manifest.timeout !== 'number' || !Number.isFinite(manifest.timeout))) {
+        return false;
+    }
+    if (!isRecord(manifest.route) || !hasOnlyKeys(manifest.route, new Set(['method', 'path']))
+        || !isNonEmptyString(manifest.route.method) || !isNonEmptyString(manifest.route.path)) {
+        return false;
+    }
+    if (manifest.options !== undefined && !isRecord(manifest.options)) {
+        return false;
+    }
+    if (isRecord(manifest.options)
+        && Object.keys(manifest.options).some((key) => INSTANCE_LOCAL_SCHEMA_OPTION_FIELDS.has(key))) {
+        return false;
+    }
+    if (manifest.execution !== undefined && !hasValidBinding(manifest.execution)) {
+        return false;
+    }
+    if (manifest.schema !== undefined && !hasValidSchemaBinding(manifest.schema)) {
+        return false;
+    }
+    return readConfiguredResourceMetadataStableKey(manifest, stableKeyName) === manifest.stableKey;
+}
+export function hashPortableEndpoint(manifest) {
+    return hashStable({
+        kind: manifest.kind,
+        stableKey: manifest.stableKey,
+        name: manifest.name,
+        category: manifest.category ?? null,
+        description: manifest.description ?? '',
+        metadata: canonicalValue(manifest.metadata),
+        active: manifest.active,
+        timeout: manifest.timeout ?? ENDPOINT_DEFAULT_TIMEOUT_SECONDS,
+        route: canonicalValue(manifest.route),
+        ...(manifest.options === undefined ? {} : { options: canonicalPortableOptions(manifest.options) }),
+        ...(manifest.execution === undefined ? {} : { execution: canonicalValue(manifest.execution) }),
+        ...(manifest.schema === undefined ? {} : { schema: canonicalValue(manifest.schema) }),
+    });
+}
+function readWorkspaceEndpoints(cwd) {
+    const { workspaceRoot } = requireProjectLayout(cwd, 'Endpoint');
+    return findManifestFiles(path.join(workspaceRoot, ENDPOINTS_DIRECTORY), ENDPOINT_MANIFEST_FILE).map((manifestPath) => ({
+        manifestPath,
+        manifest: readJsonFile(manifestPath),
+    }));
+}
+function readWorkspaceComponents(cwd, stableKeyName) {
+    const { workspaceRoot } = requireProjectLayout(cwd, 'Endpoint');
+    const result = new Map();
+    for (const manifestPath of findManifestFiles(path.join(workspaceRoot, 'Components'), 'component.json')) {
+        const component = hydrateWorkspaceComponentElementDetails(manifestPath, readJsonFile(manifestPath));
+        const stableKey = readConfiguredResourceMetadataStableKey(component, stableKeyName);
+        if (stableKey) {
+            result.set(stableKey, [...(result.get(stableKey) || []), component]);
+        }
+    }
+    return result;
+}
+async function loadRemoteEndpoints(client) {
+    const { endpoints } = await client.listAllEndpoints();
+    return Promise.all(endpoints.map(async (summary) => {
+        const endpointId = endpointIdOf(summary);
+        if (!endpointId) {
+            return summary;
+        }
+        return unwrapData(await client.getEndpoint(endpointId));
+    }));
+}
+async function loadRemoteComponents(client) {
+    const { components } = await client.listAllComponents();
+    return Promise.all(components.map(async (summary) => {
+        const componentId = componentIdOf(summary);
+        if (!componentId) {
+            return summary;
+        }
+        return unwrapData(await client.getComponent(componentId));
+    }));
+}
+async function componentBinding(input) {
+    const component = input.componentsById.get(input.componentId);
+    if (!component) {
+        throw new Error(`Endpoint "${input.endpointStableKey}" ${input.relation} component is missing from the source.`);
+    }
+    const stableKey = readConfiguredResourceMetadataStableKey(component, input.stableKeyName);
+    if (!stableKey) {
+        throw new Error(`Endpoint "${input.endpointStableKey}" ${input.relation} component is unmanaged: missing ${input.stableKeyName}.`);
+    }
+    if (typeof input.componentVersion !== 'number') {
+        return { stableKey, binding: 'latest' };
+    }
+    const snapshot = unwrapData(await input.client.getComponentSnapshotVersion(input.componentId, input.componentVersion));
+    return { stableKey, binding: 'pinned', pinnedDigest: hashPortableComponentSource(snapshot) };
+}
+async function manifestFromRecord(input) {
+    const { record } = input;
+    if (typeof record.name !== 'string' || !record.name.trim()) {
+        throw new Error(`Endpoint "${input.stableKey}" has no name.`);
+    }
+    if (record.category !== undefined && record.category !== null && typeof record.category !== 'string') {
+        throw new Error(`Endpoint "${input.stableKey}" has an invalid category.`);
+    }
+    if (record.active !== undefined && typeof record.active !== 'boolean') {
+        throw new Error(`Endpoint "${input.stableKey}" has an invalid active value.`);
+    }
+    if (record.timeout !== undefined && (typeof record.timeout !== 'number' || !Number.isFinite(record.timeout))) {
+        throw new Error(`Endpoint "${input.stableKey}" has an invalid timeout.`);
+    }
+    const executionComponentId = typeof record.componentId === 'string' ? record.componentId : '';
+    const execution = executionComponentId
+        ? await componentBinding({
+            client: input.client,
+            componentsById: input.componentsById,
+            componentId: executionComponentId,
+            componentVersion: record.componentVersion,
+            stableKeyName: input.stableKeyName,
+            endpointStableKey: input.stableKey,
+            relation: 'execution',
+        })
+        : undefined;
+    const schemaComponentId = isRecord(record.options) && typeof record.options.componentSchemaId === 'string'
+        ? record.options.componentSchemaId
+        : '';
+    const schemaElement = isRecord(record.options) && typeof record.options.componentSchemaElement === 'string'
+        ? record.options.componentSchemaElement.trim()
+        : '';
+    const schema = schemaComponentId
+        ? {
+            ...await componentBinding({
+                client: input.client,
+                componentsById: input.componentsById,
+                componentId: schemaComponentId,
+                componentVersion: record.options?.componentSchemaVersion,
+                stableKeyName: input.stableKeyName,
+                endpointStableKey: input.stableKey,
+                relation: 'schema',
+            }),
+            ...(schemaElement ? { element: schemaElement } : {}),
+        }
+        : undefined;
+    const options = portableOptions(record);
+    const manifest = {
+        kind: 'endpoint',
+        stableKey: input.stableKey,
+        name: String(record.name || ''),
+        ...(record.category === undefined ? {} : { category: record.category }),
+        ...(typeof record.desc === 'string' ? { description: record.desc } : typeof record.description === 'string' ? { description: record.description } : {}),
+        metadata: canonicalMetadata(record, input.stableKeyName, input.stableKey),
+        active: record.active !== false,
+        timeout: typeof record.timeout === 'number' ? record.timeout : ENDPOINT_DEFAULT_TIMEOUT_SECONDS,
+        route: canonicalRoute(record),
+        ...(options === undefined ? {} : { options }),
+        ...(execution ? { execution } : {}),
+        ...(schema ? { schema } : {}),
+    };
+    if (!validateManifest(manifest, input.stableKeyName)) {
+        throw new Error(`Endpoint "${input.stableKey}" has invalid portable state.`);
+    }
+    return manifest;
+}
+export async function pullEndpointsToWorkspace(input) {
+    const { projectRoot, workspaceRoot } = requireProjectLayout(input.cwd, 'Endpoint');
+    const [records, components] = await Promise.all([
+        loadRemoteEndpoints(input.client),
+        loadRemoteComponents(input.client),
+    ]);
+    const componentsById = new Map(components.map((component) => [componentIdOf(component), component]));
+    const manifests = [];
+    const skipped = [];
+    const stableKeys = new Set();
+    for (const record of records) {
+        if (record.deletedAt || record.deletedBy) {
+            skipped.push({ targetPath: endpointLabel(record), reason: 'deleted endpoint is excluded' });
+            continue;
+        }
+        const rawStableKey = rawConfiguredStableKey(record, input.stableKeyName);
+        if (rawStableKey.present && !isNonEmptyString(rawStableKey.value)) {
+            throw new Error(`Invalid endpoint stableKey on ${endpointIdOf(record) || endpointLabel(record)}; no files were changed.`);
+        }
+        const stableKey = readConfiguredResourceMetadataStableKey(record, input.stableKeyName);
+        if (!stableKey) {
+            skipped.push({ targetPath: endpointLabel(record), reason: `unmanaged: missing ${input.stableKeyName}` });
+            continue;
+        }
+        if (stableKeys.has(stableKey)) {
+            throw new Error(`Duplicate endpoint stableKey "${stableKey}" on ${input.envName}; no files were changed.`);
+        }
+        stableKeys.add(stableKey);
+        manifests.push(await manifestFromRecord({
+            client: input.client,
+            record,
+            stableKey,
+            stableKeyName: input.stableKeyName,
+            componentsById,
+        }));
+    }
+    manifests.sort((left, right) => left.stableKey.localeCompare(right.stableKey));
+    skipped.sort((left, right) => left.targetPath.localeCompare(right.targetPath));
+    const lock = readComponentLock(projectRoot);
+    const existingByKey = new Map();
+    const existingByPath = new Map();
+    for (const entry of readWorkspaceEndpoints(input.cwd)) {
+        if (!validateManifest(entry.manifest, input.stableKeyName)) {
+            throw new Error(`Cannot pull over invalid endpoint manifest ${path.relative(projectRoot, entry.manifestPath)}.`);
+        }
+        if (existingByKey.has(entry.manifest.stableKey)) {
+            throw new Error(`Duplicate local endpoint stableKey "${entry.manifest.stableKey}"; no files were changed.`);
+        }
+        existingByKey.set(entry.manifest.stableKey, entry);
+        const identity = portablePathIdentity(entry.manifestPath);
+        existingByPath.set(identity, [...(existingByPath.get(identity) || []), entry]);
+    }
+    const writes = manifests.map((manifest) => {
+        const hash = hashPortableEndpoint(manifest);
+        const existing = existingByKey.get(manifest.stableKey);
+        if (existing && !input.force) {
+            const localHash = hashPortableEndpoint(existing.manifest);
+            const baseline = lock.endpoints[manifest.stableKey];
+            if (localHash !== hash && (!baseline || localHash !== baseline.sourceHash)) {
+                throw new Error(`Cannot pull endpoint "${manifest.stableKey}": local manifest changed since the lock baseline. Re-run with --force.`);
+            }
+        }
+        return {
+            manifest,
+            hash,
+            filePath: endpointManifestPath(workspaceRoot, manifest),
+            ...(existing ? { previousPath: existing.manifestPath } : {}),
+        };
+    });
+    const candidatePathCounts = new Map();
+    for (const write of writes) {
+        const identity = portablePathIdentity(write.filePath);
+        candidatePathCounts.set(identity, (candidatePathCounts.get(identity) || 0) + 1);
+    }
+    for (const write of writes) {
+        if ((candidatePathCounts.get(portablePathIdentity(write.filePath)) || 0) > 1) {
+            write.filePath = disambiguateManifestPath(write.filePath, write.manifest.stableKey);
+        }
+    }
+    const paths = new Set();
+    for (const write of writes) {
+        const identity = portablePathIdentity(write.filePath);
+        if (paths.has(identity)) {
+            throw new Error('Multiple endpoints resolve to the same workspace path; no files were changed.');
+        }
+        paths.add(identity);
+        const pathOwner = (existingByPath.get(identity) || [])
+            .find((entry) => entry.manifest.stableKey !== write.manifest.stableKey);
+        if (pathOwner) {
+            throw new Error(`Endpoint workspace path "${path.relative(projectRoot, write.filePath)}" is occupied by different stableKey "${pathOwner.manifest.stableKey}"; no files were changed.`);
+        }
+    }
+    const root = path.join(workspaceRoot, ENDPOINTS_DIRECTORY);
+    let lockChanged = false;
+    for (const write of writes) {
+        writePulledManifest({
+            filePath: write.filePath,
+            manifest: write.manifest,
+            previousPath: write.previousPath,
+            root: root,
+            force: input.force,
+        });
+        const previous = lock.endpoints[write.manifest.stableKey];
+        const previousBaseline = previous?.environments[input.envName];
+        const entry = {
+            stableKey: write.manifest.stableKey,
+            path: toPortableRelativePath(projectRoot, write.filePath),
+            sourceHash: write.hash,
+            environments: {
+                ...(previous?.environments || {}),
+                [input.envName]: previousBaseline?.remoteHash === write.hash
+                    ? previousBaseline
+                    : { remoteHash: write.hash, syncedAt: new Date().toISOString() },
+            },
+        };
+        if (!previous || hashStable(previous) !== hashStable(entry)) {
+            lockChanged = true;
+        }
+        lock.endpoints[write.manifest.stableKey] = entry;
+    }
+    if (lockChanged) {
+        writeComponentLock(projectRoot, lock);
+    }
+    return {
+        pulled: writes.map((write) => ({
+            manifest: write.manifest,
+            targetPath: localTargetPath(input.cwd, write.filePath),
+        })),
+        skipped,
+    };
+}
+function endpointPlanCounts() {
+    return Object.fromEntries(ENDPOINT_PLAN_STATUS_ORDER.map((status) => [status, 0]));
+}
+function endpointRouteKey(route) {
+    const method = route.method.trim().toUpperCase();
+    const rawPath = route.path.trim();
+    const pathValue = rawPath.replace(/\/{2,}/g, '/').replace(/\/+$/g, '') || '/';
+    return `${method} ${pathValue}`;
+}
+function endpointRecordRouteKey(record) {
+    try {
+        return endpointRouteKey(canonicalRoute(record));
+    }
+    catch {
+        return '';
+    }
+}
+function diffEndpoints(desired, current) {
+    const fields = [
+        ['name', desired.name, current.name],
+        ['category', desired.category ?? null, current.category ?? null],
+        ['description', desired.description ?? '', current.description ?? ''],
+        ['metadata', canonicalValue(desired.metadata), canonicalValue(current.metadata)],
+        ['active', desired.active, current.active],
+        ['timeout', desired.timeout ?? ENDPOINT_DEFAULT_TIMEOUT_SECONDS, current.timeout ?? ENDPOINT_DEFAULT_TIMEOUT_SECONDS],
+        ['route.method', desired.route.method, current.route.method],
+        ['route.path', desired.route.path, current.route.path],
+        ['options', canonicalPortableOptions(desired.options) ?? null, canonicalPortableOptions(current.options) ?? null],
+        ['execution', canonicalValue(desired.execution ?? null), canonicalValue(current.execution ?? null)],
+        ['schema', canonicalValue(desired.schema ?? null), canonicalValue(current.schema ?? null)],
+    ];
+    return fields
+        .filter(([, desiredValue, currentValue]) => hashStable(desiredValue) !== hashStable(currentValue))
+        .map(([field]) => field)
+        .sort((left, right) => left.localeCompare(right));
+}
+function componentType(component) {
+    return String(component.type || '').trim().toUpperCase();
+}
+function hasComponentElement(component, elementKey) {
+    return (component.elements || []).some((element) => element.key === elementKey);
+}
+function componentDependencyDiagnostics(input) {
+    const blockers = [];
+    const details = [];
+    const bindings = [
+        ...(input.endpoint.execution ? [{ relation: 'execution', binding: input.endpoint.execution }] : []),
+        ...(input.endpoint.schema ? [{ relation: 'schema', binding: input.endpoint.schema }] : []),
+    ];
+    for (const { relation, binding } of bindings) {
+        const workspaceMatches = input.workspaceComponents.get(binding.stableKey) || [];
+        const targetMatches = input.targetComponents.get(binding.stableKey) || [];
+        if (workspaceMatches.length !== 1 || targetMatches.length !== 1) {
+            const location = workspaceMatches.length !== 1 ? 'source' : 'target';
+            const count = location === 'source' ? workspaceMatches.length : targetMatches.length;
+            blockers.push(`Endpoint "${input.endpoint.stableKey}" ${relation} Component "${binding.stableKey}" is ${count === 0 ? 'missing' : 'ambiguous'} in ${location}; align Components before Endpoints.`);
+            continue;
+        }
+        const workspace = workspaceMatches[0];
+        const target = targetMatches[0];
+        const workspaceDigest = hashPortableComponentSource(workspace);
+        const targetDigest = hashPortableComponentSource(target);
+        if (binding.binding === 'pinned') {
+            details.push({ label: `${relation} A (pinned)`, values: binding.pinnedDigest || '' });
+        }
+        details.push({ label: `${relation} B (source)`, values: workspaceDigest }, { label: `${relation} C (target)`, values: targetDigest });
+        if (relation === 'execution') {
+            const allowed = new Set(['CODE_JS', 'CODE_TS']);
+            if (!allowed.has(componentType(workspace)) || !allowed.has(componentType(target))) {
+                blockers.push(`Endpoint "${input.endpoint.stableKey}" execution Component "${binding.stableKey}" must be CODE_JS or CODE_TS in source and target.`);
+            }
+        }
+        else {
+            if (componentType(workspace) !== 'JSON_VALIDATOR' || componentType(target) !== 'JSON_VALIDATOR') {
+                blockers.push(`Endpoint "${input.endpoint.stableKey}" schema Component "${binding.stableKey}" must be JSON_VALIDATOR in source and target.`);
+            }
+            const schema = binding;
+            if (schema.element
+                && (!hasComponentElement(workspace, schema.element) || !hasComponentElement(target, schema.element))) {
+                blockers.push(`Endpoint "${input.endpoint.stableKey}" schema element "${schema.element}" is missing from Component "${binding.stableKey}" in source or target.`);
+            }
+            else if (!schema.element && ((workspace.elements || []).length === 0 || (target.elements || []).length === 0)) {
+                blockers.push(`Endpoint "${input.endpoint.stableKey}" schema Component "${binding.stableKey}" has no default first element in source or target.`);
+            }
+        }
+        const digestMatches = binding.binding === 'latest'
+            ? workspaceDigest === targetDigest
+            : binding.pinnedDigest === workspaceDigest && workspaceDigest === targetDigest;
+        if (!digestMatches) {
+            blockers.push(`Endpoint "${input.endpoint.stableKey}" ${relation} Component "${binding.stableKey}" portable content does not match (${binding.binding}); align Components before Endpoints.`);
+        }
+    }
+    return { blockers, details };
+}
+function targetComponentsByStableKey(components, stableKeyName) {
+    const result = new Map();
+    for (const component of components) {
+        const stableKey = readConfiguredResourceMetadataStableKey(component, stableKeyName);
+        if (stableKey) {
+            result.set(stableKey, [...(result.get(stableKey) || []), component]);
+        }
+    }
+    return result;
+}
+function endpointRevisionHash(record) {
+    return hashStable({
+        stableKeyMetadata: canonicalValue(record.metadata ?? record.metaData ?? record.resourceMetadata ?? null),
+        name: record.name ?? null,
+        category: record.category ?? null,
+        desc: record.desc ?? record.description ?? null,
+        active: record.active ?? null,
+        timeout: record.timeout ?? null,
+        path: record.path ?? null,
+        method: record.method ?? null,
+        componentId: record.componentId ?? null,
+        componentVersion: record.componentVersion ?? null,
+        options: canonicalValue(record.options ?? null),
+        version: record.version ?? null,
+        deletedAt: record.deletedAt ?? null,
+        deletedBy: record.deletedBy ?? null,
+    });
+}
+async function activeDeletedEndpointRestoreBlockers(input) {
+    if (!input.record.active) {
+        return [];
+    }
+    const blockers = [];
+    const loadBinding = async (componentId, version, relation) => {
+        const current = input.componentsById.get(componentId);
+        if (!current) {
+            blockers.push(`old ${relation} Component "${componentId}" is missing`);
+            return undefined;
+        }
+        if (current.active !== true) {
+            blockers.push(`old ${relation} Component "${componentId}" is inactive`);
+            return undefined;
+        }
+        try {
+            const component = typeof version === 'number'
+                ? unwrapData(await input.client.getComponentSnapshotVersion(componentId, version))
+                : current;
+            if (!component) {
+                blockers.push(`old ${relation} Component "${componentId}" is missing`);
+            }
+            return component;
+        }
+        catch {
+            blockers.push(`old ${relation} Component "${componentId}" version ${String(version)} is missing`);
+            return undefined;
+        }
+    };
+    if (typeof input.record.componentId === 'string' && input.record.componentId) {
+        const execution = await loadBinding(input.record.componentId, input.record.componentVersion, 'execution');
+        if (execution && !new Set(['CODE_JS', 'CODE_TS']).has(componentType(execution))) {
+            blockers.push(`old execution Component "${input.record.componentId}" is not executable`);
+        }
+    }
+    const options = isRecord(input.record.options) ? input.record.options : {};
+    const schemaId = typeof options.componentSchemaId === 'string' ? options.componentSchemaId : '';
+    if (schemaId) {
+        const schema = await loadBinding(schemaId, options.componentSchemaVersion, 'schema');
+        if (schema && componentType(schema) !== 'JSON_VALIDATOR') {
+            blockers.push(`old schema Component "${schemaId}" is not JSON_VALIDATOR`);
+        }
+        const element = typeof options.componentSchemaElement === 'string'
+            ? options.componentSchemaElement.trim()
+            : '';
+        if (schema && element && !hasComponentElement(schema, element)) {
+            blockers.push(`old schema Component "${schemaId}" element "${element}" is missing`);
+        }
+        if (schema && !element && (schema.elements || []).length === 0) {
+            blockers.push(`old schema Component "${schemaId}" has no default first element`);
+        }
+    }
+    return blockers;
+}
+export async function buildEndpointsPlan(input) {
+    const { projectRoot } = requireProjectLayout(input.cwd, 'Endpoint');
+    const items = [];
+    const blockers = [];
+    const exclusions = [];
+    const localByStableKey = new Map();
+    for (const entry of readWorkspaceEndpoints(input.cwd)) {
+        if (!validateManifest(entry.manifest, input.stableKeyName)) {
+            const relativePath = path.relative(projectRoot, entry.manifestPath);
+            blockers.push(`Invalid Endpoint manifest "${relativePath}".`);
+            items.push({ status: 'conflict', name: relativePath, reason: 'invalid portable manifest' });
+            continue;
+        }
+        localByStableKey.set(entry.manifest.stableKey, [
+            ...(localByStableKey.get(entry.manifest.stableKey) || []),
+            { manifest: entry.manifest, manifestPath: entry.manifestPath },
+        ]);
+    }
+    for (const [stableKey, entries] of localByStableKey) {
+        if (entries.length > 1) {
+            blockers.push(`Duplicate source Endpoint stableKey "${stableKey}".`);
+            for (const entry of entries) {
+                items.push({ status: 'collision', stableKey, name: entry.manifest.name, reason: 'duplicate source stableKey' });
+            }
+        }
+    }
+    const [targetEndpoints, targetComponents] = await Promise.all([
+        loadRemoteEndpoints(input.client),
+        loadRemoteComponents(input.client),
+    ]);
+    const workspaceComponents = readWorkspaceComponents(input.cwd, input.stableKeyName);
+    const targetComponentsByKey = targetComponentsByStableKey(targetComponents, input.stableKeyName);
+    for (const [stableKey, matches] of workspaceComponents) {
+        if (matches.length > 1) {
+            blockers.push(`Duplicate source Component stableKey "${stableKey}"; align Components before Endpoints.`);
+        }
+    }
+    for (const [stableKey, matches] of targetComponentsByKey) {
+        if (matches.length > 1) {
+            blockers.push(`Duplicate target Component stableKey "${stableKey}"; align Components before Endpoints.`);
+        }
+    }
+    const componentsById = new Map(targetComponents.map((component) => [componentIdOf(component), component]));
+    const liveTargetsByStableKey = new Map();
+    const deletedTargetsByStableKey = new Map();
+    const targetRouteOwners = new Map();
+    const targetRecordsByStableKey = new Map();
+    for (const record of targetEndpoints) {
+        const stableKey = readConfiguredResourceMetadataStableKey(record, input.stableKeyName);
+        if (stableKey) {
+            targetRecordsByStableKey.set(stableKey, [...(targetRecordsByStableKey.get(stableKey) || []), record]);
+        }
+    }
+    const ambiguousTargetKeys = new Set();
+    for (const [stableKey, records] of targetRecordsByStableKey) {
+        if (records.length <= 1) {
+            continue;
+        }
+        ambiguousTargetKeys.add(stableKey);
+        blockers.push(`Duplicate target Endpoint stableKey "${stableKey}".`);
+        for (const record of records) {
+            items.push({ status: 'collision', stableKey, name: String(record.name || stableKey), reason: 'duplicate target stableKey' });
+        }
+    }
+    const targetIssueKeys = new Set();
+    for (const record of targetEndpoints) {
+        const stableKey = readConfiguredResourceMetadataStableKey(record, input.stableKeyName);
+        const routeKey = endpointRecordRouteKey(record);
+        if (routeKey) {
+            targetRouteOwners.set(routeKey, [
+                ...(targetRouteOwners.get(routeKey) || []),
+                { ...(stableKey ? { stableKey } : {}), name: endpointLabel(record, 'unknown') },
+            ]);
+        }
+        if (record.deletedAt || record.deletedBy) {
+            if (stableKey) {
+                deletedTargetsByStableKey.set(stableKey, [...(deletedTargetsByStableKey.get(stableKey) || []), record]);
+            }
+            else {
+                const warning = `${endpointLabel(record, 'unknown')}: deleted unmanaged target Endpoint skipped`;
+                exclusions.push(warning);
+                items.push({ status: 'skipped', name: endpointLabel(record, 'unknown'), reason: 'deleted unmanaged target Endpoint' });
+            }
+            continue;
+        }
+        if (!stableKey) {
+            const warning = `${endpointLabel(record, 'unknown')}: unmanaged target Endpoint missing ${input.stableKeyName}`;
+            exclusions.push(warning);
+            items.push({ status: 'skipped', name: endpointLabel(record, 'unknown'), reason: `unmanaged: missing ${input.stableKeyName}` });
+            continue;
+        }
+        try {
+            const manifest = await manifestFromRecord({
+                client: input.client,
+                record,
+                stableKey,
+                stableKeyName: input.stableKeyName,
+                componentsById,
+            });
+            liveTargetsByStableKey.set(stableKey, [
+                ...(liveTargetsByStableKey.get(stableKey) || []),
+                { manifest, hash: hashPortableEndpoint(manifest) },
+            ]);
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            targetIssueKeys.add(stableKey);
+            blockers.push(`Cannot plan target Endpoint "${stableKey}": ${reason}`);
+            items.push({ status: 'conflict', stableKey, name: String(record.name || stableKey), reason });
+        }
+    }
+    const targetRouteBlockedKeys = new Set();
+    for (const [routeKey, owners] of targetRouteOwners) {
+        if (owners.length <= 1) {
+            continue;
+        }
+        const ownerNames = owners.map((owner) => owner.stableKey || owner.name).sort();
+        blockers.push(`Target Endpoint route collision on ${routeKey}: ${ownerNames.join(', ')}.`);
+        for (const owner of owners) {
+            if (owner.stableKey) {
+                targetRouteBlockedKeys.add(owner.stableKey);
+            }
+            items.push({
+                status: 'collision',
+                ...(owner.stableKey ? { stableKey: owner.stableKey } : {}),
+                name: owner.name,
+                reason: `duplicate target route ${routeKey}`,
+            });
+        }
+    }
+    const desiredRouteOwners = new Map();
+    for (const [stableKey, entries] of localByStableKey) {
+        if (entries.length === 1) {
+            const routeKey = endpointRouteKey(entries[0].manifest.route);
+            desiredRouteOwners.set(routeKey, [...(desiredRouteOwners.get(routeKey) || []), stableKey]);
+        }
+    }
+    const routeBlockedKeys = new Set(targetRouteBlockedKeys);
+    for (const [routeKey, stableKeys] of desiredRouteOwners) {
+        if (stableKeys.length > 1) {
+            blockers.push(`Endpoint route collision on ${routeKey}: ${stableKeys.join(', ')}.`);
+            for (const stableKey of stableKeys) {
+                routeBlockedKeys.add(stableKey);
+                items.push({ status: 'collision', stableKey, reason: `duplicate source route ${routeKey}` });
+            }
+        }
+        for (const stableKey of stableKeys) {
+            const collisions = (targetRouteOwners.get(routeKey) || []).filter((owner) => owner.stableKey !== stableKey);
+            if (collisions.length > 0) {
+                routeBlockedKeys.add(stableKey);
+                const collisionNames = collisions.map((owner) => owner.stableKey || owner.name).sort();
+                blockers.push(`Endpoint route collision on ${routeKey}: "${stableKey}" conflicts with target ${collisionNames.join(', ')}.`);
+                items.push({ status: 'collision', stableKey, reason: `target route ${routeKey} is owned by another Endpoint` });
+            }
+        }
+    }
+    const lock = readComponentLock(projectRoot);
+    const consumedTargets = new Set();
+    for (const [stableKey, localEntries] of localByStableKey) {
+        if (localEntries.length !== 1) {
+            continue;
+        }
+        const desired = localEntries[0].manifest;
+        const dependency = componentDependencyDiagnostics({
+            endpoint: desired,
+            workspaceComponents,
+            targetComponents: targetComponentsByKey,
+        });
+        const desiredHash = hashPortableEndpoint(desired);
+        if (ambiguousTargetKeys.has(stableKey) || targetIssueKeys.has(stableKey)) {
+            continue;
+        }
+        const deletedTargets = deletedTargetsByStableKey.get(stableKey) || [];
+        if (deletedTargets.length === 1) {
+            blockers.push(...dependency.blockers);
+            const restoreSafety = await activeDeletedEndpointRestoreBlockers({
+                client: input.client,
+                record: deletedTargets[0],
+                componentsById,
+            });
+            if (restoreSafety.length > 0) {
+                blockers.push(...restoreSafety.map((reason) => `Cannot restore Endpoint "${stableKey}": ${reason}.`));
+            }
+            if (routeBlockedKeys.has(stableKey)) {
+                continue;
+            }
+            const restoreBlocked = dependency.blockers.length > 0 || restoreSafety.length > 0;
+            items.push({
+                status: restoreBlocked ? 'restore-blocked' : 'restore',
+                stableKey,
+                name: desired.name,
+                desiredHash,
+                currentHash: endpointRevisionHash(deletedTargets[0]),
+                targetRevisionHash: endpointRevisionHash(deletedTargets[0]),
+                ...(restoreBlocked
+                    ? { reason: restoreSafety[0] || 'Component compatibility gate failed; align Components before Endpoints.' }
+                    : { reason: 'exact soft-deleted target Stable Key match' }),
+                details: dependency.details,
+            });
+            continue;
+        }
+        if (dependency.blockers.length > 0) {
+            blockers.push(...dependency.blockers);
+        }
+        if (routeBlockedKeys.has(stableKey)) {
+            continue;
+        }
+        const targets = liveTargetsByStableKey.get(stableKey) || [];
+        if (targets.length > 1) {
+            consumedTargets.add(stableKey);
+            continue;
+        }
+        if (targets.length === 0) {
+            items.push({
+                status: 'create',
+                stableKey,
+                name: desired.name,
+                desiredHash,
+                ...(dependency.blockers.length > 0
+                    ? { reason: 'Component compatibility gate failed; align Components before Endpoints.' }
+                    : {}),
+                details: dependency.details,
+            });
+            continue;
+        }
+        consumedTargets.add(stableKey);
+        const current = targets[0];
+        const baselineHash = lock.endpoints[stableKey]?.environments[input.envName]?.remoteHash;
+        const common = {
+            stableKey,
+            name: desired.name,
+            desiredHash,
+            currentHash: current.hash,
+            ...(baselineHash ? { baselineHash } : {}),
+            details: dependency.details,
+        };
+        if (desiredHash === current.hash) {
+            items.push({ status: 'clean', ...common });
+        }
+        else if (!baselineHash) {
+            items.push({
+                status: 'missing-lock',
+                ...common,
+                changedFields: diffEndpoints(desired, current.manifest),
+                reason: `missing ${input.envName} lock baseline`,
+            });
+        }
+        else if (current.hash === baselineHash) {
+            items.push({ status: 'safe-update', ...common, changedFields: diffEndpoints(desired, current.manifest), reason: 'local manifest changed; target matches lock baseline' });
+        }
+        else if (desiredHash === baselineHash) {
+            items.push({ status: 'remote-changed', ...common, changedFields: diffEndpoints(desired, current.manifest), reason: 'target changed; local manifest matches lock baseline' });
+        }
+        else {
+            items.push({ status: 'conflict', ...common, changedFields: diffEndpoints(desired, current.manifest), reason: 'local manifest and target both changed since lock baseline' });
+        }
+    }
+    for (const [stableKey, targets] of liveTargetsByStableKey) {
+        if (consumedTargets.has(stableKey) || localByStableKey.has(stableKey)
+            || targetRouteBlockedKeys.has(stableKey) || targets.length !== 1) {
+            continue;
+        }
+        items.push({ status: 'orphan', stableKey, name: targets[0].manifest.name, currentHash: targets[0].hash, reason: 'target-only Endpoint' });
+    }
+    for (const [stableKey, targets] of deletedTargetsByStableKey) {
+        if (localByStableKey.has(stableKey) || ambiguousTargetKeys.has(stableKey) || targets.length !== 1) {
+            continue;
+        }
+        items.push({
+            status: 'orphan',
+            stableKey,
+            name: String(targets[0].name || stableKey),
+            currentHash: endpointRevisionHash(targets[0]),
+            reason: 'target-only soft-deleted Endpoint',
+        });
+    }
+    const rank = new Map(ENDPOINT_PLAN_STATUS_ORDER.map((status, index) => [status, index]));
+    items.sort((left, right) => (Number(rank.get(left.status)) - Number(rank.get(right.status))
+        || String(left.stableKey || left.name || '').localeCompare(String(right.stableKey || right.name || ''))
+        || String(left.name || '').localeCompare(String(right.name || ''))
+        || String(left.reason || '').localeCompare(String(right.reason || ''))));
+    const counts = endpointPlanCounts();
+    for (const item of items) {
+        counts[item.status] += 1;
+    }
+    return {
+        resourceType: 'endpoint',
+        env: input.envName,
+        counts,
+        blockers: [...new Set(blockers)].sort(),
+        items,
+        exclusions: [...new Set(exclusions)].sort(),
+    };
+}
+function readValidWorkspaceEndpoints(cwd, stableKeyName) {
+    const result = new Map();
+    for (const entry of readWorkspaceEndpoints(cwd)) {
+        if (validateManifest(entry.manifest, stableKeyName)) {
+            result.set(entry.manifest.stableKey, { manifest: entry.manifest, manifestPath: entry.manifestPath });
+        }
+    }
+    return result;
+}
+function endpointWriteOptions(manifest, schemaComponent) {
+    const options = { ...(manifest.options || {}) };
+    if (manifest.schema && schemaComponent) {
+        const schemaId = componentIdOf(schemaComponent);
+        if (!schemaId) {
+            throw new Error(`schema dependency "${manifest.schema.stableKey}" has no target component id`);
+        }
+        options.componentSchemaId = schemaId;
+        options.componentSchemaVersion = manifest.schema.binding === 'pinned'
+            ? schemaComponent.version
+            : null;
+        options.componentSchemaElement = manifest.schema.element ?? null;
+    }
+    return Object.keys(options).length > 0 ? options : undefined;
+}
+async function resolveEndpointWritePayload(input) {
+    const targetComponents = await loadRemoteComponents(input.client);
+    const targetByKey = targetComponentsByStableKey(targetComponents, input.stableKeyName);
+    const workspaceComponents = input.workspaceComponents || readWorkspaceComponents(input.cwd, input.stableKeyName);
+    const diagnostics = componentDependencyDiagnostics({
+        endpoint: input.manifest,
+        workspaceComponents,
+        targetComponents: targetByKey,
+    });
+    if (diagnostics.blockers.length > 0) {
+        throw new Error(diagnostics.blockers.join(' '));
+    }
+    const resolve = (binding) => {
+        if (!binding) {
+            return undefined;
+        }
+        const matches = targetByKey.get(binding.stableKey) || [];
+        if (matches.length !== 1) {
+            throw new Error(`dependency "${binding.stableKey}" expected one active target Component, found ${matches.length}`);
+        }
+        return matches[0];
+    };
+    const execution = resolve(input.manifest.execution);
+    const schema = resolve(input.manifest.schema);
+    if (input.manifest.execution?.binding === 'pinned' && typeof execution?.version !== 'number') {
+        throw new Error(`pinned execution dependency "${input.manifest.execution.stableKey}" has no live target version`);
+    }
+    if (input.manifest.schema?.binding === 'pinned' && typeof schema?.version !== 'number') {
+        throw new Error(`pinned schema dependency "${input.manifest.schema.stableKey}" has no live target version`);
+    }
+    const componentId = execution ? componentIdOf(execution) : '';
+    if (execution && !componentId) {
+        throw new Error(`execution dependency "${input.manifest.execution?.stableKey}" has no target component id`);
+    }
+    const options = endpointWriteOptions(input.manifest, schema);
+    const common = {
+        name: input.manifest.name,
+        category: input.manifest.category ?? null,
+        desc: input.manifest.description ?? '',
+        metadata: input.manifest.metadata,
+        ...(execution
+            ? {
+                componentId,
+                componentVersion: input.manifest.execution?.binding === 'pinned' ? execution.version : null,
+            }
+            : { componentId: null, componentVersion: null }),
+        timeout: input.manifest.timeout ?? ENDPOINT_DEFAULT_TIMEOUT_SECONDS,
+        path: input.manifest.route.path,
+        method: input.manifest.route.method,
+        ...(options === undefined ? {} : { options }),
+    };
+    return common;
+}
+async function updateEndpointConfigurationAndActivation(input) {
+    const latest = unwrapData(await input.client.getEndpoint(input.endpointId));
+    const latestStableKey = readConfiguredResourceMetadataStableKey(latest, input.stableKeyName);
+    if (latestStableKey !== input.stableKey || latest.deletedAt || latest.deletedBy) {
+        throw new Error(`${input.targetLabel} identity changed before update`);
+    }
+    if (endpointRevisionHash(latest) !== input.expectedRevisionHash) {
+        throw new Error(`${input.targetLabel} changed before update`);
+    }
+    if (typeof latest.version !== 'number') {
+        throw new Error(`${input.targetLabel} did not include a current version`);
+    }
+    const payload = await resolveEndpointWritePayload(input);
+    await input.client.updateEndpoint(input.endpointId, {
+        ...payload,
+        options: payload.options ?? null,
+        version: latest.version,
+    });
+    const configured = unwrapData(await input.client.getEndpoint(input.endpointId));
+    if (Boolean(configured.active) !== input.manifest.active) {
+        if (input.manifest.active) {
+            await input.client.activateEndpoint(input.endpointId);
+        }
+        else {
+            await input.client.disableEndpoint(input.endpointId);
+        }
+    }
+}
+async function verifyEndpointWrite(input) {
+    const verified = unwrapData(await input.client.getEndpoint(input.endpointId));
+    const verifiedStableKey = readConfiguredResourceMetadataStableKey(verified, input.stableKeyName);
+    if (verifiedStableKey !== input.stableKey) {
+        throw new Error(`written target is missing or changed ${input.stableKeyName}`);
+    }
+    const targetComponents = await loadRemoteComponents(input.client);
+    const componentsById = new Map(targetComponents.map((component) => [componentIdOf(component), component]));
+    const verifiedManifest = await manifestFromRecord({
+        client: input.client,
+        record: verified,
+        stableKey: verifiedStableKey,
+        stableKeyName: input.stableKeyName,
+        componentsById,
+    });
+    const remoteHash = hashPortableEndpoint(verifiedManifest);
+    if (remoteHash !== input.desiredHash) {
+        const changedFields = diffEndpoints(input.desiredManifest, verifiedManifest);
+        throw new Error(`written endpoint did not match desired portable hash (fields: ${changedFields.join(', ') || 'unknown'}; desired: ${input.desiredHash}; actual: ${remoteHash})`);
+    }
+    return remoteHash;
+}
+function updateEndpointEnvironmentBaseline(input) {
+    const { projectRoot } = requireProjectLayout(input.cwd, 'Endpoint');
+    const lock = readComponentLock(projectRoot);
+    const stableKey = input.manifest.stableKey;
+    const existingPair = Object.entries(lock.endpoints).find(([, entry]) => entry.stableKey === stableKey);
+    const existing = existingPair?.[1];
+    if (existingPair && existingPair[0] !== stableKey) {
+        delete lock.endpoints[existingPair[0]];
+    }
+    const previousBaseline = existing?.environments[input.envName];
+    lock.endpoints[stableKey] = {
+        stableKey,
+        path: toPortableRelativePath(projectRoot, input.manifestPath),
+        sourceHash: hashPortableEndpoint(input.manifest),
+        environments: {
+            ...(existing?.environments || {}),
+            [input.envName]: previousBaseline?.remoteHash === input.remoteHash
+                ? previousBaseline
+                : { remoteHash: input.remoteHash, syncedAt: new Date().toISOString() },
+        },
+    };
+    writeComponentLock(projectRoot, lock);
+}
+async function executeEndpointPushItem(input) {
+    const stableKey = input.item.stableKey || '';
+    const local = input.localByKey.get(stableKey);
+    const targetPath = local ? localTargetPath(input.cwd, local.manifestPath) : stableKey;
+    try {
+        if (!local) {
+            throw new Error('desired manifest disappeared after planning');
+        }
+        const desiredHash = hashPortableEndpoint(local.manifest);
+        if (desiredHash !== input.item.desiredHash) {
+            throw new Error('desired manifest changed after planning');
+        }
+        const prepared = {
+            stableKey,
+            manifest: local.manifest,
+        };
+        const endpointId = await input.mutate(prepared);
+        const remoteHash = await verifyEndpointWrite({
+            client: input.client,
+            endpointId,
+            stableKey,
+            desiredManifest: local.manifest,
+            desiredHash,
+            stableKeyName: input.stableKeyName,
+        });
+        updateEndpointEnvironmentBaseline({
+            cwd: input.cwd,
+            envName: input.envName,
+            manifest: local.manifest,
+            manifestPath: local.manifestPath,
+            remoteHash,
+        });
+        return { stableKey, action: input.action, status: 'deployed', targetPath };
+    }
+    catch (error) {
+        return {
+            stableKey,
+            action: input.action,
+            status: 'failed',
+            targetPath,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+export async function pushEndpoints(input) {
+    const plan = await buildEndpointsPlan(input);
+    if (plan.blockers.length > 0) {
+        throw new Error(`Endpoint push blocked: ${plan.blockers.join(' ')}`);
+    }
+    const contentBlockers = plan.items.filter((item) => ['missing-lock', 'remote-changed', 'conflict'].includes(item.status));
+    if (contentBlockers.length > 0 && !input.force) {
+        const statuses = [...new Set(contentBlockers.map((item) => item.status))].sort().join(', ');
+        throw new Error(`Endpoint push blocked by ${statuses}; review the plan and re-run with --force only to adopt or overwrite reviewed content drift.`);
+    }
+    const localByKey = readValidWorkspaceEndpoints(input.cwd, input.stableKeyName);
+    const workspaceComponents = readWorkspaceComponents(input.cwd, input.stableKeyName);
+    const results = [];
+    for (const item of plan.items.filter((candidate) => candidate.status === 'create')) {
+        results.push(await executeEndpointPushItem({
+            ...input,
+            item,
+            localByKey,
+            action: 'create',
+            mutate: async (prepared) => {
+                const payload = await resolveEndpointWritePayload({
+                    ...input,
+                    manifest: prepared.manifest,
+                    workspaceComponents,
+                });
+                const createPayload = { ...payload, active: false };
+                if (!prepared.manifest.execution) {
+                    delete createPayload.componentId;
+                    delete createPayload.componentVersion;
+                }
+                const created = unwrapData(await input.client.createEndpoint(createPayload));
+                const createdId = endpointIdOf(created);
+                if (!createdId) {
+                    throw new Error('create response did not include endpointId');
+                }
+                if (prepared.manifest.active) {
+                    await input.client.activateEndpoint(createdId);
+                }
+                return createdId;
+            },
+        }));
+    }
+    for (const item of plan.items.filter((candidate) => candidate.status === 'restore')) {
+        results.push(await executeEndpointPushItem({
+            ...input,
+            item,
+            localByKey,
+            action: 'restore',
+            mutate: async (prepared) => {
+                const liveEndpoints = await loadRemoteEndpoints(input.client);
+                const matches = liveEndpoints.filter((record) => (Boolean(record.deletedAt || record.deletedBy)
+                    && readConfiguredResourceMetadataStableKey(record, input.stableKeyName) === prepared.stableKey));
+                if (matches.length !== 1) {
+                    throw new Error(`expected one deleted target match, found ${matches.length}`);
+                }
+                const target = matches[0];
+                const targetId = endpointIdOf(target);
+                if (!targetId) {
+                    throw new Error('deleted target did not include endpointId');
+                }
+                if (endpointRevisionHash(target) !== item.targetRevisionHash) {
+                    throw new Error('deleted target changed after planning');
+                }
+                const targetComponents = await loadRemoteComponents(input.client);
+                const restoreBlockers = await activeDeletedEndpointRestoreBlockers({
+                    client: input.client,
+                    record: target,
+                    componentsById: new Map(targetComponents.map((component) => [componentIdOf(component), component])),
+                });
+                if (restoreBlockers.length > 0) {
+                    throw new Error(`restore safety changed after planning: ${restoreBlockers.join('; ')}`);
+                }
+                await input.client.restoreEndpoint(targetId);
+                const restored = unwrapData(await input.client.getEndpoint(targetId));
+                const restoredStableKey = readConfiguredResourceMetadataStableKey(restored, input.stableKeyName);
+                if (restoredStableKey !== prepared.stableKey) {
+                    throw new Error(`restored target is missing or changed ${input.stableKeyName}`);
+                }
+                if (restored.deletedAt || restored.deletedBy) {
+                    throw new Error('target remained soft-deleted after restore');
+                }
+                if (typeof restored.version !== 'number') {
+                    throw new Error('restored target did not include version');
+                }
+                await updateEndpointConfigurationAndActivation({
+                    client: input.client,
+                    cwd: input.cwd,
+                    stableKeyName: input.stableKeyName,
+                    endpointId: targetId,
+                    stableKey: prepared.stableKey,
+                    manifest: prepared.manifest,
+                    expectedRevisionHash: endpointRevisionHash(restored),
+                    targetLabel: 'restored target',
+                    workspaceComponents,
+                });
+                return targetId;
+            },
+        }));
+    }
+    const updateItems = plan.items.filter((candidate) => (['safe-update', 'remote-changed', 'conflict', 'missing-lock'].includes(candidate.status)));
+    for (const item of updateItems) {
+        results.push(await executeEndpointPushItem({
+            ...input,
+            item,
+            localByKey,
+            action: 'update',
+            mutate: async (prepared) => {
+                const liveEndpoints = await loadRemoteEndpoints(input.client);
+                const matches = liveEndpoints.filter((record) => (!record.deletedAt
+                    && !record.deletedBy
+                    && readConfiguredResourceMetadataStableKey(record, input.stableKeyName) === prepared.stableKey));
+                if (matches.length !== 1) {
+                    throw new Error(`expected one live target match, found ${matches.length}`);
+                }
+                const target = matches[0];
+                const targetId = endpointIdOf(target);
+                if (!targetId) {
+                    throw new Error('live target did not include endpointId');
+                }
+                const targetComponents = await loadRemoteComponents(input.client);
+                const targetManifest = await manifestFromRecord({
+                    client: input.client,
+                    record: target,
+                    stableKey: prepared.stableKey,
+                    stableKeyName: input.stableKeyName,
+                    componentsById: new Map(targetComponents.map((component) => [componentIdOf(component), component])),
+                });
+                const targetHash = hashPortableEndpoint(targetManifest);
+                if (targetHash !== item.currentHash) {
+                    throw new Error('target changed after planning');
+                }
+                if (typeof target.version !== 'number') {
+                    throw new Error('live target did not include version');
+                }
+                await updateEndpointConfigurationAndActivation({
+                    client: input.client,
+                    cwd: input.cwd,
+                    stableKeyName: input.stableKeyName,
+                    endpointId: targetId,
+                    stableKey: prepared.stableKey,
+                    manifest: prepared.manifest,
+                    expectedRevisionHash: endpointRevisionHash(target),
+                    targetLabel: 'target',
+                    workspaceComponents,
+                });
+                return targetId;
+            },
+        }));
+    }
+    for (const item of plan.items.filter((candidate) => candidate.status === 'clean')) {
+        const stableKey = item.stableKey || '';
+        const local = localByKey.get(stableKey);
+        if (local && item.currentHash) {
+            updateEndpointEnvironmentBaseline({
+                cwd: input.cwd,
+                envName: input.envName,
+                manifest: local.manifest,
+                manifestPath: local.manifestPath,
+                remoteHash: item.currentHash,
+            });
+        }
+        results.push({
+            stableKey,
+            action: 'noop',
+            status: 'skipped',
+            targetPath: local ? localTargetPath(input.cwd, local.manifestPath) : stableKey,
+            reason: 'no local changes',
+        });
+    }
+    for (const item of plan.items.filter((candidate) => candidate.status === 'orphan')) {
+        results.push({ stableKey: item.stableKey || item.name || '', action: 'orphan', status: 'skipped', targetPath: item.stableKey || item.name || '', reason: 'target-only orphan' });
+    }
+    for (const item of plan.items.filter((candidate) => candidate.status === 'skipped')) {
+        results.push({ stableKey: item.stableKey || item.name || '', action: 'skipped', status: 'skipped', targetPath: item.stableKey || item.name || '', reason: item.reason || 'unmanaged' });
+    }
+    return { plan, results };
+}