@revoengine/cli 1.0.10 → 1.0.11

package/dist/src/resource-syncs/job-template-sync.js

@@ -0,0 +1,782 @@
+import path from 'node:path';
+import { hashStable, readComponentLock, writeComponentLock } from "../component-lock.js";
+import { normalizeStableKeyValue, readConfiguredResourceMetadataStableKey, sanitizeUserMetadata } from "../resource-metadata.js";
+import { readJsonFile, sanitizeSegment } from "../utils.js";
+import { findManifestFiles, isRecord, localTargetPath, requireProjectLayout, stableKeySuffix, toPortableRelativePath, unwrapData, writePulledManifest, } from "./util.js";
+export const JOB_TEMPLATES_DIRECTORY = 'JobTemplates';
+export const JOB_TEMPLATE_MANIFEST_FILE = 'job-template.json';
+const DEFAULT_JOB_TEMPLATE_MEMORY_MB = 128;
+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 canonicalJobTemplateInputs(value) {
+    // The Automation API materializes a nullable inputs field as an empty object
+    // on readback. Treat both representations as the same portable state so a
+    // successful write is not reported as unverified solely for that conversion.
+    if (value === null)
+        return {};
+    return canonicalValue(value);
+}
+function canonicalJobTemplateOptions(value, inputs) {
+    const canonical = canonicalValue(value);
+    if (!isRecord(canonical))
+        return canonical;
+    const normalized = { ...canonical };
+    // The Automation API materializes these defaults after create even when the
+    // source omitted them. They are semantically equivalent in portable state.
+    if (normalized.memory === DEFAULT_JOB_TEMPLATE_MEMORY_MB)
+        delete normalized.memory;
+    const canonicalInputs = canonicalJobTemplateInputs(inputs);
+    const inputIsEmpty = isRecord(normalized.input) && Object.keys(normalized.input).length === 0;
+    const inputDuplicatesLegacyInputs = inputs !== undefined
+        && JSON.stringify(normalized.input) === JSON.stringify(canonicalInputs);
+    if (inputIsEmpty || inputDuplicatesLegacyInputs)
+        delete normalized.input;
+    return Object.keys(normalized).length === 0 ? undefined : normalized;
+}
+function canonicalMetadata(record, stableKeyName, stableKey) {
+    const source = [record.metadata, record.metaData, record.resourceMetadata].find(isRecord);
+    return canonicalValue({
+        ...sanitizeUserMetadata(source),
+        [stableKeyName]: stableKey,
+    });
+}
+function jobTemplateIdOf(record) {
+    return String(record.jobTemplateId || record.id || '');
+}
+function componentIdOf(record) {
+    return String(record.componentId || record.id || '');
+}
+export function jobTemplateManifestPath(workspaceRoot, manifest) {
+    const category = typeof manifest.category === 'string' && manifest.category.trim()
+        ? sanitizeSegment(manifest.category)
+        : 'Uncategorized';
+    return path.join(workspaceRoot, JOB_TEMPLATES_DIRECTORY, category, `${sanitizeSegment(manifest.name)}-${stableKeySuffix(manifest.stableKey)}`, JOB_TEMPLATE_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);
+    const disambiguatedDirectory = `${path.basename(directory)}-${hashStable(stableKey).slice(0, 8)}`;
+    return path.join(path.dirname(directory), disambiguatedDirectory, path.basename(filePath));
+}
+function readWorkspaceJobTemplates(cwd) {
+    const { workspaceRoot } = requireProjectLayout(cwd, 'Job-template');
+    return findManifestFiles(path.join(workspaceRoot, JOB_TEMPLATES_DIRECTORY), JOB_TEMPLATE_MANIFEST_FILE).map((manifestPath) => ({
+        manifestPath,
+        manifest: readJsonFile(manifestPath),
+    }));
+}
+async function loadRemoteJobTemplates(client) {
+    const { jobTemplates } = await client.listAllJobTemplates();
+    const records = [];
+    for (const summary of jobTemplates) {
+        const id = jobTemplateIdOf(summary);
+        records.push(id ? unwrapData(await client.getJobTemplate(id)) : summary);
+    }
+    return records;
+}
+async function loadRemoteComponents(client) {
+    const { components } = await client.listAllComponents();
+    const records = [];
+    for (const summary of components) {
+        const id = componentIdOf(summary);
+        records.push(id ? unwrapData(await client.getComponent(id)) : summary);
+    }
+    return records;
+}
+const JOB_TEMPLATE_MANIFEST_FIELDS = new Set([
+    'kind', 'stableKey', 'name', 'category', 'description', 'metadata', 'component',
+    'timeout', 'options', 'inputs', 'migration',
+]);
+const JOB_TEMPLATE_MIGRATION_FIELDS = new Set(['componentBinding', 'executionPrincipal']);
+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 isOptionalString(value, { nullable = false } = {}) {
+    return value === undefined || (nullable && value === null) || typeof value === 'string';
+}
+function isOptionalRecord(value, { nullable = false } = {}) {
+    return value === undefined || (nullable && value === null) || isRecord(value);
+}
+function isOptionalFiniteNumber(value) {
+    return value === undefined || (typeof value === 'number' && Number.isFinite(value));
+}
+function hasValidJobTemplateComponent(value) {
+    return isRecord(value)
+        && hasOnlyKeys(value, new Set(['stableKey']))
+        && isNonEmptyString(value.stableKey);
+}
+function hasValidJobTemplateMigration(value) {
+    return value === undefined || (isRecord(value)
+        && hasOnlyKeys(value, JOB_TEMPLATE_MIGRATION_FIELDS)
+        && (value.componentBinding === undefined || value.componentBinding === 'pinned-unsupported')
+        && (value.executionPrincipal === undefined || value.executionPrincipal === 'excluded'));
+}
+function validateManifest(manifest, stableKeyName) {
+    if (!isRecord(manifest) || !hasOnlyKeys(manifest, JOB_TEMPLATE_MANIFEST_FIELDS)) {
+        return false;
+    }
+    if (manifest.kind !== 'job-template') {
+        return false;
+    }
+    if (!isNonEmptyString(manifest.stableKey) || !isNonEmptyString(manifest.name)) {
+        return false;
+    }
+    if (!isRecord(manifest.metadata) || !hasValidJobTemplateComponent(manifest.component)) {
+        return false;
+    }
+    if (!isOptionalString(manifest.category, { nullable: true })) {
+        return false;
+    }
+    if (!isOptionalString(manifest.description)) {
+        return false;
+    }
+    if (!isOptionalFiniteNumber(manifest.timeout)) {
+        return false;
+    }
+    if (!isOptionalRecord(manifest.options, { nullable: true })) {
+        return false;
+    }
+    if (!isOptionalRecord(manifest.inputs, { nullable: true })) {
+        return false;
+    }
+    if (!hasValidJobTemplateMigration(manifest.migration)) {
+        return false;
+    }
+    return readConfiguredResourceMetadataStableKey(manifest, stableKeyName) === manifest.stableKey;
+}
+async function componentStableKey(input) {
+    const embedded = isRecord(input.record.component) ? input.record.component : null;
+    let component = embedded;
+    if (!readConfiguredResourceMetadataStableKey(component || {}, input.stableKeyName)) {
+        const componentId = String(input.record.componentId || embedded?.componentId || embedded?.id || '');
+        if (componentId)
+            component = unwrapData(await input.client.getComponent(componentId));
+    }
+    return readConfiguredResourceMetadataStableKey(component || {}, input.stableKeyName);
+}
+function manifestFromRecord(record, stableKey, componentKey, stableKeyName) {
+    return {
+        kind: 'job-template',
+        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, stableKeyName, stableKey),
+        component: { stableKey: componentKey },
+        ...(typeof record.timeout === 'number' ? { timeout: record.timeout } : {}),
+        ...(record.options === undefined ? {} : { options: canonicalValue(record.options) }),
+        ...(record.inputs === undefined ? {} : { inputs: canonicalValue(record.inputs) }),
+    };
+}
+function buildCreatePayload(manifest, componentId) {
+    return {
+        name: manifest.name,
+        ...(manifest.category === undefined ? {} : { category: manifest.category }),
+        ...(manifest.description === undefined ? {} : { desc: manifest.description }),
+        metadata: canonicalValue(manifest.metadata),
+        componentId,
+        ...(manifest.timeout === undefined ? {} : { timeout: manifest.timeout }),
+        ...(manifest.options === undefined ? {} : { options: canonicalValue(manifest.options) }),
+        ...(manifest.inputs === undefined ? {} : { inputs: canonicalValue(manifest.inputs) }),
+    };
+}
+function buildUpdatePayload(manifest, componentId, version) {
+    return {
+        name: manifest.name,
+        category: manifest.category ?? null,
+        desc: manifest.description ?? '',
+        metadata: canonicalValue(manifest.metadata),
+        componentId,
+        ...(manifest.timeout === undefined ? {} : { timeout: manifest.timeout }),
+        ...(manifest.options === undefined ? {} : { options: canonicalValue(manifest.options) }),
+        ...(manifest.inputs === undefined ? {} : { inputs: canonicalValue(manifest.inputs) }),
+        version,
+    };
+}
+export function hashPortableJobTemplate(manifest) {
+    const options = canonicalJobTemplateOptions(manifest.options, manifest.inputs);
+    return hashStable({
+        kind: 'job-template',
+        stableKey: manifest.stableKey,
+        name: manifest.name,
+        category: manifest.category ?? null,
+        description: manifest.description ?? '',
+        metadata: canonicalValue(manifest.metadata),
+        component: { stableKey: manifest.component.stableKey },
+        ...(manifest.timeout === undefined ? {} : { timeout: manifest.timeout }),
+        ...(options === undefined ? {} : { options }),
+        ...(manifest.inputs === undefined ? {} : { inputs: canonicalJobTemplateInputs(manifest.inputs) }),
+    });
+}
+function diffJobTemplates(desired, target) {
+    const fields = [
+        ['name', desired.name, target.name],
+        ['category', desired.category ?? null, target.category ?? null],
+        ['description', desired.description ?? '', target.description ?? ''],
+        ['metadata', canonicalValue(desired.metadata), canonicalValue(target.metadata)],
+        ['component.stableKey', desired.component.stableKey, target.component.stableKey],
+        ['timeout', desired.timeout, target.timeout],
+        [
+            'options',
+            canonicalJobTemplateOptions(desired.options, desired.inputs),
+            canonicalJobTemplateOptions(target.options, target.inputs),
+        ],
+        ['inputs', canonicalJobTemplateInputs(desired.inputs), canonicalJobTemplateInputs(target.inputs)],
+    ];
+    return fields
+        .filter(([, desiredValue, targetValue]) => (hashStable({ value: desiredValue }) !== hashStable({ value: targetValue })))
+        .map(([field]) => field)
+        .sort((left, right) => left.localeCompare(right));
+}
+function emptyPlanCounts() {
+    return {
+        clean: 0,
+        create: 0,
+        'safe-update': 0,
+        'remote-changed': 0,
+        conflict: 0,
+        'missing-lock': 0,
+        orphan: 0,
+        collision: 0,
+        skipped: 0,
+    };
+}
+export async function buildJobTemplatesPlan(input) {
+    const { projectRoot } = requireProjectLayout(input.cwd, 'Job-template');
+    const lock = readComponentLock(projectRoot);
+    const localEntries = readWorkspaceJobTemplates(input.cwd);
+    const targetRecords = await loadRemoteJobTemplates(input.client);
+    const targetComponents = await loadRemoteComponents(input.client);
+    const blockers = [];
+    const warnings = [];
+    const items = [];
+    const lockEntriesByKey = new Map(Object.values(lock.jobTemplates).map((entry) => [entry.stableKey, entry]));
+    const targetComponentKeysById = new Map();
+    const activeTargetComponentIds = new Set();
+    const targetComponentsByKey = new Map();
+    for (const component of targetComponents) {
+        const stableKey = readConfiguredResourceMetadataStableKey(component, input.stableKeyName);
+        const id = componentIdOf(component);
+        if (id)
+            activeTargetComponentIds.add(id);
+        if (!stableKey)
+            continue;
+        targetComponentsByKey.set(stableKey, [...(targetComponentsByKey.get(stableKey) || []), component]);
+        if (id)
+            targetComponentKeysById.set(id, stableKey);
+    }
+    const localByKey = new Map();
+    for (const entry of localEntries) {
+        if (!validateManifest(entry.manifest, input.stableKeyName)) {
+            blockers.push(`Invalid job-template manifest ${path.relative(projectRoot, entry.manifestPath)}.`);
+            items.push({ status: 'conflict', name: path.basename(path.dirname(entry.manifestPath)), reason: 'invalid job-template manifest' });
+            continue;
+        }
+        localByKey.set(entry.manifest.stableKey, [...(localByKey.get(entry.manifest.stableKey) || []), entry]);
+    }
+    const targetRecordsByKey = new Map();
+    for (const record of targetRecords) {
+        const stableKey = readConfiguredResourceMetadataStableKey(record, input.stableKeyName);
+        if (!stableKey) {
+            const name = String(record.name || jobTemplateIdOf(record) || 'unknown');
+            items.push({ status: 'skipped', name, reason: `missing ${input.stableKeyName}; unmanaged target resource` });
+            continue;
+        }
+        targetRecordsByKey.set(stableKey, [...(targetRecordsByKey.get(stableKey) || []), { record, stableKey }]);
+        if (typeof record.componentVersion === 'number') {
+            blockers.push(`Target job template "${stableKey}" uses a pinned component version, which is unsupported.`);
+        }
+    }
+    const duplicateTargetKeys = new Set();
+    for (const [stableKey, candidates] of targetRecordsByKey) {
+        if (candidates.length < 2) {
+            continue;
+        }
+        duplicateTargetKeys.add(stableKey);
+        const selected = [...candidates].sort((left, right) => left.stableKey.localeCompare(right.stableKey)
+            || String(left.record.name || '').localeCompare(String(right.record.name || '')))[0];
+        blockers.push(`Duplicate target job-template stableKey "${selected.stableKey}".`);
+        items.push({ status: 'collision', stableKey: selected.stableKey, name: String(selected.record.name || ''), reason: 'duplicate target stableKey' });
+    }
+    const invalidTargetKeys = new Set();
+    const targetByKey = new Map();
+    for (const [stableKeyIdentity, candidates] of targetRecordsByKey) {
+        if (duplicateTargetKeys.has(stableKeyIdentity))
+            continue;
+        const { record, stableKey } = candidates[0];
+        const embedded = isRecord(record.component) ? record.component : null;
+        const referencedComponentId = String(record.componentId || componentIdOf(embedded || {}) || '');
+        const componentKey = referencedComponentId ? targetComponentKeysById.get(referencedComponentId) : undefined;
+        if (!componentKey) {
+            invalidTargetKeys.add(stableKeyIdentity);
+            const missingKey = referencedComponentId && activeTargetComponentIds.has(referencedComponentId);
+            const reason = missingKey
+                ? `references a component without ${input.stableKeyName}`
+                : 'does not resolve to an active target component';
+            blockers.push(`Target job template "${stableKey}" ${reason}.`);
+            items.push({ status: 'conflict', stableKey, name: String(record.name || ''), reason });
+            continue;
+        }
+        const manifest = manifestFromRecord(record, stableKey, componentKey, input.stableKeyName);
+        targetByKey.set(stableKeyIdentity, [{
+                record,
+                manifest,
+                hash: hashPortableJobTemplate(manifest),
+                pinned: typeof record.componentVersion === 'number',
+            }]);
+    }
+    const consumedTargetKeys = new Set();
+    for (const [stableKeyIdentity, entries] of localByKey) {
+        if (entries.length > 1) {
+            const desired = entries[0].manifest;
+            blockers.push(`Duplicate desired job-template stableKey "${desired.stableKey}".`);
+            items.push({ status: 'collision', stableKey: desired.stableKey, name: desired.name, reason: 'duplicate desired stableKey' });
+            continue;
+        }
+        const desired = entries[0].manifest;
+        const lockEntry = lockEntriesByKey.get(stableKeyIdentity);
+        if (desired.migration?.executionPrincipal === 'excluded' || lockEntry?.migration?.executionPrincipal === 'excluded') {
+            warnings.push(`Job template "${desired.stableKey}": source execution principal is excluded from migration.`);
+        }
+        if (desired.migration?.componentBinding === 'pinned-unsupported' || lockEntry?.migration?.componentBinding === 'pinned-unsupported') {
+            blockers.push(`Job template "${desired.stableKey}" uses a pinned component version, which is unsupported.`);
+            items.push({ status: 'conflict', stableKey: desired.stableKey, name: desired.name, reason: 'pinned component version is unsupported', componentStableKey: desired.component.stableKey });
+            continue;
+        }
+        if (duplicateTargetKeys.has(stableKeyIdentity) || invalidTargetKeys.has(stableKeyIdentity)) {
+            consumedTargetKeys.add(stableKeyIdentity);
+            continue;
+        }
+        const dependencyMatches = targetComponentsByKey.get(desired.component.stableKey) || [];
+        if (dependencyMatches.length !== 1) {
+            const reason = dependencyMatches.length === 0 ? 'target component is missing' : 'target component stableKey is ambiguous';
+            blockers.push(`Job template "${desired.stableKey}" dependency "${desired.component.stableKey}": ${reason}.`);
+            items.push({ status: 'conflict', stableKey: desired.stableKey, name: desired.name, reason, componentStableKey: desired.component.stableKey });
+            continue;
+        }
+        const desiredHash = hashPortableJobTemplate(desired);
+        const matches = targetByKey.get(stableKeyIdentity) || [];
+        if (matches.length === 0) {
+            items.push({ status: 'create', stableKey: desired.stableKey, name: desired.name, desiredHash, componentStableKey: desired.component.stableKey });
+            continue;
+        }
+        consumedTargetKeys.add(stableKeyIdentity);
+        const target = matches[0];
+        if (target.pinned) {
+            blockers.push(`Target job template "${desired.stableKey}" uses a pinned component version, which is unsupported.`);
+            items.push({ status: 'conflict', stableKey: desired.stableKey, name: desired.name, reason: 'target pinned component version is unsupported', componentStableKey: desired.component.stableKey });
+            continue;
+        }
+        const changedFields = diffJobTemplates(desired, target.manifest);
+        const changeDetails = changedFields.length > 0 ? { changedFields } : {};
+        const baseline = lockEntry?.environments[input.envName]?.remoteHash;
+        if (!baseline) {
+            items.push({ status: 'missing-lock', stableKey: desired.stableKey, name: desired.name, desiredHash, currentHash: target.hash, reason: `missing ${input.envName} lock baseline`, componentStableKey: desired.component.stableKey, ...changeDetails });
+        }
+        else if (desiredHash === target.hash) {
+            items.push({ status: 'clean', stableKey: desired.stableKey, name: desired.name, desiredHash, currentHash: target.hash, componentStableKey: desired.component.stableKey });
+        }
+        else if (target.hash === baseline) {
+            items.push({ status: 'safe-update', stableKey: desired.stableKey, name: desired.name, desiredHash, currentHash: target.hash, baselineHash: baseline, reason: 'local manifest changed; target matches lock baseline', componentStableKey: desired.component.stableKey, ...changeDetails });
+        }
+        else if (desiredHash === baseline) {
+            items.push({ status: 'remote-changed', stableKey: desired.stableKey, name: desired.name, desiredHash, currentHash: target.hash, baselineHash: baseline, reason: 'target changed; local manifest matches lock baseline', componentStableKey: desired.component.stableKey, ...changeDetails });
+        }
+        else {
+            items.push({ status: 'conflict', stableKey: desired.stableKey, name: desired.name, desiredHash, currentHash: target.hash, baselineHash: baseline, reason: 'local manifest and target both changed since lock baseline', componentStableKey: desired.component.stableKey, ...changeDetails });
+        }
+    }
+    for (const [stableKeyIdentity, matches] of targetByKey) {
+        if (consumedTargetKeys.has(stableKeyIdentity) || localByKey.has(stableKeyIdentity))
+            continue;
+        const target = matches[0];
+        items.push({ status: 'orphan', stableKey: target.manifest.stableKey, name: target.manifest.name, currentHash: target.hash, reason: 'target-only job-template' });
+    }
+    const rank = {
+        create: 0,
+        'safe-update': 1,
+        'remote-changed': 2,
+        conflict: 3,
+        'missing-lock': 4,
+        clean: 5,
+        orphan: 6,
+        collision: 7,
+        skipped: 8,
+    };
+    items.sort((left, right) => {
+        const leftKey = left.stableKey || left.name;
+        const rightKey = right.stableKey || right.name;
+        return rank[left.status] - rank[right.status]
+            || normalizeStableKeyValue(leftKey).localeCompare(normalizeStableKeyValue(rightKey))
+            || leftKey.localeCompare(rightKey);
+    });
+    const counts = emptyPlanCounts();
+    for (const item of items)
+        counts[item.status] += 1;
+    return {
+        resourceType: 'job-template',
+        env: input.envName,
+        counts,
+        blockers: [...new Set(blockers)].sort((left, right) => left.localeCompare(right)),
+        warnings: [...new Set(warnings)].sort((left, right) => left.localeCompare(right)),
+        items,
+        exclusions: ['UUID, version, componentVersion and triggerUser are never persisted', 'target-only orphans are informational and never deleted'],
+    };
+}
+export async function pullJobTemplatesToWorkspace(input) {
+    const { projectRoot, workspaceRoot } = requireProjectLayout(input.cwd, 'Job-template');
+    const { jobTemplates } = await input.client.listAllJobTemplates();
+    const manifests = [];
+    const warnings = [];
+    const missing = [];
+    const stableKeys = new Set();
+    for (const summary of jobTemplates) {
+        const id = jobTemplateIdOf(summary);
+        const record = id ? unwrapData(await input.client.getJobTemplate(id)) : summary;
+        const stableKey = readConfiguredResourceMetadataStableKey(record, input.stableKeyName);
+        if (!stableKey) {
+            missing.push(String(record.name || id || 'unknown'));
+            continue;
+        }
+        if (stableKeys.has(stableKey))
+            throw new Error(`Duplicate job-template stableKey "${stableKey}" on ${input.envName}; no files were changed.`);
+        stableKeys.add(stableKey);
+        const dependencyStableKey = await componentStableKey({ client: input.client, record, stableKeyName: input.stableKeyName });
+        if (!dependencyStableKey)
+            throw new Error(`Job template "${stableKey}" references a component without ${input.stableKeyName}; no files were changed.`);
+        const migration = {
+            ...(typeof record.componentVersion === 'number' ? { componentBinding: 'pinned-unsupported' } : {}),
+            ...(record.triggerUser ? { executionPrincipal: 'excluded' } : {}),
+        };
+        manifests.push({
+            ...manifestFromRecord(record, stableKey, dependencyStableKey, input.stableKeyName),
+            ...(Object.keys(migration).length > 0 ? { migration } : {}),
+        });
+        if (record.triggerUser)
+            warnings.push({ stableKey, reason: 'triggerUser execution principal skipped' });
+    }
+    if (missing.length > 0)
+        throw new Error(`Active source job template(s) missing ${input.stableKeyName}: ${missing.sort().join(', ')}; no files were changed.`);
+    manifests.sort((left, right) => left.stableKey.localeCompare(right.stableKey));
+    warnings.sort((left, right) => left.stableKey.localeCompare(right.stableKey));
+    const lock = readComponentLock(projectRoot);
+    const existingByKey = new Map();
+    const existingByPath = new Map();
+    for (const entry of readWorkspaceJobTemplates(input.cwd)) {
+        if (!validateManifest(entry.manifest, input.stableKeyName)) {
+            throw new Error(`Cannot pull over invalid job-template manifest ${path.relative(projectRoot, entry.manifestPath)}.`);
+        }
+        if (existingByKey.has(entry.manifest.stableKey))
+            throw new Error(`Duplicate local job-template stableKey "${entry.manifest.stableKey}"; no files were changed.`);
+        existingByKey.set(entry.manifest.stableKey, entry);
+        const pathIdentity = portablePathIdentity(entry.manifestPath);
+        existingByPath.set(pathIdentity, [...(existingByPath.get(pathIdentity) || []), entry]);
+    }
+    const writes = manifests.map((manifest) => {
+        const hash = hashPortableJobTemplate(manifest);
+        const existing = existingByKey.get(manifest.stableKey);
+        if (existing && !input.force) {
+            const localHash = hashPortableJobTemplate(existing.manifest);
+            const baseline = lock.jobTemplates[manifest.stableKey];
+            if (localHash !== hash && (!baseline || localHash !== baseline.sourceHash)) {
+                throw new Error(`Cannot pull job-template "${manifest.stableKey}": local manifest changed since the lock baseline. Re-run with --force.`);
+            }
+        }
+        const filePath = jobTemplateManifestPath(workspaceRoot, manifest);
+        return { manifest, hash, filePath, 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 pathIdentity = portablePathIdentity(write.filePath);
+        if (paths.has(pathIdentity))
+            throw new Error('Multiple job templates resolve to the same workspace path; no files were changed.');
+        paths.add(pathIdentity);
+        const pathOwner = (existingByPath.get(pathIdentity) || [])
+            .find((entry) => entry.manifest.stableKey !== write.manifest.stableKey);
+        if (pathOwner) {
+            throw new Error(`Job-template workspace path "${path.relative(projectRoot, write.filePath)}" is occupied by different stableKey "${pathOwner.manifest.stableKey}"; no files were changed.`);
+        }
+    }
+    const root = path.join(workspaceRoot, JOB_TEMPLATES_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.jobTemplates[write.manifest.stableKey];
+        const previousBaseline = previous?.environments[input.envName];
+        const entry = {
+            stableKey: write.manifest.stableKey,
+            path: toPortableRelativePath(projectRoot, write.filePath),
+            sourceHash: write.hash,
+            ...(write.manifest.migration
+                ? { migration: write.manifest.migration }
+                : {}),
+            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.jobTemplates[write.manifest.stableKey] = entry;
+    }
+    if (lockChanged)
+        writeComponentLock(projectRoot, lock);
+    return {
+        pulled: writes.map((write) => ({ manifest: write.manifest, targetPath: localTargetPath(input.cwd, write.filePath) })),
+        warnings,
+    };
+}
+async function prepareJobTemplateCreates(input) {
+    const localByKey = new Map(readWorkspaceJobTemplates(input.cwd)
+        .filter((entry) => validateManifest(entry.manifest, input.stableKeyName))
+        .map((entry) => [entry.manifest.stableKey, entry]));
+    const targetTemplates = await loadRemoteJobTemplates(input.client);
+    const targetKeys = targetTemplates.map((record) => readConfiguredResourceMetadataStableKey(record, input.stableKeyName));
+    const targetComponents = await loadRemoteComponents(input.client);
+    const prepared = [];
+    for (const item of input.plan.items.filter((candidate) => candidate.status === 'create')) {
+        const stableKey = item.stableKey || '';
+        const local = localByKey.get(stableKey);
+        if (!local)
+            throw new Error(`Job-template push blocked: desired manifest "${stableKey}" disappeared after planning.`);
+        const desiredHash = hashPortableJobTemplate(local.manifest);
+        if (desiredHash !== item.desiredHash)
+            throw new Error(`Job-template push blocked: desired manifest "${stableKey}" changed after planning.`);
+        if (targetKeys.some((key) => key === stableKey)) {
+            throw new Error(`Job-template push blocked: target job template "${stableKey}" appeared after planning.`);
+        }
+        const componentMatches = targetComponents.filter((component) => (readConfiguredResourceMetadataStableKey(component, input.stableKeyName) === local.manifest.component.stableKey));
+        if (componentMatches.length !== 1) {
+            throw new Error(`Job-template push blocked: dependency "${local.manifest.component.stableKey}" expected one active target component, found ${componentMatches.length}.`);
+        }
+        const componentId = componentIdOf(componentMatches[0]);
+        if (!componentId)
+            throw new Error(`Job-template push blocked: dependency "${local.manifest.component.stableKey}" has no target component id.`);
+        prepared.push({ manifest: local.manifest, manifestPath: local.manifestPath, desiredHash, componentId });
+    }
+    return prepared.sort((left, right) => (normalizeStableKeyValue(left.manifest.stableKey).localeCompare(normalizeStableKeyValue(right.manifest.stableKey))
+        || left.manifest.stableKey.localeCompare(right.manifest.stableKey)));
+}
+function updateJobTemplateEnvironmentBaseline(input) {
+    const { projectRoot } = requireProjectLayout(input.cwd, 'Job-template');
+    const lock = readComponentLock(projectRoot);
+    const stableKey = input.manifest.stableKey;
+    const existingPair = Object.entries(lock.jobTemplates).find(([, entry]) => entry.stableKey === stableKey);
+    const existing = existingPair?.[1];
+    if (existingPair && existingPair[0] !== stableKey)
+        delete lock.jobTemplates[existingPair[0]];
+    const previousBaseline = existing?.environments[input.envName];
+    lock.jobTemplates[stableKey] = {
+        stableKey,
+        path: toPortableRelativePath(projectRoot, input.manifestPath),
+        sourceHash: hashPortableJobTemplate(input.manifest),
+        ...(input.manifest.migration ? { migration: input.manifest.migration } : {}),
+        environments: {
+            ...(existing?.environments || {}),
+            [input.envName]: previousBaseline?.remoteHash === input.remoteHash
+                ? previousBaseline
+                : { remoteHash: input.remoteHash, syncedAt: new Date().toISOString() },
+        },
+    };
+    writeComponentLock(projectRoot, lock);
+}
+export async function pushJobTemplates(input) {
+    const plan = await buildJobTemplatesPlan(input);
+    if (plan.blockers.length > 0) {
+        throw new Error(`Job-template 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(`Job-template push blocked by ${statuses}; review the plan and re-run with --force only to adopt or overwrite reviewed content drift.`);
+    }
+    const preparedCreates = await prepareJobTemplateCreates({ ...input, plan });
+    const results = [];
+    for (const prepared of preparedCreates) {
+        const stableKey = prepared.manifest.stableKey;
+        const targetPath = localTargetPath(input.cwd, prepared.manifestPath);
+        try {
+            const created = unwrapData(await input.client.createJobTemplate(buildCreatePayload(prepared.manifest, prepared.componentId)));
+            const createdId = jobTemplateIdOf(created);
+            if (!createdId)
+                throw new Error('create response did not include jobTemplateId');
+            const verified = unwrapData(await input.client.getJobTemplate(createdId));
+            const verifiedStableKey = readConfiguredResourceMetadataStableKey(verified, input.stableKeyName);
+            if (!verifiedStableKey)
+                throw new Error(`created job template is missing ${input.stableKeyName}`);
+            if (verifiedStableKey !== stableKey)
+                throw new Error(`created job template ${input.stableKeyName} does not match desired identity`);
+            const verifiedComponentKey = await componentStableKey({ client: input.client, record: verified, stableKeyName: input.stableKeyName });
+            if (!verifiedComponentKey)
+                throw new Error(`created job template references a component without ${input.stableKeyName}`);
+            const verifiedManifest = manifestFromRecord(verified, verifiedStableKey, verifiedComponentKey, input.stableKeyName);
+            if (hashPortableJobTemplate(verifiedManifest) !== prepared.desiredHash) {
+                throw new Error('created job template did not match desired portable hash');
+            }
+            updateJobTemplateEnvironmentBaseline({
+                cwd: input.cwd,
+                envName: input.envName,
+                manifest: prepared.manifest,
+                manifestPath: prepared.manifestPath,
+                remoteHash: prepared.desiredHash,
+            });
+            results.push({ stableKey, action: 'create', status: 'deployed', targetPath });
+        }
+        catch (error) {
+            results.push({
+                stableKey,
+                action: 'create',
+                status: 'failed',
+                targetPath,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    const localByKey = new Map(readWorkspaceJobTemplates(input.cwd).map((entry) => [entry.manifest.stableKey, entry]));
+    for (const item of plan.items.filter((candidate) => candidate.status === 'clean')) {
+        const local = item.stableKey ? localByKey.get(item.stableKey) : undefined;
+        if (local && item.currentHash) {
+            updateJobTemplateEnvironmentBaseline({
+                cwd: input.cwd,
+                envName: input.envName,
+                manifest: local.manifest,
+                manifestPath: local.manifestPath,
+                remoteHash: item.currentHash,
+            });
+        }
+        results.push({
+            stableKey: item.stableKey || item.name,
+            action: 'noop',
+            status: 'skipped',
+            targetPath: local ? localTargetPath(input.cwd, local.manifestPath) : item.stableKey || item.name,
+            reason: 'no local changes',
+        });
+    }
+    const updateItems = plan.items.filter((candidate) => (['safe-update', 'remote-changed', 'conflict', 'missing-lock'].includes(candidate.status)));
+    const liveTargetTemplates = updateItems.length > 0 ? await loadRemoteJobTemplates(input.client) : [];
+    const liveTargetComponents = updateItems.length > 0 ? await loadRemoteComponents(input.client) : [];
+    for (const item of updateItems) {
+        const stableKey = item.stableKey || '';
+        const local = 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 = hashPortableJobTemplate(local.manifest);
+            if (desiredHash !== item.desiredHash)
+                throw new Error('desired manifest changed after planning');
+            const targetMatches = liveTargetTemplates.filter((record) => (readConfiguredResourceMetadataStableKey(record, input.stableKeyName) === stableKey));
+            if (targetMatches.length !== 1)
+                throw new Error(`expected one live target match, found ${targetMatches.length}`);
+            const targetId = jobTemplateIdOf(targetMatches[0]);
+            if (!targetId)
+                throw new Error('live target did not include jobTemplateId');
+            const target = unwrapData(await input.client.getJobTemplate(targetId));
+            const targetStableKey = readConfiguredResourceMetadataStableKey(target, input.stableKeyName);
+            if (targetStableKey !== stableKey)
+                throw new Error('target stableKey changed after planning');
+            const targetComponentKey = await componentStableKey({ client: input.client, record: target, stableKeyName: input.stableKeyName });
+            if (!targetComponentKey)
+                throw new Error(`target dependency is missing ${input.stableKeyName}`);
+            const targetManifest = manifestFromRecord(target, targetStableKey, targetComponentKey, input.stableKeyName);
+            const targetHash = hashPortableJobTemplate(targetManifest);
+            if (targetHash !== item.currentHash)
+                throw new Error('target changed after planning');
+            if (item.status === 'missing-lock' && desiredHash === targetHash) {
+                updateJobTemplateEnvironmentBaseline({
+                    cwd: input.cwd,
+                    envName: input.envName,
+                    manifest: local.manifest,
+                    manifestPath: local.manifestPath,
+                    remoteHash: desiredHash,
+                });
+                results.push({
+                    stableKey,
+                    action: 'noop',
+                    status: 'deployed',
+                    targetPath,
+                    reason: 'force-adopted existing target into lock baseline',
+                });
+                continue;
+            }
+            if (typeof target.version !== 'number')
+                throw new Error('live target did not include version');
+            const componentMatches = liveTargetComponents.filter((component) => (readConfiguredResourceMetadataStableKey(component, input.stableKeyName) === local.manifest.component.stableKey));
+            if (componentMatches.length !== 1) {
+                throw new Error(`dependency "${local.manifest.component.stableKey}" expected one active target component, found ${componentMatches.length}`);
+            }
+            const componentId = componentIdOf(componentMatches[0]);
+            if (!componentId)
+                throw new Error(`dependency "${local.manifest.component.stableKey}" has no target component id`);
+            await input.client.updateJobTemplate(targetId, buildUpdatePayload(local.manifest, componentId, target.version));
+            const verified = unwrapData(await input.client.getJobTemplate(targetId));
+            const verifiedStableKey = readConfiguredResourceMetadataStableKey(verified, input.stableKeyName);
+            if (verifiedStableKey !== stableKey)
+                throw new Error(`updated target is missing or changed ${input.stableKeyName}`);
+            const verifiedComponentKey = await componentStableKey({ client: input.client, record: verified, stableKeyName: input.stableKeyName });
+            if (!verifiedComponentKey)
+                throw new Error(`updated target dependency is missing ${input.stableKeyName}`);
+            const verifiedManifest = manifestFromRecord(verified, verifiedStableKey, verifiedComponentKey, input.stableKeyName);
+            if (hashPortableJobTemplate(verifiedManifest) !== desiredHash) {
+                throw new Error('updated job template did not match desired portable hash');
+            }
+            updateJobTemplateEnvironmentBaseline({
+                cwd: input.cwd,
+                envName: input.envName,
+                manifest: local.manifest,
+                manifestPath: local.manifestPath,
+                remoteHash: desiredHash,
+            });
+            results.push({ stableKey, action: 'update', status: 'deployed', targetPath });
+        }
+        catch (error) {
+            results.push({
+                stableKey,
+                action: 'update',
+                status: 'failed',
+                targetPath,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    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 };
+}