@revoengine/cli 1.0.9 → 1.0.11

package/dist/src/resource-syncs/role-group-sync.d.ts

@@ -0,0 +1,83 @@
+import type { RoleGroupRecord } from '../types.ts';
+import type { RevoClient } from '../client.ts';
+export declare const ROLE_GROUPS_DIRECTORY = "RoleGroups";
+export declare const ROLE_GROUP_MANIFEST_FILE = "role-group.json";
+export type RoleGroupManifest = {
+    kind: 'role-group';
+    stableKey: string;
+    name: string;
+    category?: string | null;
+    description?: string;
+    metadata: Record<string, unknown>;
+    roles: string[];
+};
+export type RoleGroupPullResult = {
+    pulled: Array<{
+        manifest: RoleGroupManifest;
+        targetPath: string;
+    }>;
+    skipped: Array<{
+        name: string;
+        targetPath: string;
+        reason: string;
+    }>;
+};
+export type RoleGroupPlanStatus = 'clean' | 'create' | 'safe-update' | 'remote-changed' | 'conflict' | 'missing-lock' | 'orphan' | 'collision' | 'skipped' | 'delete';
+export type RoleGroupPlanItem = {
+    status: RoleGroupPlanStatus;
+    stableKey?: string;
+    name: string;
+    reason?: string;
+    changedFields?: string[];
+    rolesToAdd?: string[];
+    rolesToRemove?: string[];
+    desiredHash?: string;
+    currentHash?: string;
+    baselineHash?: string;
+};
+export type RoleGroupsPlan = {
+    resourceType: 'role-group';
+    env: string;
+    counts: Record<RoleGroupPlanStatus, number>;
+    blockers: string[];
+    items: RoleGroupPlanItem[];
+    exclusions: string[];
+};
+export type RoleGroupPushResult = {
+    stableKey: string;
+    action: 'create' | 'update' | 'noop' | 'orphan' | 'skipped';
+    status: 'deployed' | 'skipped' | 'failed';
+    targetPath: string;
+    reason?: string;
+    error?: string;
+};
+export declare function roleGroupManifestFromRecord(record: RoleGroupRecord, stableKeyName: string): RoleGroupManifest | null;
+export declare function hashPortableRoleGroup(manifest: RoleGroupManifest): string;
+export declare function roleGroupManifestPath(workspaceRoot: string, manifest: RoleGroupManifest): string;
+export declare function readWorkspaceRoleGroups(cwd: string): {
+    manifestPath: string;
+    manifest: RoleGroupManifest;
+}[];
+export declare function buildRoleGroupsPlan(input: {
+    client: RevoClient;
+    cwd: string;
+    envName: string;
+    stableKeyName: string;
+}): Promise<RoleGroupsPlan>;
+export declare function pullRoleGroupsToWorkspace(input: {
+    client: RevoClient;
+    cwd: string;
+    envName: string;
+    stableKeyName: string;
+    force?: boolean;
+}): Promise<RoleGroupPullResult>;
+export declare function pushRoleGroups(input: {
+    client: RevoClient;
+    cwd: string;
+    envName: string;
+    stableKeyName: string;
+    force?: boolean;
+}): Promise<{
+    plan: RoleGroupsPlan;
+    results: RoleGroupPushResult[];
+}>;

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

@@ -0,0 +1,597 @@
+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 ROLE_GROUPS_DIRECTORY = 'RoleGroups';
+export const ROLE_GROUP_MANIFEST_FILE = 'role-group.json';
+function roleGroupIdOf(record) {
+    return String(record.roleGroupId || record.id || '');
+}
+function roleKeyOf(value) {
+    if (typeof value === 'string')
+        return value.trim();
+    if (!isRecord(value))
+        return '';
+    for (const key of ['roleKey', 'key', 'name', 'code']) {
+        if (typeof value[key] === 'string' && value[key].trim())
+            return value[key].trim();
+    }
+    return '';
+}
+function roleKeysOf(record) {
+    return [...new Set((record.roles || []).map(roleKeyOf).filter(Boolean))]
+        .sort((left, right) => left.localeCompare(right));
+}
+export function roleGroupManifestFromRecord(record, stableKeyName) {
+    const stableKey = readConfiguredResourceMetadataStableKey(record, stableKeyName);
+    if (!stableKey)
+        return null;
+    return {
+        kind: 'role-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: sanitizeUserMetadata(record.metadata),
+        roles: roleKeysOf(record),
+    };
+}
+export function hashPortableRoleGroup(manifest) {
+    return hashStable({
+        ...manifest,
+        category: manifest.category ?? null,
+        description: manifest.description ?? '',
+    });
+}
+function roleGroupHint(value) {
+    const category = typeof value.category === 'string' && value.category.trim() ? value.category : '__no_category__';
+    return normalizeStableKeyValue(`${category}/${String(value.name || '')}`);
+}
+function diffRoleGroups(desired, target) {
+    const changedFields = ['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));
+    const desiredRoles = new Set(desired.roles);
+    const targetRoles = new Set(target.roles);
+    return {
+        changedFields,
+        rolesToAdd: desired.roles.filter((roleKey) => !targetRoles.has(roleKey)),
+        rolesToRemove: target.roles.filter((roleKey) => !desiredRoles.has(roleKey)),
+    };
+}
+export function roleGroupManifestPath(workspaceRoot, manifest) {
+    const category = manifest.category == null || manifest.category === '' ? '__no_category__' : sanitizeSegment(manifest.category);
+    return path.join(workspaceRoot, ROLE_GROUPS_DIRECTORY, category, `${sanitizeSegment(manifest.name)}-${stableKeySuffix(manifest.stableKey)}`, ROLE_GROUP_MANIFEST_FILE);
+}
+export function readWorkspaceRoleGroups(cwd) {
+    const { workspaceRoot } = requireProjectLayout(cwd, 'Role-group');
+    return findManifestFiles(path.join(workspaceRoot, ROLE_GROUPS_DIRECTORY), ROLE_GROUP_MANIFEST_FILE)
+        .map((manifestPath) => ({
+        manifestPath,
+        manifest: readJsonFile(manifestPath),
+    }));
+}
+async function loadRemoteRoleGroups(client) {
+    const { roleGroups } = await client.listAllRoleGroups();
+    const records = [];
+    for (const summary of roleGroups) {
+        const id = roleGroupIdOf(summary);
+        records.push(id ? unwrapData(await client.getRoleGroup(id)) : summary);
+    }
+    return records;
+}
+function validateManifest(manifest, stableKeyName) {
+    const errors = [];
+    if (!isRecord(manifest)) {
+        return ['manifest must be a JSON object'];
+    }
+    if (manifest.kind !== 'role-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');
+    }
+    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`);
+    }
+    if (!Array.isArray(manifest.roles)
+        || manifest.roles.some((roleKey) => typeof roleKey !== 'string' || !roleKey.trim())) {
+        errors.push('roles must contain only non-empty strings');
+    }
+    else {
+        const roles = manifest.roles;
+        if (new Set(roles).size !== roles.length)
+            errors.push('roles must not contain duplicates');
+        if (roles.some((roleKey, index) => index > 0 && roles[index - 1].localeCompare(roleKey) > 0)) {
+            errors.push('roles must be sorted');
+        }
+    }
+    return errors;
+}
+function emptyPlanCounts() {
+    return {
+        clean: 0,
+        create: 0,
+        'safe-update': 0,
+        'remote-changed': 0,
+        conflict: 0,
+        'missing-lock': 0,
+        orphan: 0,
+        collision: 0,
+        skipped: 0,
+        delete: 0,
+    };
+}
+export async function buildRoleGroupsPlan(input) {
+    const localEntries = readWorkspaceRoleGroups(input.cwd);
+    const records = await loadRemoteRoleGroups(input.client);
+    const { projectRoot } = requireProjectLayout(input.cwd, 'Role-group');
+    const lock = readComponentLock(projectRoot);
+    const lockByNormalizedKey = new Map(Object.values(lock.roleGroups)
+        .map((entry) => [normalizeStableKeyValue(entry.stableKey), entry]));
+    const blockers = [];
+    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 role-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 role-group manifest',
+            });
+            continue;
+        }
+        const normalized = normalizeStableKeyValue(entry.manifest.stableKey || '');
+        localByKey.set(normalized, [...(localByKey.get(normalized) || []), entry]);
+    }
+    const remoteByKey = new Map();
+    const unmanaged = [];
+    for (const record of records) {
+        const manifest = roleGroupManifestFromRecord(record, input.stableKeyName);
+        if (!manifest) {
+            unmanaged.push(record);
+            continue;
+        }
+        const normalized = normalizeStableKeyValue(manifest.stableKey);
+        remoteByKey.set(normalized, [...(remoteByKey.get(normalized) || []), {
+                record,
+                manifest,
+                hash: hashPortableRoleGroup(manifest),
+            }]);
+    }
+    const validLocalEntries = [...localByKey.values()].flat();
+    const roleKeys = validLocalEntries.flatMap((entry) => entry.manifest.roles);
+    const targetRoleKeys = new Set(roleKeys.length > 0
+        ? (await input.client.listAllSystemRoles()).map(roleKeyOf).filter(Boolean)
+        : []);
+    const unknownRoleKeys = [...new Set(roleKeys.filter((roleKey) => !targetRoleKeys.has(roleKey)))].sort();
+    if (unknownRoleKeys.length > 0)
+        blockers.push(`Unknown target system role key(s): ${unknownRoleKeys.join(', ')}.`);
+    const consumedRemoteKeys = new Set();
+    const consumedUnmanaged = new Set();
+    for (const [normalized, entries] of localByKey) {
+        if (entries.length > 1) {
+            const stableKey = entries[0].manifest.stableKey;
+            blockers.push(`Duplicate desired role-group stableKey "${stableKey}".`);
+            items.push({ status: 'collision', stableKey, name: entries[0].manifest.name, reason: 'duplicate desired stableKey' });
+            continue;
+        }
+        const desired = entries[0].manifest;
+        const desiredHash = hashPortableRoleGroup(desired);
+        const matches = remoteByKey.get(normalized) || [];
+        if (matches.length > 1) {
+            blockers.push(`Duplicate target role-group stableKey "${desired.stableKey}".`);
+            consumedRemoteKeys.add(normalized);
+            items.push({ status: 'collision', stableKey: desired.stableKey, name: desired.name, reason: 'duplicate target stableKey', desiredHash });
+            continue;
+        }
+        if (unknownRoleKeys.some((roleKey) => desired.roles.includes(roleKey))) {
+            items.push({ status: 'conflict', stableKey: desired.stableKey, name: desired.name, reason: 'unknown target system role key', desiredHash });
+            continue;
+        }
+        if (matches.length === 0) {
+            const hinted = unmanaged.filter((record) => roleGroupHint(record) === roleGroupHint(desired));
+            if (hinted.length > 0) {
+                hinted.forEach((record) => consumedUnmanaged.add(record));
+                const reason = `target role-group matching category/name is missing ${input.stableKeyName}`;
+                blockers.push(`Cannot create "${desired.stableKey}": ${reason}.`);
+                items.push({ status: 'conflict', stableKey: desired.stableKey, name: desired.name, reason, desiredHash });
+            }
+            else {
+                items.push({ status: 'create', stableKey: desired.stableKey, name: desired.name, desiredHash });
+            }
+            continue;
+        }
+        consumedRemoteKeys.add(normalized);
+        const target = matches[0];
+        const diff = diffRoleGroups(desired, target.manifest);
+        const common = {
+            stableKey: desired.stableKey,
+            name: desired.name,
+            desiredHash,
+            currentHash: target.hash,
+            ...(diff.changedFields.length > 0 ? { changedFields: diff.changedFields } : {}),
+            ...(diff.rolesToAdd.length > 0 ? { rolesToAdd: diff.rolesToAdd } : {}),
+            ...(diff.rolesToRemove.length > 0 ? { rolesToRemove: diff.rolesToRemove } : {}),
+        };
+        if (desiredHash === target.hash) {
+            items.push({ status: 'clean', ...common });
+            continue;
+        }
+        const baselineHash = lockByNormalizedKey.get(normalized)?.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' });
+        }
+    }
+    for (const [normalized, matches] of remoteByKey) {
+        if (consumedRemoteKeys.has(normalized) || localByKey.has(normalized))
+            continue;
+        if (matches.length > 1) {
+            const stableKey = matches[0].manifest.stableKey;
+            blockers.push(`Duplicate target role-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 role-group' });
+    }
+    for (const record of unmanaged) {
+        if (consumedUnmanaged.has(record))
+            continue;
+        items.push({ status: 'skipped', name: String(record.name || 'unknown'), reason: `missing ${input.stableKeyName}; unmanaged` });
+    }
+    const rank = {
+        create: 0,
+        'safe-update': 1,
+        'remote-changed': 2,
+        conflict: 3,
+        'missing-lock': 4,
+        clean: 5,
+        orphan: 6,
+        collision: 7,
+        skipped: 8,
+        delete: 9,
+    };
+    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: 'role-group',
+        env: input.envName,
+        counts,
+        blockers: [...new Set(blockers)].sort((left, right) => left.localeCompare(right)),
+        items,
+        exclusions: ['members/users are always skipped', 'UUID and version are resolved live and never persisted'],
+    };
+}
+export async function pullRoleGroupsToWorkspace(input) {
+    const { projectRoot, workspaceRoot } = requireProjectLayout(input.cwd, 'Role-group');
+    const records = await loadRemoteRoleGroups(input.client);
+    const skipped = [];
+    const managed = [];
+    const normalizedKeys = new Set();
+    for (const record of records) {
+        const manifest = roleGroupManifestFromRecord(record, input.stableKeyName);
+        if (!manifest) {
+            const name = String(record.name || roleGroupIdOf(record) || 'unknown');
+            skipped.push({ name, targetPath: name, reason: `missing ${input.stableKeyName}; unmanaged` });
+            continue;
+        }
+        const normalized = normalizeStableKeyValue(manifest.stableKey);
+        if (normalizedKeys.has(normalized)) {
+            throw new Error(`Duplicate role-group stableKey "${manifest.stableKey}" on ${input.envName}; no files were changed.`);
+        }
+        normalizedKeys.add(normalized);
+        managed.push(manifest);
+    }
+    managed.sort((left, right) => left.stableKey.localeCompare(right.stableKey));
+    const lock = readComponentLock(projectRoot);
+    const existingByStableKey = new Map();
+    for (const entry of readWorkspaceRoleGroups(input.cwd)) {
+        const errors = validateManifest(entry.manifest, input.stableKeyName);
+        if (errors.length > 0) {
+            throw new Error(`Cannot pull over invalid role-group manifest ${path.relative(projectRoot, entry.manifestPath)}: ${errors.join('; ')}.`);
+        }
+        const normalized = normalizeStableKeyValue(entry.manifest.stableKey || '');
+        if (existingByStableKey.has(normalized)) {
+            throw new Error(`Duplicate local role-group stableKey "${entry.manifest.stableKey}"; no files were changed.`);
+        }
+        existingByStableKey.set(normalized, entry);
+    }
+    const writes = [];
+    const outputPaths = new Set();
+    for (const manifest of managed) {
+        const hash = hashPortableRoleGroup(manifest);
+        const normalized = normalizeStableKeyValue(manifest.stableKey);
+        const existing = existingByStableKey.get(normalized);
+        if (existing && !input.force) {
+            const localHash = hashPortableRoleGroup(existing.manifest);
+            const lockEntry = Object.values(lock.roleGroups)
+                .find((entry) => normalizeStableKeyValue(entry.stableKey) === normalized);
+            if (localHash !== hash && (!lockEntry || localHash !== lockEntry.sourceHash)) {
+                throw new Error(`Cannot pull role-group "${manifest.stableKey}": local manifest changed since the lock baseline. Re-run with --force.`);
+            }
+        }
+        const filePath = roleGroupManifestPath(workspaceRoot, manifest);
+        if (outputPaths.has(filePath)) {
+            throw new Error(`Multiple role-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,
+        });
+    }
+    const roleGroupsRoot = path.join(workspaceRoot, ROLE_GROUPS_DIRECTORY);
+    let lockChanged = false;
+    for (const write of writes) {
+        writePulledManifest({
+            filePath: write.filePath,
+            manifest: write.manifest,
+            previousPath: write.previousPath,
+            root: roleGroupsRoot,
+            force: input.force,
+        });
+        const normalized = normalizeStableKeyValue(write.manifest.stableKey);
+        const previousPair = Object.entries(lock.roleGroups)
+            .find(([, entry]) => normalizeStableKeyValue(entry.stableKey) === normalized);
+        const previous = previousPair?.[1];
+        if (previousPair && previousPair[0] !== write.manifest.stableKey) {
+            delete lock.roleGroups[previousPair[0]];
+            lockChanged = true;
+        }
+        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.roleGroups[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 buildCreatePayload(manifest) {
+    return {
+        name: manifest.name,
+        ...(manifest.category === undefined ? {} : { category: manifest.category }),
+        ...(manifest.description === undefined ? {} : { desc: manifest.description }),
+        metadata: sanitizeUserMetadata(manifest.metadata),
+        roles: manifest.roles,
+    };
+}
+function buildBaseUpdatePayload(manifest, target) {
+    if (!Number.isInteger(target.version))
+        throw new Error('target role-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,
+    };
+}
+function updateEnvironmentBaseline(input) {
+    const { projectRoot } = requireProjectLayout(input.cwd, 'Role-group');
+    const lock = readComponentLock(projectRoot);
+    const normalized = normalizeStableKeyValue(input.stableKey);
+    const localMatches = readWorkspaceRoleGroups(input.cwd)
+        .filter(({ manifest }) => typeof manifest.stableKey === 'string'
+        && normalizeStableKeyValue(manifest.stableKey) === normalized);
+    if (localMatches.length !== 1) {
+        throw new Error(`Cannot update lock baseline for "${input.stableKey}": expected one local role-group manifest, found ${localMatches.length}.`);
+    }
+    const local = localMatches[0];
+    const pair = Object.entries(lock.roleGroups)
+        .find(([, entry]) => normalizeStableKeyValue(entry.stableKey) === normalized);
+    const lockKey = pair?.[0] || local.manifest.stableKey;
+    const entry = pair?.[1];
+    const existingBaseline = entry?.environments[input.envName];
+    const nextEntry = {
+        stableKey: local.manifest.stableKey,
+        path: toPortableRelativePath(projectRoot, local.manifestPath),
+        sourceHash: hashPortableRoleGroup(local.manifest),
+        environments: {
+            ...(entry?.environments || {}),
+            [input.envName]: existingBaseline?.remoteHash === input.remoteHash
+                ? existingBaseline
+                : { remoteHash: input.remoteHash, syncedAt: new Date().toISOString() },
+        },
+    };
+    if (entry && hashStable(entry) === hashStable(nextEntry))
+        return;
+    if (lockKey !== local.manifest.stableKey)
+        delete lock.roleGroups[lockKey];
+    lock.roleGroups[local.manifest.stableKey] = nextEntry;
+    writeComponentLock(projectRoot, lock);
+}
+function localManifestByStableKey(cwd) {
+    return new Map(readWorkspaceRoleGroups(cwd).map((entry) => [
+        normalizeStableKeyValue(entry.manifest.stableKey),
+        entry,
+    ]));
+}
+async function liveTargetByStableKey(client, stableKeyName, stableKey) {
+    const normalized = normalizeStableKeyValue(stableKey);
+    const records = await loadRemoteRoleGroups(client);
+    return records.filter((record) => {
+        const value = readConfiguredResourceMetadataStableKey(record, stableKeyName);
+        return value ? normalizeStableKeyValue(value) === normalized : false;
+    });
+}
+async function assertCreateStillSafe(client, stableKeyName, desired) {
+    const normalized = normalizeStableKeyValue(desired.stableKey);
+    const records = await loadRemoteRoleGroups(client);
+    for (const record of records) {
+        const key = readConfiguredResourceMetadataStableKey(record, stableKeyName);
+        if (key && normalizeStableKeyValue(key) === normalized) {
+            throw new Error('matching stableKey appeared after planning');
+        }
+        if (!key && roleGroupHint(record) === roleGroupHint(desired)) {
+            throw new Error(`target role-group matching category/name appeared without ${stableKeyName} after planning`);
+        }
+    }
+}
+export async function pushRoleGroups(input) {
+    const plan = await buildRoleGroupsPlan(input);
+    if (plan.blockers.length > 0) {
+        throw new Error(`Role-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(`Role-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('Role-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;
+        const local = localByKey.get(normalizeStableKeyValue(item.stableKey));
+        updateEnvironmentBaseline({ cwd: input.cwd, envName: input.envName, stableKey: item.stableKey, remoteHash: item.currentHash });
+        results.push({
+            stableKey: item.stableKey,
+            action: 'noop',
+            status: 'skipped',
+            targetPath: local ? localTargetPath(input.cwd, local.manifestPath) : item.stableKey,
+            reason: 'no local changes',
+        });
+    }
+    const writeItems = plan.items.filter((item) => item.status === 'create')
+        .concat(plan.items.filter((item) => ['safe-update', 'missing-lock', 'remote-changed', 'conflict'].includes(item.status)));
+    for (const item of writeItems) {
+        const stableKey = item.stableKey || '';
+        const local = localByKey.get(normalizeStableKeyValue(stableKey));
+        if (!local) {
+            results.push({ stableKey, action: item.status === 'create' ? 'create' : 'update', status: 'failed', targetPath: stableKey, error: 'desired manifest disappeared after planning' });
+            continue;
+        }
+        const targetPath = localTargetPath(input.cwd, local.manifestPath);
+        const liveDesiredHash = hashPortableRoleGroup(local.manifest);
+        if (liveDesiredHash !== item.desiredHash) {
+            results.push({ stableKey, action: item.status === 'create' ? 'create' : 'update', status: 'failed', targetPath, error: 'desired manifest changed after planning' });
+            continue;
+        }
+        if (item.status === 'create') {
+            try {
+                await assertCreateStillSafe(input.client, input.stableKeyName, local.manifest);
+                const created = unwrapData(await input.client.createRoleGroup(buildCreatePayload(local.manifest)));
+                const createdId = roleGroupIdOf(created);
+                if (!createdId)
+                    throw new Error('create response did not include roleGroupId');
+                const verified = unwrapData(await input.client.getRoleGroup(createdId));
+                const verifiedManifest = roleGroupManifestFromRecord(verified, input.stableKeyName);
+                if (!verifiedManifest || hashPortableRoleGroup(verifiedManifest) !== liveDesiredHash) {
+                    throw new Error('created role-group did not match desired portable hash');
+                }
+                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) });
+            }
+            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 = roleGroupIdOf(matches[0]);
+            if (!targetId)
+                throw new Error('live target did not include roleGroupId');
+            let target = unwrapData(await input.client.getRoleGroup(targetId));
+            let targetManifest = roleGroupManifestFromRecord(target, input.stableKeyName);
+            if (!targetManifest || hashPortableRoleGroup(targetManifest) !== item.currentHash) {
+                throw new Error('target changed after planning');
+            }
+            const diff = diffRoleGroups(local.manifest, targetManifest);
+            if (diff.changedFields.length > 0) {
+                await input.client.updateRoleGroup(targetId, buildBaseUpdatePayload(local.manifest, target));
+                target = unwrapData(await input.client.getRoleGroup(targetId));
+                targetManifest = roleGroupManifestFromRecord(target, input.stableKeyName);
+                if (!targetManifest)
+                    throw new Error(`updated target is missing ${input.stableKeyName}`);
+            }
+            const roleDiff = diffRoleGroups(local.manifest, targetManifest);
+            for (const roleKey of roleDiff.rolesToRemove) {
+                await input.client.removeRoleGroupRole(targetId, roleKey);
+            }
+            for (const roleKey of roleDiff.rolesToAdd) {
+                await input.client.addRoleGroupRole(targetId, roleKey);
+            }
+            const verified = unwrapData(await input.client.getRoleGroup(targetId));
+            const verifiedManifest = roleGroupManifestFromRecord(verified, input.stableKeyName);
+            if (!verifiedManifest || hashPortableRoleGroup(verifiedManifest) !== liveDesiredHash) {
+                throw new Error('updated role-group did not match desired portable hash');
+            }
+            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 === '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 };
+}