@revoengine/cli 1.0.9 → 1.0.11

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

@@ -0,0 +1,882 @@
+import path from 'node:path';
+import { hashStable, readComponentLock, writeComponentLock, } from "../component-lock.js";
+import { 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 GROUPS_DIRECTORY = 'Groups';
+export const GROUP_MANIFEST_FILE = 'group.json';
+function groupIdOf(record) {
+    return String(record.groupId || record.id || '');
+}
+function groupMetadataOf(record) {
+    return {
+        ...sanitizeUserMetadata(record.resourceMetadata),
+        ...sanitizeUserMetadata(record.metaData),
+        ...sanitizeUserMetadata(record.metadata),
+    };
+}
+function groupMemberCount(record) {
+    const members = Array.isArray(record.members) ? record.members.length : 0;
+    const users = Array.isArray(record.users) ? record.users.length : 0;
+    const declared = Number.isInteger(record.memberCount) && Number(record.memberCount) > 0
+        ? Number(record.memberCount)
+        : 0;
+    return Math.max(members, users, declared);
+}
+function groupHint(value) {
+    return JSON.stringify([
+        value.category ?? null,
+        typeof value.name === 'string' ? value.name : '',
+    ]);
+}
+function stableKeyOf(record, stableKeyName) {
+    return readConfiguredResourceMetadataStableKey(record, stableKeyName);
+}
+function targetLocalWarnings(stableKey, record, preserveOwner) {
+    const warnings = [];
+    if (preserveOwner && (typeof record.ownerId === 'string' || typeof record.ownerType === 'string')) {
+        warnings.push(`Group "${stableKey}": target owner is preserved.`);
+    }
+    const memberCount = groupMemberCount(record);
+    if (memberCount > 0) {
+        warnings.push(`Group "${stableKey}": target members preserved: ${memberCount}.`);
+    }
+    return warnings;
+}
+export function groupManifestFromRecord(record, stableKeyName) {
+    const stableKey = stableKeyOf(record, stableKeyName);
+    if (!stableKey) {
+        return null;
+    }
+    return {
+        kind: 'group',
+        stableKey,
+        name: String(record.name || ''),
+        ...(record.category === undefined ? {} : { category: record.category }),
+        ...(typeof record.description === 'string'
+            ? { description: record.description }
+            : typeof record.desc === 'string' ? { description: record.desc } : {}),
+        metadata: groupMetadataOf(record),
+    };
+}
+export function hashPortableGroup(manifest) {
+    return hashStable({
+        ...manifest,
+        category: manifest.category ?? null,
+        description: manifest.description ?? '',
+    });
+}
+function diffGroups(desired, target) {
+    return ['name', 'category', 'description', 'metadata']
+        .filter((field) => {
+        const desiredValue = field === 'category'
+            ? desired.category ?? null
+            : field === 'description' ? desired.description ?? '' : desired[field];
+        const targetValue = field === 'category'
+            ? target.category ?? null
+            : field === 'description' ? target.description ?? '' : target[field];
+        return hashStable({ value: desiredValue }) !== hashStable({ value: targetValue });
+    })
+        .sort((left, right) => left.localeCompare(right));
+}
+export function groupManifestPath(workspaceRoot, manifest) {
+    const category = manifest.category == null || manifest.category === ''
+        ? '__no_category__'
+        : sanitizeSegment(manifest.category);
+    return path.join(workspaceRoot, GROUPS_DIRECTORY, category, `${sanitizeSegment(manifest.name)}-${stableKeySuffix(manifest.stableKey)}`, GROUP_MANIFEST_FILE);
+}
+export function readWorkspaceGroups(cwd) {
+    const { workspaceRoot } = requireProjectLayout(cwd, 'Group');
+    return findManifestFiles(path.join(workspaceRoot, GROUPS_DIRECTORY), GROUP_MANIFEST_FILE)
+        .map((manifestPath) => ({
+        manifestPath,
+        manifest: readJsonFile(manifestPath),
+    }));
+}
+async function loadRemoteGroups(client) {
+    const { groups } = await client.listAllGroups();
+    const records = [];
+    for (const summary of groups) {
+        const id = groupIdOf(summary);
+        if (id) {
+            records.push(unwrapData(await client.getGroup(id)));
+        }
+        else {
+            records.push(summary);
+        }
+    }
+    return records;
+}
+function validateManifest(manifest, stableKeyName) {
+    const errors = [];
+    if (!isRecord(manifest)) {
+        return ['manifest must be a JSON object'];
+    }
+    if (manifest.kind !== 'group'
+        || typeof manifest.stableKey !== 'string'
+        || !manifest.stableKey.trim()
+        || typeof manifest.name !== 'string'
+        || !manifest.name.trim()
+        || !isRecord(manifest.metadata)) {
+        errors.push('manifest must contain kind, stableKey, name and metadata');
+    }
+    if (manifest.category !== undefined && manifest.category !== null && typeof manifest.category !== 'string') {
+        errors.push('category must be a string, null, or omitted');
+    }
+    if (manifest.description !== undefined && typeof manifest.description !== 'string') {
+        errors.push('description must be a string or omitted');
+    }
+    if (isRecord(manifest.metadata) && Object.keys(manifest.metadata).some((key) => key.startsWith('__'))) {
+        errors.push('metadata must not contain backend-reserved keys');
+    }
+    const metadataStableKey = isRecord(manifest.metadata)
+        ? readConfiguredResourceMetadataStableKey(manifest, stableKeyName)
+        : null;
+    if (typeof manifest.stableKey === 'string' && metadataStableKey !== manifest.stableKey) {
+        errors.push(`metadata.${stableKeyName} must exactly equal stableKey`);
+    }
+    return errors;
+}
+function emptyPlanCounts() {
+    return {
+        clean: 0,
+        create: 0,
+        'manual-owner': 0,
+        'safe-update': 0,
+        'remote-changed': 0,
+        conflict: 0,
+        'missing-lock': 0,
+        orphan: 0,
+        collision: 0,
+        skipped: 0,
+        delete: 0,
+    };
+}
+function sourceOwnerPolicy(input) {
+    const ownerType = typeof input.record.ownerType === 'string'
+        ? input.record.ownerType.trim().toUpperCase()
+        : '';
+    const ownerId = typeof input.record.ownerId === 'string' ? input.record.ownerId.trim() : '';
+    if (ownerType === 'USER' && ownerId) {
+        return { type: 'manual-user' };
+    }
+    if (ownerType === 'GROUP' && ownerId) {
+        const owner = input.recordsById.get(ownerId);
+        const ownerStableKey = owner ? stableKeyOf(owner, input.stableKeyName) : null;
+        if (ownerStableKey) {
+            return { type: 'group', stableKey: ownerStableKey };
+        }
+        return { type: 'unresolved', reason: `source GROUP owner is missing ${input.stableKeyName}` };
+    }
+    if (ownerType === 'USER') {
+        return { type: 'unresolved', reason: 'source USER owner is missing ownerId' };
+    }
+    if (ownerType === 'GROUP') {
+        return { type: 'unresolved', reason: 'source GROUP owner is missing ownerId' };
+    }
+    return { type: 'unresolved', reason: 'source ownerType is missing or unsupported' };
+}
+function resolveCreateDependencies(input) {
+    const createByKey = new Map(input.items
+        .filter((item) => item.status === 'create' && item.stableKey)
+        .map((item) => [item.stableKey, item]));
+    const manualKeys = new Set(input.items
+        .filter((item) => item.status === 'manual-owner' && item.stableKey)
+        .map((item) => item.stableKey));
+    for (const item of createByKey.values()) {
+        const ownerStableKey = item.ownerStableKey || '';
+        const targetOwners = input.remoteByKey.get(ownerStableKey) || [];
+        if (targetOwners.length === 1) {
+            continue;
+        }
+        if (targetOwners.length > 1) {
+            item.status = 'conflict';
+            item.reason = `owner Group "${ownerStableKey}" has duplicate target stableKey`;
+            input.blockers.push(`Cannot create Group "${item.stableKey}": ${item.reason}.`);
+            continue;
+        }
+        if (manualKeys.has(ownerStableKey)) {
+            item.status = 'manual-owner';
+            item.reason = `owner Group "${ownerStableKey}" must be created manually first`;
+            continue;
+        }
+        if (!createByKey.has(ownerStableKey)) {
+            item.status = 'conflict';
+            item.reason = `owner Group "${ownerStableKey}" is missing from workspace and target`;
+            input.blockers.push(`Cannot create Group "${item.stableKey}": ${item.reason}.`);
+        }
+    }
+    const visiting = new Set();
+    const visited = new Set();
+    const cycleKeys = new Set();
+    const visit = (stableKey, trail) => {
+        if (visiting.has(stableKey)) {
+            const start = trail.indexOf(stableKey);
+            for (const key of trail.slice(start)) {
+                cycleKeys.add(key);
+            }
+            return;
+        }
+        if (visited.has(stableKey)) {
+            return;
+        }
+        visiting.add(stableKey);
+        const ownerStableKey = createByKey.get(stableKey)?.ownerStableKey;
+        if (ownerStableKey && createByKey.get(ownerStableKey)?.status === 'create') {
+            visit(ownerStableKey, [...trail, stableKey]);
+        }
+        visiting.delete(stableKey);
+        visited.add(stableKey);
+    };
+    for (const stableKey of createByKey.keys()) {
+        visit(stableKey, []);
+    }
+    if (cycleKeys.size > 0) {
+        const cycle = [...cycleKeys].sort((left, right) => left.localeCompare(right));
+        input.blockers.push(`Cannot create Groups: circular Group owner dependency: ${cycle.join(', ')}.`);
+        for (const stableKey of cycle) {
+            const item = createByKey.get(stableKey);
+            if (item) {
+                item.status = 'conflict';
+                item.reason = 'circular Group owner dependency';
+            }
+        }
+    }
+}
+function consumeCollisionCandidates(input) {
+    for (const record of input.records) {
+        const stableKey = stableKeyOf(record, input.stableKeyName);
+        if (stableKey) {
+            input.consumedRemoteKeys.add(stableKey);
+        }
+        else {
+            input.consumedUnmanaged.add(record);
+        }
+    }
+}
+export async function buildGroupsPlan(input) {
+    const localEntries = readWorkspaceGroups(input.cwd);
+    const records = await loadRemoteGroups(input.client);
+    const { projectRoot } = requireProjectLayout(input.cwd, 'Group');
+    const lock = readComponentLock(projectRoot);
+    const lockByStableKey = new Map(Object.values(lock.groups)
+        .map((entry) => [entry.stableKey, entry]));
+    const blockers = [];
+    const warnings = new Set();
+    const items = [];
+    const localByKey = new Map();
+    for (const entry of localEntries) {
+        const errors = validateManifest(entry.manifest, input.stableKeyName);
+        if (errors.length > 0) {
+            blockers.push(`Invalid Group manifest ${path.relative(projectRoot, entry.manifestPath)}: ${errors.join('; ')}.`);
+            const invalidName = isRecord(entry.manifest) && typeof entry.manifest.name === 'string' && entry.manifest.name
+                ? entry.manifest.name
+                : path.basename(path.dirname(entry.manifestPath));
+            items.push({ status: 'conflict', name: invalidName, reason: 'invalid Group manifest' });
+            continue;
+        }
+        const key = entry.manifest.stableKey;
+        localByKey.set(key, [...(localByKey.get(key) || []), entry]);
+    }
+    const remoteByKey = new Map();
+    const unmanaged = [];
+    for (const record of records) {
+        const manifest = groupManifestFromRecord(record, input.stableKeyName);
+        if (!manifest) {
+            unmanaged.push(record);
+            continue;
+        }
+        remoteByKey.set(manifest.stableKey, [...(remoteByKey.get(manifest.stableKey) || []), {
+                record,
+                manifest,
+                hash: hashPortableGroup(manifest),
+            }]);
+    }
+    const consumedRemoteKeys = new Set();
+    const consumedUnmanaged = new Set();
+    for (const [stableKey, entries] of localByKey) {
+        if (entries.length > 1) {
+            const desired = entries[0].manifest;
+            blockers.push(`Duplicate desired Group stableKey "${stableKey}".`);
+            items.push({ status: 'collision', stableKey, name: desired.name, reason: 'duplicate desired stableKey' });
+            continue;
+        }
+        const desired = entries[0].manifest;
+        const desiredHash = hashPortableGroup(desired);
+        const matches = remoteByKey.get(desired.stableKey) || [];
+        if (matches.length > 1) {
+            blockers.push(`Duplicate target Group stableKey "${desired.stableKey}".`);
+            consumedRemoteKeys.add(desired.stableKey);
+            items.push({ status: 'collision', stableKey: desired.stableKey, name: desired.name, reason: 'duplicate target stableKey', desiredHash });
+            continue;
+        }
+        const identityCollisions = records.filter((record) => (groupHint(record) === groupHint(desired)
+            && stableKeyOf(record, input.stableKeyName) !== desired.stableKey));
+        if (identityCollisions.length > 0) {
+            consumeCollisionCandidates({
+                records: identityCollisions,
+                stableKeyName: input.stableKeyName,
+                consumedRemoteKeys,
+                consumedUnmanaged,
+            });
+            const reason = `target Group matching category/name does not have exact ${input.stableKeyName}`;
+            blockers.push(`Cannot synchronize "${desired.stableKey}": ${reason}.`);
+            items.push({ status: 'collision', stableKey: desired.stableKey, name: desired.name, reason, desiredHash });
+            continue;
+        }
+        const lockEntry = lockByStableKey.get(desired.stableKey);
+        if (matches.length === 0) {
+            const owner = lockEntry?.owner;
+            if (!owner) {
+                blockers.push(`Cannot create Group "${desired.stableKey}": missing portable source owner policy; pull from source first.`);
+                items.push({
+                    status: 'missing-lock',
+                    stableKey: desired.stableKey,
+                    name: desired.name,
+                    desiredHash,
+                    reason: 'missing portable source owner policy',
+                });
+            }
+            else if (owner.type === 'manual-user') {
+                items.push({
+                    status: 'manual-owner',
+                    stableKey: desired.stableKey,
+                    name: desired.name,
+                    desiredHash,
+                    reason: 'source USER owner requires manual target creation with the exact stableKey',
+                });
+            }
+            else if (owner.type === 'unresolved') {
+                blockers.push(`Cannot create Group "${desired.stableKey}": ${owner.reason}.`);
+                items.push({
+                    status: 'conflict',
+                    stableKey: desired.stableKey,
+                    name: desired.name,
+                    desiredHash,
+                    reason: owner.reason,
+                });
+            }
+            else {
+                items.push({
+                    status: 'create',
+                    stableKey: desired.stableKey,
+                    name: desired.name,
+                    desiredHash,
+                    ownerStableKey: owner.stableKey,
+                });
+            }
+            continue;
+        }
+        consumedRemoteKeys.add(desired.stableKey);
+        const target = matches[0];
+        if (lockEntry?.owner?.type === 'manual-user') {
+            const hasTargetUserOwner = String(target.record.ownerType || '').toUpperCase() === 'USER'
+                && typeof target.record.ownerId === 'string'
+                && target.record.ownerId.length > 0;
+            if (!hasTargetUserOwner) {
+                items.push({
+                    status: 'manual-owner',
+                    stableKey: desired.stableKey,
+                    name: desired.name,
+                    desiredHash,
+                    currentHash: target.hash,
+                    reason: 'target Group requires a target-local USER owner',
+                });
+                continue;
+            }
+        }
+        let ownerChanged = false;
+        let ownerStableKey;
+        if (lockEntry?.owner?.type === 'group') {
+            ownerStableKey = lockEntry.owner.stableKey;
+            const ownerMatches = remoteByKey.get(ownerStableKey) || [];
+            if (ownerMatches.length > 1) {
+                const reason = `owner Group "${ownerStableKey}" has duplicate target stableKey`;
+                blockers.push(`Cannot synchronize Group "${desired.stableKey}": ${reason}.`);
+                items.push({ status: 'conflict', stableKey: desired.stableKey, name: desired.name, desiredHash, reason, ownerStableKey });
+                continue;
+            }
+            if (ownerMatches.length === 0 && !localByKey.has(ownerStableKey)) {
+                const reason = `owner Group "${ownerStableKey}" is missing from workspace and target`;
+                blockers.push(`Cannot synchronize Group "${desired.stableKey}": ${reason}.`);
+                items.push({ status: 'conflict', stableKey: desired.stableKey, name: desired.name, desiredHash, reason, ownerStableKey });
+                continue;
+            }
+            const targetOwnerId = ownerMatches.length === 1 ? groupIdOf(ownerMatches[0].record) : '';
+            ownerChanged = String(target.record.ownerType || '').toUpperCase() !== 'GROUP'
+                || !targetOwnerId
+                || target.record.ownerId !== targetOwnerId;
+        }
+        for (const warning of targetLocalWarnings(desired.stableKey, target.record, lockEntry?.owner?.type !== 'group')) {
+            warnings.add(warning);
+        }
+        const changedFields = [
+            ...diffGroups(desired, target.manifest),
+            ...(ownerChanged ? ['owner'] : []),
+        ].sort((left, right) => left.localeCompare(right));
+        const common = {
+            stableKey: desired.stableKey,
+            name: desired.name,
+            desiredHash,
+            currentHash: target.hash,
+            ...(ownerStableKey ? { ownerStableKey } : {}),
+            ...(changedFields.length > 0 ? { changedFields } : {}),
+        };
+        if (desiredHash === target.hash && !ownerChanged) {
+            items.push({ status: 'clean', ...common });
+            continue;
+        }
+        if (desiredHash === target.hash && ownerChanged) {
+            items.push({ status: 'safe-update', ...common, reason: 'target GROUP owner differs from source owner Stable Key' });
+            continue;
+        }
+        const baselineHash = lockEntry?.environments[input.envName]?.remoteHash;
+        if (!baselineHash) {
+            items.push({ status: 'missing-lock', ...common, reason: `missing ${input.envName} lock baseline` });
+        }
+        else if (target.hash === baselineHash) {
+            items.push({ status: 'safe-update', ...common, baselineHash });
+        }
+        else if (desiredHash === baselineHash) {
+            items.push({ status: 'remote-changed', ...common, baselineHash, reason: 'target changed since lock baseline' });
+        }
+        else {
+            items.push({ status: 'conflict', ...common, baselineHash, reason: 'desired and target changed since lock baseline' });
+        }
+    }
+    resolveCreateDependencies({ items, remoteByKey, blockers });
+    for (const [stableKey, matches] of remoteByKey) {
+        if (consumedRemoteKeys.has(stableKey) || localByKey.has(stableKey)) {
+            continue;
+        }
+        if (matches.length > 1) {
+            blockers.push(`Duplicate target Group stableKey "${stableKey}".`);
+            items.push({ status: 'collision', stableKey, name: matches[0].manifest.name, reason: 'duplicate target stableKey' });
+            continue;
+        }
+        const target = matches[0];
+        items.push({
+            status: 'orphan',
+            stableKey: target.manifest.stableKey,
+            name: target.manifest.name,
+            currentHash: target.hash,
+            reason: 'target-only Group',
+        });
+    }
+    for (const record of unmanaged) {
+        if (consumedUnmanaged.has(record)) {
+            continue;
+        }
+        items.push({
+            status: 'skipped',
+            name: String(record.name || groupIdOf(record) || 'unknown'),
+            reason: `missing ${input.stableKeyName}; unmanaged`,
+        });
+    }
+    const rank = {
+        create: 0,
+        'manual-owner': 1,
+        'safe-update': 2,
+        'remote-changed': 3,
+        conflict: 4,
+        'missing-lock': 5,
+        clean: 6,
+        orphan: 7,
+        collision: 8,
+        skipped: 9,
+        delete: 10,
+    };
+    items.sort((left, right) => rank[left.status] - rank[right.status]
+        || (left.stableKey || left.name).localeCompare(right.stableKey || right.name));
+    const counts = emptyPlanCounts();
+    for (const item of items) {
+        counts[item.status] += 1;
+    }
+    return {
+        resourceType: 'group',
+        env: input.envName,
+        counts,
+        blockers: [...new Set(blockers)].sort((left, right) => left.localeCompare(right)),
+        items,
+        warnings: [...warnings].sort((left, right) => left.localeCompare(right)),
+        exclusions: [
+            'members/users are always skipped',
+            'USER owners, leader, avatar, UUID and version are target-local and never persisted',
+            'GROUP owner dependencies are persisted only as stableKey references',
+        ],
+    };
+}
+export async function pullGroupsToWorkspace(input) {
+    const { projectRoot, workspaceRoot } = requireProjectLayout(input.cwd, 'Group');
+    const records = await loadRemoteGroups(input.client);
+    const skipped = [];
+    const notices = [];
+    const managed = [];
+    const stableKeys = new Set();
+    const recordsById = new Map(records
+        .map((record) => [groupIdOf(record), record])
+        .filter(([id]) => Boolean(id)));
+    for (const record of records) {
+        const manifest = groupManifestFromRecord(record, input.stableKeyName);
+        if (!manifest) {
+            const name = String(record.name || groupIdOf(record) || 'unknown');
+            skipped.push({ name, targetPath: name, reason: `missing ${input.stableKeyName}; unmanaged` });
+            continue;
+        }
+        const errors = validateManifest(manifest, input.stableKeyName);
+        if (errors.length > 0) {
+            throw new Error(`Invalid managed Group "${manifest.stableKey}" on ${input.envName}: ${errors.join('; ')}; no files were changed.`);
+        }
+        if (stableKeys.has(manifest.stableKey)) {
+            throw new Error(`Duplicate Group stableKey "${manifest.stableKey}" on ${input.envName}; no files were changed.`);
+        }
+        stableKeys.add(manifest.stableKey);
+        const memberCount = groupMemberCount(record);
+        if (memberCount > 0) {
+            notices.push({ stableKey: manifest.stableKey, reason: `source members excluded: ${memberCount}` });
+        }
+        const owner = sourceOwnerPolicy({ record, recordsById, stableKeyName: input.stableKeyName });
+        if (owner.type === 'manual-user') {
+            notices.push({ stableKey: manifest.stableKey, reason: 'source USER owner excluded; target creation is manual' });
+        }
+        else if (owner.type === 'unresolved') {
+            notices.push({ stableKey: manifest.stableKey, reason: `${owner.reason}; automatic create is blocked` });
+        }
+        managed.push({ manifest, owner });
+    }
+    managed.sort((left, right) => left.manifest.stableKey.localeCompare(right.manifest.stableKey));
+    const lock = readComponentLock(projectRoot);
+    const existingByStableKey = new Map();
+    for (const entry of readWorkspaceGroups(input.cwd)) {
+        const errors = validateManifest(entry.manifest, input.stableKeyName);
+        if (errors.length > 0) {
+            throw new Error(`Cannot pull over invalid Group manifest ${path.relative(projectRoot, entry.manifestPath)}: ${errors.join('; ')}.`);
+        }
+        if (existingByStableKey.has(entry.manifest.stableKey)) {
+            throw new Error(`Duplicate local Group stableKey "${entry.manifest.stableKey}"; no files were changed.`);
+        }
+        existingByStableKey.set(entry.manifest.stableKey, entry);
+    }
+    const writes = [];
+    const outputPaths = new Set();
+    for (const managedGroup of managed) {
+        const { manifest, owner } = managedGroup;
+        const hash = hashPortableGroup(manifest);
+        const existing = existingByStableKey.get(manifest.stableKey);
+        if (existing && !input.force) {
+            const localHash = hashPortableGroup(existing.manifest);
+            const lockEntry = lock.groups[manifest.stableKey];
+            if (localHash !== hash && (!lockEntry || localHash !== lockEntry.sourceHash)) {
+                throw new Error(`Cannot pull Group "${manifest.stableKey}": local manifest changed since the lock baseline. Re-run with --force.`);
+            }
+        }
+        const filePath = groupManifestPath(workspaceRoot, manifest);
+        if (outputPaths.has(filePath)) {
+            throw new Error(`Multiple Groups resolve to workspace path "${path.relative(projectRoot, filePath)}"; no files were changed.`);
+        }
+        outputPaths.add(filePath);
+        writes.push({
+            filePath,
+            ...(existing && existing.manifestPath !== filePath ? { previousPath: existing.manifestPath } : {}),
+            manifest,
+            hash,
+            owner,
+        });
+    }
+    const groupsRoot = path.join(workspaceRoot, GROUPS_DIRECTORY);
+    let lockChanged = false;
+    for (const write of writes) {
+        writePulledManifest({
+            filePath: write.filePath,
+            manifest: write.manifest,
+            previousPath: write.previousPath,
+            root: groupsRoot,
+            force: input.force,
+        });
+        const previous = lock.groups[write.manifest.stableKey];
+        const previousBaseline = previous?.environments[input.envName];
+        const entry = {
+            stableKey: write.manifest.stableKey,
+            path: toPortableRelativePath(projectRoot, write.filePath),
+            sourceHash: write.hash,
+            owner: write.owner,
+            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.groups[write.manifest.stableKey] = entry;
+    }
+    if (lockChanged) {
+        writeComponentLock(projectRoot, lock);
+    }
+    return {
+        pulled: writes.map((write) => ({
+            manifest: write.manifest,
+            targetPath: localTargetPath(input.cwd, write.filePath),
+        })),
+        skipped,
+        notices,
+    };
+}
+function buildCreatePayload(manifest, ownerId) {
+    return {
+        name: manifest.name,
+        ...(manifest.category === undefined ? {} : { category: manifest.category }),
+        ...(manifest.description === undefined ? {} : { desc: manifest.description }),
+        metadata: sanitizeUserMetadata(manifest.metadata),
+        ownerType: 'GROUP',
+        ownerId,
+        members: [],
+    };
+}
+function buildUpdatePayload(manifest, target, ownerId) {
+    if (!Number.isInteger(target.version)) {
+        throw new Error('target Group version is required');
+    }
+    return {
+        name: manifest.name,
+        ...(manifest.category === undefined && target.category === undefined
+            ? {}
+            : { category: manifest.category ?? null }),
+        ...(manifest.description === undefined && target.description === undefined && target.desc === undefined
+            ? {}
+            : { desc: manifest.description ?? '' }),
+        metadata: sanitizeUserMetadata(manifest.metadata),
+        version: target.version,
+        ...(ownerId ? { ownerType: 'GROUP', ownerId } : {}),
+    };
+}
+function updateEnvironmentBaseline(input) {
+    const { projectRoot } = requireProjectLayout(input.cwd, 'Group');
+    const lock = readComponentLock(projectRoot);
+    const localMatches = readWorkspaceGroups(input.cwd)
+        .filter(({ manifest }) => manifest.stableKey === input.stableKey);
+    if (localMatches.length !== 1) {
+        throw new Error(`Cannot update lock baseline for "${input.stableKey}": expected one local Group manifest, found ${localMatches.length}.`);
+    }
+    const local = localMatches[0];
+    const entry = lock.groups[input.stableKey];
+    const existingBaseline = entry?.environments[input.envName];
+    const nextEntry = {
+        stableKey: local.manifest.stableKey,
+        path: toPortableRelativePath(projectRoot, local.manifestPath),
+        sourceHash: hashPortableGroup(local.manifest),
+        ...(entry?.owner ? { owner: entry.owner } : {}),
+        environments: {
+            ...(entry?.environments || {}),
+            [input.envName]: existingBaseline?.remoteHash === input.remoteHash
+                ? existingBaseline
+                : { remoteHash: input.remoteHash, syncedAt: new Date().toISOString() },
+        },
+    };
+    if (entry && hashStable(entry) === hashStable(nextEntry)) {
+        return;
+    }
+    lock.groups[input.stableKey] = nextEntry;
+    writeComponentLock(projectRoot, lock);
+}
+function localManifestByStableKey(cwd) {
+    return new Map(readWorkspaceGroups(cwd).map((entry) => [entry.manifest.stableKey, entry]));
+}
+async function liveTargetByStableKey(client, stableKeyName, stableKey) {
+    const records = await loadRemoteGroups(client);
+    return records.filter((record) => stableKeyOf(record, stableKeyName) === stableKey);
+}
+async function assertCreateStillSafe(client, stableKeyName, desired) {
+    const records = await loadRemoteGroups(client);
+    for (const record of records) {
+        const key = stableKeyOf(record, stableKeyName);
+        if (key === desired.stableKey) {
+            throw new Error('matching stableKey appeared after planning');
+        }
+        if (groupHint(record) === groupHint(desired) && key !== desired.stableKey) {
+            throw new Error(`target Group matching category/name appeared without exact ${stableKeyName} after planning`);
+        }
+    }
+}
+function resultTargetPath(cwd, localByKey, item) {
+    const local = item.stableKey ? localByKey.get(item.stableKey) : undefined;
+    return local ? localTargetPath(cwd, local.manifestPath) : item.stableKey || item.name;
+}
+export async function pushGroups(input) {
+    const plan = await buildGroupsPlan(input);
+    if (plan.blockers.length > 0) {
+        throw new Error(`Group 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(`Group push blocked by ${statuses}; review the plan and re-run with --force only to adopt or overwrite reviewed content drift.`);
+    }
+    if (plan.items.some((item) => item.status === 'collision')) {
+        throw new Error('Group push blocked by stableKey collision; --force cannot bypass identity ambiguity.');
+    }
+    const localByKey = localManifestByStableKey(input.cwd);
+    const results = [];
+    for (const item of plan.items.filter((candidate) => candidate.status === 'clean')) {
+        if (!item.stableKey || !item.currentHash) {
+            continue;
+        }
+        updateEnvironmentBaseline({
+            cwd: input.cwd,
+            envName: input.envName,
+            stableKey: item.stableKey,
+            remoteHash: item.currentHash,
+        });
+        results.push({
+            stableKey: item.stableKey,
+            action: 'noop',
+            status: 'skipped',
+            targetPath: resultTargetPath(input.cwd, localByKey, item),
+            reason: 'no local changes',
+        });
+    }
+    const pendingCreates = new Map(plan.items
+        .filter((item) => item.status === 'create' && item.stableKey)
+        .map((item) => [item.stableKey, item]));
+    while (pendingCreates.size > 0) {
+        let progressed = false;
+        for (const [stableKey, item] of [...pendingCreates.entries()]
+            .sort(([left], [right]) => left.localeCompare(right))) {
+            const ownerMatches = await liveTargetByStableKey(input.client, input.stableKeyName, item.ownerStableKey || '');
+            if (ownerMatches.length === 0) {
+                continue;
+            }
+            pendingCreates.delete(stableKey);
+            progressed = true;
+            const local = localByKey.get(stableKey);
+            const targetPath = resultTargetPath(input.cwd, localByKey, item);
+            if (!local) {
+                results.push({ stableKey, action: 'create', status: 'failed', targetPath, error: 'desired manifest disappeared after planning' });
+                continue;
+            }
+            if (ownerMatches.length !== 1) {
+                results.push({ stableKey, action: 'create', status: 'failed', targetPath, error: `expected one target owner Group, found ${ownerMatches.length}` });
+                continue;
+            }
+            const ownerId = groupIdOf(ownerMatches[0]);
+            if (!ownerId) {
+                results.push({ stableKey, action: 'create', status: 'failed', targetPath, error: 'target owner Group did not include groupId' });
+                continue;
+            }
+            const liveDesiredHash = hashPortableGroup(local.manifest);
+            if (liveDesiredHash !== item.desiredHash) {
+                results.push({ stableKey, action: 'create', status: 'failed', targetPath, error: 'desired manifest changed after planning' });
+                continue;
+            }
+            try {
+                await assertCreateStillSafe(input.client, input.stableKeyName, local.manifest);
+                const created = unwrapData(await input.client.createGroup(buildCreatePayload(local.manifest, ownerId)));
+                const createdId = groupIdOf(created);
+                if (!createdId) {
+                    throw new Error('create response did not include groupId');
+                }
+                const verified = unwrapData(await input.client.getGroup(createdId));
+                const verifiedManifest = groupManifestFromRecord(verified, input.stableKeyName);
+                if (!verifiedManifest || hashPortableGroup(verifiedManifest) !== liveDesiredHash) {
+                    throw new Error('created Group did not match desired portable hash');
+                }
+                if (String(verified.ownerType || '').toUpperCase() !== 'GROUP' || verified.ownerId !== ownerId) {
+                    throw new Error('created Group did not retain the resolved target owner');
+                }
+                updateEnvironmentBaseline({ cwd: input.cwd, envName: input.envName, stableKey, remoteHash: liveDesiredHash });
+                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) });
+            }
+        }
+        if (!progressed) {
+            for (const [stableKey, item] of pendingCreates) {
+                results.push({
+                    stableKey,
+                    action: 'create',
+                    status: 'failed',
+                    targetPath: resultTargetPath(input.cwd, localByKey, item),
+                    error: `target owner Group "${item.ownerStableKey || 'unknown'}" is unavailable`,
+                });
+            }
+            pendingCreates.clear();
+        }
+    }
+    const updates = plan.items
+        .filter((item) => ['safe-update', 'missing-lock', 'remote-changed', 'conflict'].includes(item.status));
+    for (const item of updates) {
+        const stableKey = item.stableKey || '';
+        const local = localByKey.get(stableKey);
+        const targetPath = resultTargetPath(input.cwd, localByKey, item);
+        if (!local) {
+            results.push({ stableKey, action: 'update', status: 'failed', targetPath, error: 'desired manifest disappeared after planning' });
+            continue;
+        }
+        const liveDesiredHash = hashPortableGroup(local.manifest);
+        if (liveDesiredHash !== item.desiredHash) {
+            results.push({ stableKey, action: 'update', status: 'failed', targetPath, error: 'desired manifest changed after planning' });
+            continue;
+        }
+        try {
+            const matches = await liveTargetByStableKey(input.client, input.stableKeyName, stableKey);
+            if (matches.length !== 1) {
+                throw new Error(`expected one live target match, found ${matches.length}`);
+            }
+            const targetId = groupIdOf(matches[0]);
+            if (!targetId) {
+                throw new Error('live target did not include groupId');
+            }
+            const target = unwrapData(await input.client.getGroup(targetId));
+            const targetManifest = groupManifestFromRecord(target, input.stableKeyName);
+            if (!targetManifest || hashPortableGroup(targetManifest) !== item.currentHash) {
+                throw new Error('target changed after planning');
+            }
+            let desiredOwnerId;
+            if (item.ownerStableKey) {
+                const ownerMatches = await liveTargetByStableKey(input.client, input.stableKeyName, item.ownerStableKey);
+                if (ownerMatches.length !== 1) {
+                    throw new Error(`expected one live target owner Group, found ${ownerMatches.length}`);
+                }
+                desiredOwnerId = groupIdOf(ownerMatches[0]);
+                if (!desiredOwnerId) {
+                    throw new Error('live target owner Group did not include groupId');
+                }
+            }
+            await input.client.updateGroup(targetId, buildUpdatePayload(local.manifest, target, desiredOwnerId));
+            const verified = unwrapData(await input.client.getGroup(targetId));
+            const verifiedManifest = groupManifestFromRecord(verified, input.stableKeyName);
+            if (!verifiedManifest || hashPortableGroup(verifiedManifest) !== liveDesiredHash) {
+                throw new Error('updated Group did not match desired portable hash');
+            }
+            if (desiredOwnerId && (String(verified.ownerType || '').toUpperCase() !== 'GROUP'
+                || verified.ownerId !== desiredOwnerId)) {
+                throw new Error('updated Group did not retain the resolved target owner');
+            }
+            updateEnvironmentBaseline({ cwd: input.cwd, envName: input.envName, stableKey, remoteHash: liveDesiredHash });
+            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 === 'manual-owner')) {
+        results.push({
+            stableKey: item.stableKey || item.name,
+            action: 'manual-owner',
+            status: 'skipped',
+            targetPath: resultTargetPath(input.cwd, localByKey, item),
+            reason: item.reason || 'manual target owner required',
+        });
+    }
+    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 };
+}