@revoengine/cli 1.0.8 → 1.0.10

package/dist/src/commands/env.d.ts

@@ -0,0 +1,2 @@
+import type { CommandContext } from '../types.ts';
+export declare function handleEnvCommand(context: CommandContext): Promise<void>;

package/dist/src/commands/env.js

@@ -0,0 +1,360 @@
+import { RevoClient } from "../client.js";
+import { DEFAULT_BASE_URL, DEFAULT_ENV_NAME, getConfigDir, getEnvironmentProfile, listEnvironmentProfiles, removeEnvironmentProfile, resolveRuntimeConfig, saveEnvironmentProfile, } from "../config.js";
+import { applyEnvSyncPlan, buildEnvSyncPlan, captureEnvSnapshot, } from "../env-sync.js";
+import { isInteractiveTerminal, promptConfirm, promptText } from "../prompt.js";
+import { readProjectStableKeyName, readProjectTrackedResources } from "../project.js";
+import { normalizeStableKeyName } from "../resource-metadata.js";
+import { normalizeTrackedResources, shouldTrackResource } from "../tracked-resources.js";
+import { readBoolFlag, readFlag, readValues } from "../utils.js";
+const ENV_NAME_PATTERN = /^[a-zA-Z0-9._-]+$/;
+const RESERVED_ENV_NAMES = new Set(['add', 'list', 'remove', 'diff', 'apply', DEFAULT_ENV_NAME]);
+const ANSI = {
+    reset: '\u001b[0m',
+    bold: '\u001b[1m',
+    dim: '\u001b[2m',
+    green: '\u001b[32m',
+    yellow: '\u001b[33m',
+    red: '\u001b[31m',
+    magenta: '\u001b[35m',
+    cyan: '\u001b[36m',
+};
+function supportsColor() {
+    return Boolean(process.stdout.isTTY || process.env.FORCE_COLOR);
+}
+function paint(text, code) {
+    return supportsColor() ? `${code}${text}${ANSI.reset}` : text;
+}
+const ACTION_MARKS = {
+    create: { symbol: '+', code: ANSI.bold + ANSI.green },
+    update: { symbol: '~', code: ANSI.bold + ANSI.yellow },
+    delete: { symbol: '-', code: ANSI.bold + ANSI.red },
+    collision: { symbol: '!', code: ANSI.bold + ANSI.magenta },
+    orphan: { symbol: ' ', code: ANSI.dim },
+    noop: { symbol: ' ', code: ANSI.dim },
+};
+function formatUpdateDetail(item) {
+    const parts = [];
+    if (item.changedFields && item.changedFields.length > 0) {
+        parts.push(`fields: ${item.changedFields.join(', ')}`);
+    }
+    const elementParts = [
+        ...(item.changedElementKeys || []).map((key) => `~${key}`),
+        ...(item.addedElementKeys || []).map((key) => `+${key}`),
+        ...(item.removedElementKeys || []).map((key) => `-${key}`),
+    ];
+    if (elementParts.length > 0) {
+        parts.push(`elements ${elementParts.join(' ')}`);
+    }
+    return parts.length > 0 ? ` (${parts.join('; ')})` : '';
+}
+function printPlanText(context, plan) {
+    const { println } = context;
+    println(`Comparing ${paint(plan.from.env, ANSI.bold + ANSI.cyan)} -> ${paint(plan.to.env, ANSI.bold + ANSI.cyan)}`);
+    for (const item of plan.items) {
+        if (item.action === 'noop') {
+            continue;
+        }
+        const mark = ACTION_MARKS[item.action];
+        const detail = item.action === 'update'
+            ? formatUpdateDetail(item)
+            : item.reason
+                ? ` (${item.reason})`
+                : '';
+        const line = `${mark.symbol} ${item.action.padEnd(9)} ${item.resourceType}  ${item.stableKey}${detail}`;
+        println(paint(line, mark.code));
+    }
+    const { counts } = plan;
+    println(`Plan: ${counts.create} to create, ${counts.update} to update, ${counts.delete} to delete, `
+        + `${counts.noop} unchanged, ${counts.orphan} orphaned, ${counts.collision} collisions.`);
+}
+function hasBlockingDrift(plan) {
+    return plan.items.some((item) => item.action !== 'noop');
+}
+function readScope(args) {
+    const keys = readValues(args, ['key']);
+    const categories = readValues(args, ['category']);
+    return keys.length > 0 || categories.length > 0 ? { keys, categories } : undefined;
+}
+function readStableKeyName(context) {
+    return normalizeStableKeyName(readFlag(context.args, ['stable-key-name', 'stableKeyName'])
+        || readProjectStableKeyName(context.cwd));
+}
+function readTrackedResources(context) {
+    const values = readValues(context.args, ['resources', 'resource', 'tracked-resources', 'trackedResources']);
+    return values.length > 0
+        ? normalizeTrackedResources(values)
+        : readProjectTrackedResources(context.cwd);
+}
+function requireEnvName(args, flag) {
+    const value = readFlag(args, [flag]) || '';
+    if (!value) {
+        throw new Error(`Missing --${flag} <env>. Use a saved environment name or "${DEFAULT_ENV_NAME}".`);
+    }
+    return value;
+}
+function buildEnvClient(envName) {
+    return new RevoClient(resolveRuntimeConfig({ envName }));
+}
+function assertDifferentEnvironments(fromName, toName, from, to) {
+    if (from.baseUrl === to.baseUrl && from.token === to.token) {
+        throw new Error(`--from ${fromName} and --to ${toName} resolve to the same environment.`);
+    }
+}
+async function captureSnapshots(fromName, toName, stableKeyName) {
+    const fromClient = buildEnvClient(fromName);
+    const toClient = buildEnvClient(toName);
+    assertDifferentEnvironments(fromName, toName, fromClient, toClient);
+    const [source, target] = await Promise.all([
+        captureEnvSnapshot(fromClient, fromName, { stableKeyName }),
+        captureEnvSnapshot(toClient, toName, { stableKeyName }),
+    ]);
+    return { source, target, toClient };
+}
+function emptySnapshot(client, envName) {
+    return {
+        ref: {
+            env: envName,
+            baseUrl: client.baseUrl,
+            instance: client.instance,
+        },
+        components: new Map(),
+        collisions: [],
+    };
+}
+function buildEmptySnapshots(fromName, toName) {
+    const fromClient = buildEnvClient(fromName);
+    const toClient = buildEnvClient(toName);
+    assertDifferentEnvironments(fromName, toName, fromClient, toClient);
+    return {
+        source: emptySnapshot(fromClient, fromName),
+        target: emptySnapshot(toClient, toName),
+        toClient,
+    };
+}
+function validateProfileName(name) {
+    if (!name) {
+        throw new Error('Missing environment name. Usage: revo env add <name>');
+    }
+    if (!ENV_NAME_PATTERN.test(name)) {
+        throw new Error('Environment names may only contain letters, digits, dots, underscores, and dashes.');
+    }
+    if (RESERVED_ENV_NAMES.has(name)) {
+        throw new Error(`"${name}" is a reserved name and cannot be used for an environment.`);
+    }
+}
+async function handleEnvAdd(context) {
+    const { args, println } = context;
+    const name = args._[2] || '';
+    validateProfileName(name);
+    const offline = readBoolFlag(args, ['offline']);
+    const baseUrl = readFlag(args, ['url', 'baseUrl'])
+        || await promptText('RevoEngine API URL', DEFAULT_BASE_URL);
+    const token = (readFlag(args, ['token']) || await promptText('Paste API key (input is visible)')).trim();
+    if (!token) {
+        throw new Error('API key is required.');
+    }
+    let instance = '';
+    if (!offline) {
+        const probe = new RevoClient({ baseUrl, token });
+        await probe.validateSession({ force: true });
+        instance = probe.instance;
+    }
+    const existed = Boolean(getEnvironmentProfile(name));
+    saveEnvironmentProfile(name, {
+        baseUrl,
+        token,
+        ...(instance ? { instance } : {}),
+    });
+    println(`${existed ? 'Updated' : 'Saved'} environment "${name}" in ${getConfigDir()}.`);
+}
+function handleEnvList(context) {
+    const { args, print, println } = context;
+    const profiles = listEnvironmentProfiles();
+    const names = Object.keys(profiles).sort();
+    if (readBoolFlag(args, ['json'])) {
+        print(Object.fromEntries(names.map((name) => [name, {
+                baseUrl: profiles[name].baseUrl,
+                instance: profiles[name].instance || null,
+                tokenConfigured: Boolean(profiles[name].token),
+            }])));
+        return;
+    }
+    if (names.length === 0) {
+        println('No environments saved. Run `revo env add <name>` to add one.');
+        return;
+    }
+    for (const name of names) {
+        const profile = profiles[name];
+        const instanceSuffix = profile.instance ? ` (instance ${profile.instance})` : '';
+        println(`${paint(name.padEnd(16), ANSI.bold + ANSI.cyan)} ${profile.baseUrl}${instanceSuffix}`);
+    }
+}
+function handleEnvRemove(context) {
+    const { args, println } = context;
+    const name = args._[2] || '';
+    if (!name) {
+        throw new Error('Missing environment name. Usage: revo env remove <name>');
+    }
+    if (!removeEnvironmentProfile(name)) {
+        throw new Error(`Unknown environment "${name}". Run 'revo env list' to see saved environments.`);
+    }
+    println(`Removed environment "${name}".`);
+}
+async function handleEnvDiff(context) {
+    const { args, print } = context;
+    const fromName = requireEnvName(args, 'from');
+    const toName = requireEnvName(args, 'to');
+    const prune = readBoolFlag(args, ['prune']);
+    const stableKeyName = readStableKeyName(context);
+    const trackedResources = readTrackedResources(context);
+    const { source, target } = shouldTrackResource(trackedResources, 'component')
+        ? await captureSnapshots(fromName, toName, stableKeyName)
+        : buildEmptySnapshots(fromName, toName);
+    const plan = buildEnvSyncPlan(source, target, { prune, scope: readScope(args) });
+    if (readBoolFlag(args, ['json'])) {
+        print(plan);
+    }
+    else {
+        printPlanText(context, plan);
+    }
+    if (readBoolFlag(args, ['strict']) && hasBlockingDrift(plan)) {
+        throw new Error('Strict mode: environments differ.');
+    }
+}
+async function confirmApply(context, plan, toName) {
+    const { args, println } = context;
+    const yes = readBoolFlag(args, ['yes']);
+    const force = readBoolFlag(args, ['force']);
+    const changeCount = plan.counts.create + plan.counts.update + plan.counts.delete;
+    const deleteCount = plan.counts.delete;
+    if (!isInteractiveTerminal()) {
+        if (!yes) {
+            throw new Error('Apply requires confirmation. Re-run with --yes or use an interactive terminal.');
+        }
+        if (deleteCount > 0 && !force) {
+            throw new Error(`Apply would delete ${deleteCount} component(s) from "${toName}". Re-run with --force to confirm deletes.`);
+        }
+        return true;
+    }
+    if (!yes) {
+        const confirmed = await promptConfirm(`Apply ${changeCount} change(s) to "${toName}"?`, false);
+        if (!confirmed) {
+            println('Apply cancelled.');
+            return false;
+        }
+    }
+    if (deleteCount > 0 && !force) {
+        const confirmed = await promptConfirm(`Also delete ${deleteCount} component(s) from "${toName}"?`, false);
+        if (!confirmed) {
+            println('Apply cancelled: deletes were not confirmed. Re-run without --prune to apply without deletes.');
+            return false;
+        }
+    }
+    return true;
+}
+function formatDuration(durationMs) {
+    if (durationMs < 1_000) {
+        return `${durationMs}ms`;
+    }
+    const seconds = durationMs / 1_000;
+    return seconds < 10 ? `${seconds.toFixed(1)}s` : `${Math.round(seconds)}s`;
+}
+function printApplyResult(context, result) {
+    const { println } = context;
+    const mark = ACTION_MARKS[result.action];
+    if (result.status === 'failed') {
+        println(`${paint('Failed', ANSI.bold + ANSI.red)}    ${result.action.padEnd(9)} ${result.stableKey} (${result.error})`);
+        return;
+    }
+    const verifiedSuffix = result.verified === false ? paint(' (verification mismatch)', ANSI.bold + ANSI.red) : '';
+    println(`${paint('Applied', mark.code)}   ${result.action.padEnd(9)} ${result.stableKey}${verifiedSuffix}`);
+}
+async function handleEnvApply(context) {
+    const { args, print, println } = context;
+    const fromName = requireEnvName(args, 'from');
+    const toName = requireEnvName(args, 'to');
+    const prune = readBoolFlag(args, ['prune']);
+    const dryRun = readBoolFlag(args, ['dry-run', 'dryRun']);
+    const json = readBoolFlag(args, ['json']);
+    const stableKeyName = readStableKeyName(context);
+    const trackedResources = readTrackedResources(context);
+    const { source, target, toClient } = shouldTrackResource(trackedResources, 'component')
+        ? await captureSnapshots(fromName, toName, stableKeyName)
+        : buildEmptySnapshots(fromName, toName);
+    const plan = buildEnvSyncPlan(source, target, { prune, scope: readScope(args) });
+    if (!json) {
+        printPlanText(context, plan);
+    }
+    const changeCount = plan.counts.create + plan.counts.update + plan.counts.delete;
+    if (plan.counts.collision > 0) {
+        throw new Error(`Cannot apply: ${plan.counts.collision} stable-key collision(s) in scope. Resolve duplicates or narrow the scope with --key/--category.`);
+    }
+    if (changeCount === 0) {
+        if (json) {
+            print({ plan, results: [] });
+        }
+        else {
+            println('No changes to apply.');
+        }
+        return;
+    }
+    if (dryRun) {
+        if (json) {
+            print({ plan, results: [] });
+        }
+        else {
+            println('Dry run: no changes applied.');
+        }
+        return;
+    }
+    if (!await confirmApply(context, plan, toName)) {
+        return;
+    }
+    const startedAt = Date.now();
+    const results = await applyEnvSyncPlan({
+        targetClient: toClient,
+        plan,
+        source,
+        target,
+        stableKeyName,
+        onItem: json ? undefined : (result) => printApplyResult(context, result),
+    });
+    const failed = results.filter((result) => result.status === 'failed');
+    const unverified = results.filter((result) => result.verified === false);
+    if (json) {
+        print({ plan, results });
+    }
+    else {
+        println(`Applied ${results.length - failed.length}/${results.length} in ${formatDuration(Date.now() - startedAt)}.`);
+        if (unverified.length > 0) {
+            println(paint(`Warning: ${unverified.length} component(s) did not verify against the source after apply.`, ANSI.bold + ANSI.yellow));
+        }
+    }
+    if (failed.length > 0) {
+        throw new Error(`Apply finished with ${failed.length} failure(s).`);
+    }
+}
+export async function handleEnvCommand(context) {
+    const subcommand = context.args._[1] || 'list';
+    if (subcommand === 'add') {
+        await handleEnvAdd(context);
+        return;
+    }
+    if (subcommand === 'list') {
+        handleEnvList(context);
+        return;
+    }
+    if (subcommand === 'remove') {
+        handleEnvRemove(context);
+        return;
+    }
+    if (subcommand === 'diff') {
+        await handleEnvDiff(context);
+        return;
+    }
+    if (subcommand === 'apply') {
+        await handleEnvApply(context);
+        return;
+    }
+    throw new Error(`Unknown env command: ${subcommand}. Available: add, list, remove, diff, apply.`);
+}

package/dist/src/commands/index.d.ts

@@ -1,7 +1,9 @@
 export * from './auth.ts';
 export * from './component.ts';
 export * from './endpoints.ts';
+export * from './env.ts';
 export * from './info.ts';
+export * from './metadata.ts';
 export * from './project.ts';
 export * from './request.ts';
 export * from './search.ts';

package/dist/src/commands/index.js

@@ -1,7 +1,9 @@
 export * from "./auth.js";
 export * from "./component.js";
 export * from "./endpoints.js";
+export * from "./env.js";
 export * from "./info.js";
+export * from "./metadata.js";
 export * from "./project.js";
 export * from "./request.js";
 export * from "./search.js";

package/dist/src/commands/metadata.d.ts

@@ -0,0 +1,2 @@
+import type { CommandContext } from '../types.ts';
+export declare function handleMetadataCommand(context: CommandContext): Promise<void>;

package/dist/src/commands/metadata.js

@@ -0,0 +1,137 @@
+import { RevoClient } from "../client.js";
+import { DEFAULT_ENV_NAME, resolveRuntimeConfig } from "../config.js";
+import { applyMetadataBackfillPlan, buildMetadataBackfillPlan, } from "../metadata-backfill.js";
+import { isInteractiveTerminal, promptConfirm } from "../prompt.js";
+import { readProjectStableKeyName, readProjectTrackedResources } from "../project.js";
+import { normalizeStableKeyName } from "../resource-metadata.js";
+import { normalizeTrackedResources } from "../tracked-resources.js";
+import { readBoolFlag, readFlag, readValues } from "../utils.js";
+const ANSI = {
+    reset: '\u001b[0m',
+    bold: '\u001b[1m',
+    dim: '\u001b[2m',
+    green: '\u001b[32m',
+    yellow: '\u001b[33m',
+    red: '\u001b[31m',
+    cyan: '\u001b[36m',
+};
+function supportsColor() {
+    return Boolean(process.stdout.isTTY || process.env.FORCE_COLOR);
+}
+function paint(text, code) {
+    return supportsColor() ? `${code}${text}${ANSI.reset}` : text;
+}
+function readEnvName(context) {
+    return readFlag(context.args, ['env']) || DEFAULT_ENV_NAME;
+}
+function readStableKeyName(context) {
+    return normalizeStableKeyName(readFlag(context.args, ['stable-key-name', 'stableKeyName'])
+        || readProjectStableKeyName(context.cwd));
+}
+function readTrackedResources(context) {
+    const values = readValues(context.args, ['resources', 'resource', 'tracked-resources', 'trackedResources']);
+    return values.length > 0
+        ? normalizeTrackedResources(values)
+        : readProjectTrackedResources(context.cwd);
+}
+function buildEnvClient(envName) {
+    return new RevoClient(resolveRuntimeConfig({ envName }));
+}
+async function buildPlan(context) {
+    const envName = readEnvName(context);
+    const client = buildEnvClient(envName);
+    return buildMetadataBackfillPlan({
+        client,
+        envName,
+        stableKeyName: readStableKeyName(context),
+        trackedResources: readTrackedResources(context),
+        force: readBoolFlag(context.args, ['force']),
+    });
+}
+function printPlanText(context, plan) {
+    const { println } = context;
+    println(`Metadata backfill ${paint(plan.env, ANSI.bold + ANSI.cyan)} (${plan.stableKeyName})`);
+    for (const item of plan.items) {
+        if (item.action === 'skip') {
+            continue;
+        }
+        println(`${paint('+ update', ANSI.bold + ANSI.green)} ${item.resourceType} ${item.name} -> ${item.metadataField}.${item.stableKeyName}=${item.stableKey}`);
+    }
+    println(`Plan: ${plan.counts.update} to update, ${plan.counts.skip} already populated.`);
+}
+function printResult(context, result) {
+    const { println } = context;
+    if (result.action === 'failed') {
+        println(`${paint('Failed', ANSI.bold + ANSI.red)} ${result.resourceType} ${result.resourceId} (${result.error})`);
+        return;
+    }
+    if (result.action === 'skip') {
+        println(`${paint('Skipped', ANSI.dim + ANSI.yellow)} ${result.resourceType} ${result.resourceId}`);
+        return;
+    }
+    println(`${paint('Updated', ANSI.bold + ANSI.green)} ${result.resourceType} ${result.resourceId} ${result.stableKey}`);
+}
+async function confirmApply(context, plan) {
+    const yes = readBoolFlag(context.args, ['yes']);
+    if (plan.counts.update === 0) {
+        return false;
+    }
+    if (yes) {
+        return true;
+    }
+    if (!isInteractiveTerminal()) {
+        throw new Error('Metadata apply requires confirmation. Re-run with --yes or use an interactive terminal.');
+    }
+    return promptConfirm(`Populate metadata on ${plan.counts.update} resource(s) in "${plan.env}"?`, false);
+}
+async function handleMetadataPlan(context) {
+    const plan = await buildPlan(context);
+    if (readBoolFlag(context.args, ['json'])) {
+        context.print(plan);
+        return;
+    }
+    printPlanText(context, plan);
+}
+async function handleMetadataApply(context) {
+    const plan = await buildPlan(context);
+    if (!readBoolFlag(context.args, ['json'])) {
+        printPlanText(context, plan);
+    }
+    if (!await confirmApply(context, plan)) {
+        if (readBoolFlag(context.args, ['json'])) {
+            context.print({ plan, results: [] });
+        }
+        else {
+            context.println('No metadata changes to apply.');
+        }
+        return;
+    }
+    const client = buildEnvClient(plan.env);
+    const results = await applyMetadataBackfillPlan({ client, plan });
+    if (readBoolFlag(context.args, ['json'])) {
+        context.print({ plan, results });
+    }
+    else {
+        for (const result of results) {
+            printResult(context, result);
+        }
+        const failed = results.filter((result) => result.action === 'failed').length;
+        context.println(`Applied ${results.length - failed}/${results.length}.`);
+    }
+    const failed = results.filter((result) => result.action === 'failed').length;
+    if (failed > 0) {
+        throw new Error(`Metadata apply finished with ${failed} failure(s).`);
+    }
+}
+export async function handleMetadataCommand(context) {
+    const subcommand = context.args._[1] || 'plan';
+    if (subcommand === 'plan') {
+        await handleMetadataPlan(context);
+        return;
+    }
+    if (subcommand === 'apply') {
+        await handleMetadataApply(context);
+        return;
+    }
+    throw new Error('Unknown metadata command. Usage: revo metadata <plan|apply> --env <name>');
+}

package/dist/src/commands/project.js

@@ -1,5 +1,10 @@
 import path from 'node:path';
-import { buildProjectSyncState, buildEditorTypesUrl, extractSandboxEndpoint, extractEditorTypesBundle, resolveProjectInvocation, resolveProjectTarget, syncProjectFiles, } from "../project.js";
+import { readComponentLock } from "../component-lock.js";
+import { applyMetadataBackfillPlan, buildMetadataBackfillPlan, } from "../metadata-backfill.js";
+import { buildProjectSyncState, buildEditorTypesUrl, extractSandboxEndpoint, extractEditorTypesBundle, readProjectComponentIdentity, readProjectMetadata, readProjectStableKeyName, readProjectTrackedResources, resolveProjectInvocation, resolveProjectTarget, syncProjectFiles, } from "../project.js";
+import { promptText } from "../prompt.js";
+import { DEFAULT_COMPONENT_IDENTITY, DEFAULT_STABLE_KEY_NAME, normalizeComponentIdentityConfig, normalizeComponentIdentityMode, normalizeStableKeyName, } from "../resource-metadata.js";
+import { formatTrackedResources, normalizeTrackedResources, } from "../tracked-resources.js";
 function printSyncSummary(println, projectRoot, workspaceRoot, result, prefix) {
     const workspaceDirectory = path.relative(projectRoot, workspaceRoot) || '.';
     println(`${prefix} ${projectRoot}`);
@@ -31,6 +36,68 @@ async function resolveProjectSyncInput(context) {
         bundle,
     });
 }
+async function resolveTrackedResources(invocation, projectRoot) {
+    if (invocation.trackedResources) {
+        return invocation.trackedResources;
+    }
+    if (invocation.action === 'update') {
+        return readProjectTrackedResources(projectRoot);
+    }
+    const existing = readProjectTrackedResources(projectRoot);
+    const answer = await promptText('Resources to track with CLI (all, component; comma-separated)', formatTrackedResources(existing));
+    return normalizeTrackedResources(answer);
+}
+async function resolveComponentIdentity(invocation, projectRoot) {
+    if (invocation.identityMode === 'componentId' && invocation.stableKeyName) {
+        throw new Error('--stable-key-name cannot be used with --identity-mode componentId.');
+    }
+    const existingMetadata = readProjectMetadata(projectRoot);
+    const existingLock = readComponentLock(projectRoot);
+    const hasTrackedIdentity = Object.keys(existingLock.components).length > 0
+        || existingLock.componentIdentity.mode === 'stableKey';
+    const existing = existingMetadata
+        ? readProjectComponentIdentity(projectRoot)
+        : hasTrackedIdentity
+            ? existingLock.componentIdentity
+            : DEFAULT_COMPONENT_IDENTITY;
+    const defaultIdentity = existing;
+    const mode = invocation.identityMode || (invocation.action === 'update'
+        ? existing.mode
+        : normalizeComponentIdentityMode(await promptText('Component identity mode (stableKey or componentId)', defaultIdentity.mode)));
+    if (mode === 'componentId') {
+        return { mode };
+    }
+    const metadataProperty = invocation.stableKeyName || (invocation.action === 'update'
+        ? readProjectStableKeyName(projectRoot)
+        : normalizeStableKeyName(await promptText('Stable key metadata property', defaultIdentity.mode === 'stableKey'
+            ? defaultIdentity.metadataProperty || DEFAULT_STABLE_KEY_NAME
+            : DEFAULT_STABLE_KEY_NAME)));
+    return normalizeComponentIdentityConfig({ mode, metadataProperty }, DEFAULT_COMPONENT_IDENTITY);
+}
+async function backfillStableKeyMetadata(context, stableKeyName, trackedResources) {
+    const plan = await buildMetadataBackfillPlan({
+        client: context.client,
+        envName: 'default',
+        stableKeyName,
+        trackedResources,
+    });
+    if (plan.counts.update === 0) {
+        return;
+    }
+    const results = await applyMetadataBackfillPlan({
+        client: context.client,
+        plan,
+    });
+    const failed = results.filter((result) => result.action === 'failed');
+    if (failed.length > 0) {
+        const details = failed
+            .map((result) => `${result.resourceId}: ${result.error || 'unknown error'}`)
+            .join('; ');
+        throw new Error(`Project initialized, but stable-key metadata backfill failed for ${failed.length} component(s): ${details}`);
+    }
+    const updated = results.filter((result) => result.action === 'update').length;
+    context.println(`Backfilled stable-key metadata on ${updated} component(s).`);
+}
 export async function handleProjectCommand(context) {
     const { args, client, cwd, println } = context;
     const invocation = resolveProjectInvocation(args);
@@ -39,6 +106,13 @@ export async function handleProjectCommand(context) {
     }
     const layout = resolveProjectTarget(cwd, invocation.targetArg);
     const syncInput = await resolveProjectSyncInput(context);
+    syncInput.componentIdentity = await resolveComponentIdentity(invocation, layout.projectRoot);
+    syncInput.trackedResources = await resolveTrackedResources(invocation, layout.projectRoot);
     const result = syncProjectFiles(layout, syncInput);
     printSyncSummary(println, layout.projectRoot, layout.workspaceRoot, result, invocation.action === 'update' ? 'Updated Revo project in' : 'Initialized Revo project in');
+    if (invocation.action === 'init'
+        && syncInput.componentIdentity.mode === 'stableKey'
+        && context.args['metadata-backfill'] !== false) {
+        await backfillStableKeyMetadata(context, syncInput.componentIdentity.metadataProperty || DEFAULT_STABLE_KEY_NAME, syncInput.trackedResources);
+    }
 }

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;
@@ -10,8 +15,10 @@ export type ComponentLockEntry = {
     sourceHash: string;
     pulledAt: string;
 };
+export type ComponentLockEntryInput = Omit<ComponentLockEntry, 'identityMode' | 'remoteComponentId'> & Partial<Pick<ComponentLockEntry, 'identityMode' | 'remoteComponentId'>>;
 export type RevoLockFile = {
-    schemaVersion: 1;
+    schemaVersion: 2;
+    componentIdentity: ComponentIdentityConfig;
     components: Record<string, ComponentLockEntry>;
 };
 export declare function hashStable(value: unknown): string;
@@ -23,7 +30,6 @@ export declare function normalizeComponentSource(component: ComponentRecord): {
     desc: string | null;
     active: boolean;
     type: string;
-    compiler: string;
     async: boolean;
     elements: {
         key: string;
@@ -34,7 +40,26 @@ 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 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): ComponentLockEntry | null;
+export declare function upsertComponentLockEntry(projectRoot: string, entry: ComponentLockEntryInput, identity?: ComponentIdentityConfig): void;