@revoengine/cli 1.0.9 → 1.0.11

package/dist/src/commands/terminal.js

@@ -0,0 +1,511 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import WebSocket from 'ws';
+import { getActiveEnvironmentName, getConfigDir, getEnvironmentProfile, loadStoredConfig, resolveRuntimeConfig } from "../config.js";
+import { promptConfirm } from "../prompt.js";
+import { installTerminalService, terminalServiceInstalled, uninstallTerminalService } from "./terminal-service.js";
+const configDir = getConfigDir;
+const runnerConfig = () => path.join(configDir(), 'runner.json');
+const MAX_MODEL_OUTPUT_BYTES = 100_000;
+const MAX_LOCAL_LOG_BYTES = 10_000_000;
+const OUTPUT_FRAME_CHARS = 1_000;
+const LOG_RETENTION_MS = 24 * 60 * 60 * 1_000;
+const CHILD_ENV_KEYS = ['HOME', 'PATH', 'USER', 'LOGNAME', 'SHELL', 'TMPDIR', 'LANG', 'LC_ALL', 'LC_CTYPE', 'TERM'];
+export function childEnvironment(source) {
+    const safe = {};
+    for (const key of CHILD_ENV_KEYS)
+        if (source[key] !== undefined)
+            safe[key] = source[key];
+    return safe;
+}
+function logDirectory() { return path.join(configDir(), 'runner-logs'); }
+function pruneLogs(directory) {
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    for (const name of fs.readdirSync(directory)) {
+        const file = path.join(directory, name);
+        try {
+            if (name.endsWith('.log') && Date.now() - fs.statSync(file).mtimeMs > LOG_RETENTION_MS)
+                fs.unlinkSync(file);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+}
+function readJson(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return {};
+        throw error;
+    }
+}
+function readStore() {
+    const value = readJson(runnerConfig());
+    return { devices: Array.isArray(value.devices) ? value.devices.map((device) => ({
+            ...device, agentTerminalId: device.agentTerminalId || device.deviceId, deviceId: undefined,
+        })) : [] };
+}
+function saveStore(store) {
+    fs.mkdirSync(configDir(), { recursive: true, mode: 0o700 });
+    const file = runnerConfig();
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    try {
+        fs.writeFileSync(temporary, JSON.stringify(store, null, 2), { mode: 0o600 });
+        fs.renameSync(temporary, file);
+        fs.chmodSync(file, 0o600);
+    }
+    finally {
+        try {
+            fs.unlinkSync(temporary);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+}
+export function resolveWorkspaceDirectory(root, requested) {
+    const workspace = fs.realpathSync(root);
+    const workdir = fs.realpathSync(requested);
+    const relative = path.relative(workspace, workdir);
+    if (relative.startsWith('..') || path.isAbsolute(relative))
+        throw new Error('Working directory is outside the registered workspace.');
+    return workdir;
+}
+function option(argv, name) {
+    const index = argv.indexOf(`--${name}`);
+    if (index >= 0)
+        return argv[index + 1];
+    return argv.find(value => value.startsWith(`--${name}=`))?.slice(name.length + 3);
+}
+function resolveProfile(argv) {
+    const urlOverride = option(argv, 'url');
+    const tokenOverride = option(argv, 'token');
+    const configured = resolveRuntimeConfig({ baseUrl: urlOverride,
+        token: tokenOverride, instance: option(argv, 'instance'), envName: option(argv, 'env') });
+    const token = configured.token;
+    if (!token || !token.startsWith('sk-'))
+        throw new Error('A personal Revo API key is required. Run revo auth login or select a CLI profile.');
+    return { baseUrl: configured.baseUrl.replace(/\/$/, ''), token,
+        instance: option(argv, 'instance') || (urlOverride || tokenOverride ? undefined : configured.instance),
+        realtimeUrl: option(argv, 'realtime-url'), production: configured.production };
+}
+function apiUrl(profile, route) {
+    const base = profile.baseUrl.replace(/\/(?:api\/)?v1\/?$/, '');
+    const url = new URL(base);
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && url.hostname === 'localhost'))
+        throw new Error('Remote Revo API requires HTTPS.');
+    return `${base}/api/v1${route}`;
+}
+async function api(profile, method, route, body) {
+    if (profile.production && !profile.productionWriteConfirmed && ['POST', 'PUT', 'PATCH', 'DELETE'].includes(method)) {
+        const confirmed = await promptConfirm(`PRODUCTION: send ${method} ${apiUrl(profile, route)}?`, false);
+        if (!confirmed)
+            throw new Error('Production write cancelled. Confirm the operation in an interactive terminal.');
+        profile.productionWriteConfirmed = true;
+    }
+    const response = await fetch(apiUrl(profile, route), {
+        method,
+        redirect: 'manual',
+        headers: { Authorization: `Bearer ${profile.token}`,
+            ...(profile.instance ? { instance: profile.instance } : {}),
+            ...(body ? { 'Content-Type': 'application/json' } : {}) },
+        ...(body ? { body: JSON.stringify(body) } : {}),
+    });
+    if (response.status >= 300 && response.status < 400)
+        throw new Error(`Revo API ${method} ${route} redirected; refusing to forward credentials.`);
+    const value = await response.json().catch(() => ({}));
+    if (!response.ok)
+        throw new Error(`Revo API ${method} ${route} returned ${response.status}: ${String(value?.message || 'request failed')}`);
+    return (value?.data ?? value);
+}
+function realtimeUrl(value) {
+    const url = new URL(value);
+    if (!['http:', 'https:', 'ws:', 'wss:'].includes(url.protocol))
+        throw new Error('Invalid Realtime URL.');
+    url.protocol = url.protocol === 'https:' || url.protocol === 'wss:' ? 'wss:' : 'ws:';
+    if (url.protocol === 'ws:' && url.hostname !== 'localhost')
+        throw new Error('Remote Realtime requires TLS.');
+    url.pathname = '/runner/v1/ws';
+    url.search = '';
+    return url.toString();
+}
+function send(socket, frame) {
+    if (socket.readyState === WebSocket.OPEN)
+        socket.send(JSON.stringify(frame));
+}
+export function boundResultFrame(frame) {
+    const bounded = { ...frame, stdout: String(frame.stdout || ''), stderr: String(frame.stderr || '') };
+    while (Buffer.byteLength(JSON.stringify(bounded)) > 90_000) {
+        if (bounded.stdout.length >= bounded.stderr.length)
+            bounded.stdout = bounded.stdout.slice(0, Math.floor(bounded.stdout.length * 0.75));
+        else
+            bounded.stderr = bounded.stderr.slice(0, Math.floor(bounded.stderr.length * 0.75));
+    }
+    return bounded;
+}
+function sendResult(socket, frame) {
+    send(socket, boundResultFrame(frame));
+}
+export async function runCommand(input, onDone, onChunk) {
+    const workdir = resolveWorkspaceDirectory(input.workspace, input.workdir);
+    const directory = input.logDir || logDirectory();
+    const logPath = path.join(directory, `${input.executionId || randomUUID()}.log`);
+    let logFd;
+    try {
+        pruneLogs(directory);
+        logFd = fs.openSync(logPath, 'wx', 0o600);
+    }
+    catch (error) {
+        console.error(`Runner log unavailable: ${error.message}`);
+    }
+    const child = spawn(process.platform === 'darwin' ? '/bin/zsh' : '/bin/sh', ['-lc', input.cmd], {
+        cwd: workdir, detached: true, stdio: ['ignore', 'pipe', 'pipe'], env: childEnvironment(process.env),
+    });
+    let stdout = '';
+    let stderr = '';
+    let modelBytes = 0;
+    let logBytes = 0;
+    let truncated = false;
+    let logTruncated = logFd === undefined;
+    let timedOut = false;
+    let finished = false;
+    const terminate = () => { if (child.pid) {
+        try {
+            process.kill(-child.pid, 'SIGKILL');
+        }
+        catch { /* exited */ }
+    } };
+    const timer = setTimeout(() => { timedOut = true; terminate(); }, Math.min(Math.max(input.timeoutMs, 1_000), 600_000));
+    const append = (chunk, kind) => {
+        const logPart = chunk.subarray(0, Math.max(0, MAX_LOCAL_LOG_BYTES - logBytes));
+        if (logPart.length && logFd !== undefined) {
+            const header = Buffer.from(`[${kind}] `);
+            if (logBytes + header.length + logPart.length <= MAX_LOCAL_LOG_BYTES) {
+                try {
+                    fs.writeSync(logFd, header);
+                    fs.writeSync(logFd, logPart);
+                    logBytes += header.length + logPart.length;
+                }
+                catch (error) {
+                    console.error(`Runner log write failed: ${error.message}`);
+                    logTruncated = true;
+                    try {
+                        fs.closeSync(logFd);
+                    }
+                    catch { /* log already unavailable */ }
+                    logFd = undefined;
+                }
+            }
+            else
+                logTruncated = true;
+        }
+        if (logPart.length < chunk.length)
+            logTruncated = true;
+        const available = Math.max(0, MAX_MODEL_OUTPUT_BYTES - modelBytes);
+        const modelPart = chunk.subarray(0, available);
+        modelBytes += modelPart.length;
+        if (modelPart.length < chunk.length)
+            truncated = true;
+        const text = modelPart.toString('utf8');
+        if (kind === 'stdout')
+            stdout += text;
+        else
+            stderr += text;
+        if (onChunk && text) {
+            for (let offset = 0; offset < text.length; offset += OUTPUT_FRAME_CHARS)
+                onChunk(kind, text.slice(offset, offset + OUTPUT_FRAME_CHARS));
+        }
+    };
+    child.stdout?.on('data', (chunk) => append(chunk, 'stdout'));
+    child.stderr?.on('data', (chunk) => append(chunk, 'stderr'));
+    const finish = (exitCode, error) => {
+        if (finished)
+            return;
+        finished = true;
+        clearTimeout(timer);
+        if (logFd !== undefined) {
+            try {
+                fs.closeSync(logFd);
+            }
+            catch {
+                logTruncated = true;
+            }
+        }
+        onDone({ executed: !error, exitCode, stdout, stderr: error ? `${stderr}\n${error.message}` : stderr,
+            timedOut, truncated, logTruncated, logPath: logFd === undefined ? '' : logPath });
+    };
+    child.on('close', code => finish(code));
+    child.on('error', error => finish(null, error));
+    return child;
+}
+async function connect(profile, device) {
+    let backoffMs = 1_000;
+    let stopping = false;
+    let activeSocket;
+    const activeChildren = new Set();
+    const stop = () => {
+        stopping = true;
+        if (activeSocket?.readyState === WebSocket.CONNECTING)
+            activeSocket.terminate();
+        else
+            activeSocket?.close();
+        for (const child of activeChildren)
+            if (child.pid) {
+                try {
+                    process.kill(-child.pid, 'SIGKILL');
+                }
+                catch { /* exited */ }
+            }
+    };
+    process.on('SIGINT', stop);
+    process.on('SIGTERM', stop);
+    try {
+        while (!stopping) {
+            const children = new Map();
+            const cancelledExecutions = new Set();
+            try {
+                await new Promise((resolve, reject) => {
+                    const socket = new WebSocket(device.realtimeUrl, {
+                        headers: { Authorization: `Bearer ${profile.token}`,
+                            ...(profile.instance ? { instance: profile.instance } : {}) },
+                        perMessageDeflate: false,
+                    });
+                    activeSocket = socket;
+                    let connectionId = '';
+                    let workspace = device.workspace;
+                    let heartbeat;
+                    let lastHeartbeat = Date.now();
+                    let incoming = Promise.resolve();
+                    socket.on('open', () => send(socket, { type: 'hello', protocol: 1, agentTerminalId: device.agentTerminalId, secret: device.secret }));
+                    socket.on('message', raw => {
+                        incoming = incoming.then(async () => {
+                            if (stopping || socket.readyState !== WebSocket.OPEN)
+                                return;
+                            const frame = JSON.parse(raw.toString());
+                            if (frame.type === 'ready' && frame.connectionId) {
+                                connectionId = frame.connectionId;
+                                workspace = frame.workspace || device.workspace;
+                                backoffMs = 1_000;
+                                console.log(`Connected ${device.name} (${device.agentTerminalId}).`);
+                                heartbeat = setInterval(() => {
+                                    if (Date.now() - lastHeartbeat > 45_000) {
+                                        socket.terminate();
+                                        return;
+                                    }
+                                    send(socket, { type: 'heartbeat', connectionId });
+                                }, 15_000);
+                                return;
+                            }
+                            if (frame.type === 'heartbeat') {
+                                lastHeartbeat = Date.now();
+                                return;
+                            }
+                            if (frame.connectionId !== connectionId || !frame.executionId)
+                                return;
+                            if (frame.type === 'cancel') {
+                                const child = children.get(frame.executionId);
+                                if (child?.pid) {
+                                    cancelledExecutions.add(frame.executionId);
+                                    try {
+                                        process.kill(-child.pid, 'SIGKILL');
+                                    }
+                                    catch { /* exited */ }
+                                }
+                                return;
+                            }
+                            if (frame.type !== 'execute')
+                                return;
+                            if (typeof frame.cmd !== 'string' || !frame.cmd.trim() || frame.cmd.length > 8_192 || children.size >= 4) {
+                                sendResult(socket, { type: 'result', connectionId, executionId: frame.executionId,
+                                    executed: false, exitCode: null, stdout: '', stderr: children.size >= 4 ? 'runner_busy' : 'invalid_command', timedOut: false });
+                                return;
+                            }
+                            try {
+                                const child = await runCommand({ cmd: frame.cmd, workdir: frame.workdir || workspace,
+                                    workspace, timeoutMs: frame.timeoutMs || 60_000, executionId: frame.executionId }, result => {
+                                    children.delete(frame.executionId);
+                                    activeChildren.delete(child);
+                                    const { stdout, stderr, ...completion } = result;
+                                    send(socket, { type: 'result', connectionId, executionId: frame.executionId,
+                                        ...completion, cancelled: cancelledExecutions.delete(frame.executionId), stdout: '', stderr: '' });
+                                }, (stream, text) => send(socket, { type: 'output', connectionId,
+                                    executionId: frame.executionId, stream, text }));
+                                children.set(frame.executionId, child);
+                                activeChildren.add(child);
+                                send(socket, { type: 'ack', connectionId, executionId: frame.executionId });
+                            }
+                            catch (error) {
+                                sendResult(socket, { type: 'result', connectionId, executionId: frame.executionId,
+                                    executed: false, exitCode: null, stdout: '', stderr: error instanceof Error ? error.message : 'Command rejected.', timedOut: false });
+                            }
+                        }).catch(() => socket.terminate());
+                    });
+                    socket.on('close', (code, reason) => {
+                        if (heartbeat)
+                            clearInterval(heartbeat);
+                        for (const child of children.values())
+                            if (child.pid) {
+                                try {
+                                    process.kill(-child.pid, 'SIGKILL');
+                                }
+                                catch { /* exited */ }
+                            }
+                        for (const child of children.values())
+                            activeChildren.delete(child);
+                        children.clear();
+                        cancelledExecutions.clear();
+                        if (activeSocket === socket)
+                            activeSocket = undefined;
+                        if (code === 1008 && reason.toString() !== 'heartbeat_timeout')
+                            reject(new Error(`Runner rejected by Realtime: ${reason.toString() || 'policy violation'}.`));
+                        else
+                            resolve();
+                    });
+                    socket.on('error', error => { console.error(`Realtime connection: ${error.message}`); });
+                });
+            }
+            catch (error) {
+                if (error instanceof Error && error.message.startsWith('Runner rejected by Realtime:'))
+                    throw error;
+                console.error(error);
+            }
+            if (stopping)
+                break;
+            await new Promise(resolve => setTimeout(resolve, backoffMs));
+            backoffMs = Math.min(backoffMs * 2, 30_000);
+        }
+    }
+    finally {
+        stop();
+        process.off('SIGINT', stop);
+        process.off('SIGTERM', stop);
+    }
+}
+export async function handleTerminalCommand(argv) {
+    const command = argv[0] || 'help';
+    if (command === 'help' || argv.includes('--help')) {
+        console.log('revo terminal connect|status|disconnect [--project NAME] [--workspace PATH] [--name NAME] [--url URL] [--realtime-url URL]\nrevo terminal service install|uninstall --workspace PATH [--project NAME]');
+        return;
+    }
+    if (command === 'service') {
+        const action = argv[1];
+        if (!action || action === 'help') {
+            console.log('revo terminal service install|uninstall --workspace PATH [--project NAME]');
+            return;
+        }
+        if (action !== 'install' && action !== 'uninstall')
+            throw new Error('Use revo terminal service install|uninstall.');
+        const requestedWorkspace = option(argv, 'workspace');
+        if (!requestedWorkspace)
+            throw new Error('Terminal service requires --workspace PATH.');
+        const workspace = fs.existsSync(requestedWorkspace) ? fs.realpathSync(requestedWorkspace) : path.resolve(requestedWorkspace);
+        const envName = option(argv, 'env') || getActiveEnvironmentName();
+        if (action === 'uninstall') {
+            const result = uninstallTerminalService({ workspace, envName, configHome: process.env.XDG_CONFIG_HOME });
+            console.log(result.removed ? `Terminal service stopped and removed (${result.label}). Grant remains active.`
+                : `No terminal service installed for this workspace (${result.label}).`);
+            return;
+        }
+        if (!fs.existsSync(workspace))
+            throw new Error('Workspace does not exist.');
+        for (const unsupported of ['token', 'url', 'instance', 'realtime-url'])
+            if (option(argv, unsupported))
+                throw new Error(`Service install cannot use --${unsupported}; use a saved CLI login/profile.`);
+        const saved = envName === 'default' ? loadStoredConfig({ allowLegacy: false }) : getEnvironmentProfile(envName);
+        if (!saved?.token?.startsWith('sk-'))
+            throw new Error('A saved personal Revo API key is required. Run revo auth login or select a saved --project profile.');
+        const baseUrl = saved.baseUrl.replace(/\/$/, '');
+        const devices = readStore().devices.filter(item => item.workspace === workspace && item.baseUrl === baseUrl
+            && (!saved.instance || item.instance === saved.instance));
+        if (devices.length !== 1)
+            throw new Error('Expected one registered terminal for this workspace and saved profile. Run revo terminal connect first.');
+        const device = devices[0];
+        const profile = { baseUrl, token: saved.token, instance: device.instance };
+        const listing = await api(profile, 'GET', '/agents/terminals');
+        if (!listing.devices.some(item => item.agentTerminalId === device.agentTerminalId && item.status === 'approved'))
+            throw new Error('Terminal grant is not approved. Approve it in AI Agents → Terminals before installing the service.');
+        const result = installTerminalService({ workspace, envName, pathValue: process.env.PATH,
+            configHome: process.env.XDG_CONFIG_HOME });
+        console.log(result.installed ? `Terminal service installed and started (${result.label}).`
+            : `Terminal service already installed (${result.label}).`);
+        return;
+    }
+    const profile = resolveProfile(argv);
+    let me;
+    if (!profile.instance) {
+        const currentUser = await api(profile, 'GET', '/me');
+        me = currentUser;
+        profile.instance = currentUser.instance?.id;
+        if (!profile.instance)
+            throw new Error('The API key instance could not be resolved. Pass --instance.');
+    }
+    const workspace = fs.realpathSync(option(argv, 'workspace') || process.cwd());
+    const store = readStore();
+    let device = store.devices.find(item => item.workspace === workspace && item.baseUrl === profile.baseUrl && item.instance === profile.instance);
+    if (command === 'disconnect') {
+        if (!device) {
+            console.log('No local terminal registration for this workspace.');
+            return;
+        }
+        if (terminalServiceInstalled(workspace, option(argv, 'env') || getActiveEnvironmentName()))
+            throw new Error('Uninstall the terminal service before revoking this terminal grant.');
+        const selectedDevice = device;
+        const listing = await api(profile, 'GET', '/agents/terminals');
+        if (listing.devices.some(item => item.agentTerminalId === selectedDevice.agentTerminalId))
+            await api(profile, 'POST', `/agents/terminals/${selectedDevice.agentTerminalId}/revoke`);
+        store.devices = store.devices.filter(item => item !== selectedDevice);
+        saveStore(store);
+        console.log('Terminal registration removed.');
+        return;
+    }
+    if (command === 'status') {
+        const listing = await api(profile, 'GET', '/agents/terminals');
+        console.log(JSON.stringify({ devices: listing.devices.map(item => ({ agentTerminalId: item.agentTerminalId, status: item.status, mode: item.mode })) }, null, 2));
+        return;
+    }
+    if (command !== 'connect')
+        throw new Error(`Unknown command: ${command}`);
+    if (process.platform !== 'darwin' && process.platform !== 'linux')
+        throw new Error('Runner supports macOS and Linux.');
+    if (device) {
+        const listing = await api(profile, 'GET', '/agents/terminals');
+        if (!listing.devices.some(item => item.agentTerminalId === device.agentTerminalId && item.status !== 'revoked')) {
+            store.devices = store.devices.filter(item => item !== device);
+            saveStore(store);
+            device = undefined;
+        }
+    }
+    if (!device) {
+        const currentUser = me || await api(profile, 'GET', '/me');
+        const rt = option(argv, 'realtime-url') || profile.realtimeUrl || currentUser.instance?.endpoints?.realtime;
+        if (!rt)
+            throw new Error('Realtime endpoint unavailable. Pass --realtime-url.');
+        const secret = randomBytes(32).toString('hex');
+        device = { agentTerminalId: randomUUID(), secret, workspace, name: option(argv, 'name') || os.hostname(),
+            baseUrl: profile.baseUrl, instance: profile.instance, realtimeUrl: realtimeUrl(rt) };
+        await api(profile, 'POST', '/agents/terminals/pair', { agentTerminalId: device.agentTerminalId,
+            secretHash: createHash('sha256').update(Buffer.from(secret, 'hex')).digest('hex'),
+            name: device.name, workspace });
+        store.devices.push(device);
+        saveStore(store);
+        console.log(`Pending approval in AI Agents → Terminals: ${device.name} (${device.agentTerminalId}).`);
+    }
+    for (;;) {
+        const listing = await api(profile, 'GET', '/agents/terminals');
+        const grant = listing.devices.find(item => item.agentTerminalId === device.agentTerminalId);
+        if (grant?.status === 'approved')
+            break;
+        if (!grant || grant.status === 'revoked')
+            throw new Error('Terminal grant revoked or missing.');
+        await new Promise(resolve => setTimeout(resolve, 2_000));
+    }
+    await connect(profile, device);
+}

package/dist/src/component-lock.d.ts

@@ -1,7 +1,12 @@
+import { type ComponentIdentityConfig, type ComponentIdentityMode } from './resource-metadata.ts';
 import type { ComponentRecord } from './types.ts';
 export declare const REVO_LOCK_FILE: string;
 export type ComponentLockEntry = {
+    identityMode: ComponentIdentityMode;
+    metadataProperty?: string;
+    stableKey?: string;
     componentId: string;
+    remoteComponentId: string;
     componentName: string;
     category: string | null;
     path: string;
@@ -9,10 +14,101 @@ export type ComponentLockEntry = {
     remoteHash: string;
     sourceHash: string;
     pulledAt: string;
+    environments?: Record<string, ComponentEnvironmentBaseline>;
+};
+export type ComponentEnvironmentBaseline = {
+    remoteComponentId: string;
+    remoteVersion: number | null;
+    remoteHash: string;
+    syncedAt: string;
+};
+export type ComponentLockEntryInput = Omit<ComponentLockEntry, 'identityMode' | 'remoteComponentId'> & Partial<Pick<ComponentLockEntry, 'identityMode' | 'remoteComponentId'>>;
+export type EnvironmentBaseline = {
+    remoteHash: string;
+    syncedAt: string;
+};
+export type RoleGroupLockEntry = {
+    stableKey: string;
+    path: string;
+    sourceHash: string;
+    environments: Record<string, EnvironmentBaseline>;
+};
+export type GroupLockEntry = {
+    stableKey: string;
+    path: string;
+    sourceHash: string;
+    owner?: GroupOwnerPolicy;
+    environments: Record<string, EnvironmentBaseline>;
+};
+export type GroupOwnerPolicy = {
+    type: 'group';
+    stableKey: string;
+} | {
+    type: 'manual-user';
+} | {
+    type: 'unresolved';
+    reason: string;
+};
+export type JobTemplateLockEntry = {
+    stableKey: string;
+    path: string;
+    sourceHash: string;
+    environments: Record<string, EnvironmentBaseline>;
+    migration?: {
+        componentBinding?: 'pinned-unsupported';
+        executionPrincipal?: 'excluded';
+    };
+};
+export type ScheduleLockEntry = {
+    stableKey: string;
+    path: string;
+    sourceHash: string;
+    environments: Record<string, EnvironmentBaseline>;
+};
+export type EventLockEntry = {
+    stableKey: string;
+    path: string;
+    sourceHash: string;
+    environments: Record<string, EnvironmentBaseline>;
+};
+export type EndpointLockEntry = {
+    stableKey: string;
+    path: string;
+    sourceHash: string;
+    environments: Record<string, EnvironmentBaseline>;
+};
+export type DatabaseSchemaLockEntry = {
+    stableKey: string;
+    path: string;
+    sourceHash: string;
+    sourceRestricted?: boolean;
+    parentStableKey?: string;
+    environments: Record<string, {
+        remoteHash: string;
+        tombstone?: {
+            deletedAt: string;
+            parentStableKey: string;
+        };
+    }>;
+};
+export type DatabaseViewLockEntry = {
+    stableKey: string;
+    path: string;
+    sourceHash: string;
+    environments: Record<string, EnvironmentBaseline>;
 };
 export type RevoLockFile = {
-    schemaVersion: 1;
+    schemaVersion: 2;
+    componentIdentity: ComponentIdentityConfig;
     components: Record<string, ComponentLockEntry>;
+    groups: Record<string, GroupLockEntry>;
+    roleGroups: Record<string, RoleGroupLockEntry>;
+    jobTemplates: Record<string, JobTemplateLockEntry>;
+    schedules: Record<string, ScheduleLockEntry>;
+    events: Record<string, EventLockEntry>;
+    endpoints: Record<string, EndpointLockEntry>;
+    databaseSchemas: Record<string, DatabaseSchemaLockEntry>;
+    databaseViews: Record<string, DatabaseViewLockEntry>;
 };
 export declare function hashStable(value: unknown): string;
 export declare function sanitizeComponentSource<T extends ComponentRecord>(component: T): T;
@@ -33,7 +129,35 @@ export declare function normalizeComponentSource(component: ComponentRecord): {
     }[];
 };
 export declare function hashComponentSource(component: ComponentRecord): string;
+export declare function normalizePortableComponentSource(component: ComponentRecord): {
+    name: string;
+    category: string | null;
+    desc: string | null;
+    active: boolean;
+    type: string;
+    async: boolean;
+    elements: {
+        key: string;
+        desc: string | null;
+        hidden: boolean;
+        order: number;
+        details: string;
+    }[];
+};
+export declare function hashPortableComponentSource(component: ComponentRecord): string;
+export declare const PORTABLE_COMPONENT_CONFIG_FIELDS: readonly ["name", "category", "desc", "active", "type", "async"];
+export type PortableComponentConfigField = (typeof PORTABLE_COMPONENT_CONFIG_FIELDS)[number];
+export declare function diffPortableComponentSource(source: ComponentRecord, target: ComponentRecord): {
+    configurationFields: ("desc" | "name" | "category" | "type" | "active" | "async")[];
+    elementsChanged: boolean;
+    changedFields: string[];
+};
+export declare function buildPortableComponentUpdatePayload(source: ComponentRecord, target: ComponentRecord, changedFields: ReadonlyArray<string>): Record<string, unknown>;
 export declare function getLockPath(projectRoot: string): string;
 export declare function readComponentLock(projectRoot: string): RevoLockFile;
 export declare function writeComponentLock(projectRoot: string, lock: RevoLockFile): void;
-export declare function upsertComponentLockEntry(projectRoot: string, entry: ComponentLockEntry): void;
+export declare function componentLockKey(identity: ComponentIdentityConfig, component: ComponentRecord): string | null;
+export declare function componentLockMatchesIdentity(lock: RevoLockFile, identity: ComponentIdentityConfig): boolean;
+export declare function getComponentLockEntry(lock: RevoLockFile, identity: ComponentIdentityConfig, component: ComponentRecord, environmentName?: string): ComponentLockEntry | null;
+export declare function getComponentLockEntries(lock: RevoLockFile, identity: ComponentIdentityConfig, environmentName?: string): Record<string, ComponentLockEntry>;
+export declare function upsertComponentLockEntry(projectRoot: string, entry: ComponentLockEntryInput, identity?: ComponentIdentityConfig, environmentName?: string): void;