@nexusclawhq/cli 0.2.1

package/dist/nexus-cli/src/commands/dx.js

@@ -0,0 +1,857 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerDxCommands = registerDxCommands;
+const chalk_1 = __importDefault(require("chalk"));
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const project_1 = require("./generate/project");
+const api_client_1 = require("../services/api-client");
+const package_manifest_1 = require("../services/package-manifest");
+const pack_registry_1 = require("../services/pack-registry");
+const source_tracker_1 = require("../services/source-tracker");
+const workspace_dx_1 = require("../services/workspace-dx");
+const workspace_contract_1 = require("../services/workspace-contract");
+const logger_1 = require("../utils/logger");
+const structured_error_1 = require("../utils/structured-error");
+const dx_pages_1 = require("./dx-pages");
+const page_source_file_1 = require("../services/page-source-file");
+const revision_ledger_1 = require("../services/revision-ledger");
+const json_diff_1 = require("../services/json-diff");
+const page_source_file_2 = require("../../../shared/src/source-format/page-source-file");
+const target_context_1 = require("../services/target-context");
+function resolveCodePromotionPackages(workspaceDir, packageRefs) {
+    const workspace = (0, workspace_contract_1.loadWorkspaceManifest)(workspaceDir).manifest;
+    const localPackages = new Map(workspace.localPackages.map((entry) => [entry.name, entry]));
+    const registryRoot = workspace.registry?.rootDirectory
+        ? path.resolve(workspaceDir, workspace.registry.rootDirectory)
+        : null;
+    return packageRefs.map((pkgRef) => {
+        const explicitDirectory = pkgRef.directory
+            ? path.resolve(workspaceDir, pkgRef.directory)
+            : null;
+        if (explicitDirectory) {
+            const loaded = (0, package_manifest_1.loadPackageManifest)(explicitDirectory);
+            const validation = (0, package_manifest_1.validateLocalPackageManifest)(loaded.manifest, {
+                packageDirectory: loaded.packageDirectory,
+            });
+            if (!validation.valid) {
+                throw new Error(`Invalid code package ${loaded.manifest.name}@${loaded.manifest.version}: ${validation.errors.join('; ')}`);
+            }
+            if (loaded.manifest.packageClass !== 'code-extension') {
+                throw new Error(`Environment promotion only supports code-extension packages, got ${loaded.manifest.packageClass ?? 'legacy'} for ${loaded.manifest.name}.`);
+            }
+            if (pkgRef.version
+                && pkgRef.version.trim()
+                && pkgRef.version !== loaded.manifest.version) {
+                throw new Error(`Environment descriptor expects ${pkgRef.packageName}@${pkgRef.version}, but local manifest is ${loaded.manifest.version}.`);
+            }
+            return {
+                manifest: loaded.manifest,
+                packageDirectory: loaded.packageDirectory,
+                sourceUri: explicitDirectory,
+            };
+        }
+        if (pkgRef.source === 'registry') {
+            if (!registryRoot) {
+                throw new Error(`Unable to resolve registry-backed code package ${pkgRef.packageName}. Add workspace.registry.rootDirectory to the workspace manifest.`);
+            }
+            const packageRef = pkgRef.version?.trim()
+                ? `${pkgRef.packageName}@${pkgRef.version}`
+                : pkgRef.packageName;
+            const record = (0, pack_registry_1.resolveRegistryPackage)(registryRoot, packageRef);
+            const validation = (0, package_manifest_1.validateLocalPackageManifest)(record.manifest, {
+                packageDirectory: record.packageDirectory,
+            });
+            if (!validation.valid) {
+                throw new Error(`Invalid code package ${record.manifest.name}@${record.manifest.version}: ${validation.errors.join('; ')}`);
+            }
+            if (record.manifest.packageClass !== 'code-extension') {
+                throw new Error(`Environment promotion only supports code-extension packages, got ${record.manifest.packageClass ?? 'legacy'} for ${record.manifest.name}.`);
+            }
+            return {
+                manifest: record.manifest,
+                packageDirectory: record.packageDirectory,
+                sourceUri: record.packageDirectory,
+            };
+        }
+        const sourcePath = localPackages.get(pkgRef.packageName)
+            ? path.resolve(workspaceDir, localPackages.get(pkgRef.packageName)?.path ?? '')
+            : null;
+        if (!sourcePath) {
+            throw new Error(`Unable to resolve code package source for ${pkgRef.packageName}. Add codePackages[].directory, mark the ref as source=registry, or add a matching localPackages entry.`);
+        }
+        const loaded = (0, package_manifest_1.loadPackageManifest)(sourcePath);
+        const validation = (0, package_manifest_1.validateLocalPackageManifest)(loaded.manifest, {
+            packageDirectory: loaded.packageDirectory,
+        });
+        if (!validation.valid) {
+            throw new Error(`Invalid code package ${loaded.manifest.name}@${loaded.manifest.version}: ${validation.errors.join('; ')}`);
+        }
+        if (loaded.manifest.packageClass !== 'code-extension') {
+            throw new Error(`Environment promotion only supports code-extension packages, got ${loaded.manifest.packageClass ?? 'legacy'} for ${loaded.manifest.name}.`);
+        }
+        if (pkgRef.version
+            && pkgRef.version.trim()
+            && pkgRef.version !== loaded.manifest.version) {
+            throw new Error(`Environment descriptor expects ${pkgRef.packageName}@${pkgRef.version}, but local manifest is ${loaded.manifest.version}.`);
+        }
+        return {
+            manifest: loaded.manifest,
+            packageDirectory: loaded.packageDirectory,
+            sourceUri: sourcePath,
+        };
+    });
+}
+function registerInit(program) {
+    program
+        .command('init')
+        .description('Bootstrap a DX workspace using the canonical project scaffold')
+        .requiredOption('--name <name>', 'Workspace name')
+        .option('--dir <directory>', 'Target directory', '.')
+        .option('--template <template>', 'Workspace template', 'empty')
+        .action((options) => {
+        const projectDir = (0, project_1.createProjectScaffold)({
+            name: options.name,
+            dir: options.dir,
+            template: options.template,
+        });
+        console.log(`Workspace "${options.name}" created at ${projectDir}`);
+    });
+}
+function registerValidate(program) {
+    program
+        .command('validate')
+        .description('Validate workspace manifest, environment descriptors, and local package contracts')
+        .option('--workspace <path>', 'Workspace root', '.')
+        .option('--json', 'Print machine-readable output', false)
+        .action((options) => {
+        const result = (0, workspace_dx_1.validateWorkspaceContract)(options.workspace);
+        if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            console.log(chalk_1.default.cyan(result.summary.join(' | ')));
+            result.environments.forEach((environment) => {
+                console.log(`env  ${environment.descriptor.name} -> ${environment.valid ? 'ok' : 'invalid'} (${environment.path})`);
+            });
+            result.packages.forEach((pkg) => {
+                console.log(`pkg  ${pkg.manifest.name}@${pkg.manifest.version} -> ${pkg.valid ? 'ok' : 'invalid'}`);
+            });
+            if (result.warnings.length > 0) {
+                console.log(chalk_1.default.yellow('\nWarnings:'));
+                result.warnings.forEach((warning) => console.log(`  - ${warning}`));
+            }
+            if (result.errors.length > 0) {
+                console.log(chalk_1.default.red('\nErrors:'));
+                result.errors.forEach((error) => console.log(`  - ${error}`));
+            }
+        }
+        if (!result.valid) {
+            process.exit(1);
+        }
+    });
+}
+function registerPack(program) {
+    program
+        .command('pack')
+        .description('Validate a package against the full metadata package contract and prepare a release preview')
+        .requiredOption('--source <path>', 'Package directory or manifest path')
+        .option('--workspace <path>', 'Workspace root', '.')
+        .action((options) => {
+        const loaded = (0, package_manifest_1.loadPackageManifest)(options.source);
+        const workspaceDir = path.resolve(options.workspace);
+        let pageStats = null;
+        try {
+            const workspace = (0, workspace_contract_1.loadWorkspaceManifest)(workspaceDir);
+            const pageRoot = (0, dx_pages_1.findPagesSourceRoot)(workspace.manifest);
+            if (pageRoot) {
+                const pageRootAbsPath = path.resolve(workspaceDir, pageRoot.path);
+                const scannedEntries = (0, page_source_file_1.scanPageSourceRoot)(pageRootAbsPath);
+                if (scannedEntries.length > 0) {
+                    let totalBytes = 0;
+                    const packPageDir = path.join(loaded.packageDirectory, 'custompage');
+                    for (const entry of scannedEntries) {
+                        const mainContent = fs.readFileSync(entry.main, 'utf-8');
+                        const schemaContent = entry.sidecar
+                            ? fs.readFileSync(entry.sidecar, 'utf-8')
+                            : '';
+                        const parseResult = (0, page_source_file_1.parsePageSourceFile)({
+                            mainContent,
+                            schemaContent,
+                            sourcePath: entry.main,
+                        });
+                        if (!parseResult.ok) {
+                            const errorDetail = parseResult.errors
+                                .map((e) => `  ${e.path}: ${e.reason} — ${e.detail}`)
+                                .join('\n');
+                            (0, structured_error_1.emitStructuredError)({
+                                command: 'dx:pack',
+                                phase: 'validate',
+                                metadataKind: 'pages',
+                                apiName: entry.apiName,
+                                reason: 'parse-error',
+                                detail: errorDetail,
+                            });
+                            throw new Error(`Page source file parse error for "${entry.apiName}":\n${errorDetail}`);
+                        }
+                        const apiNameDir = path.join(packPageDir, entry.apiName);
+                        fs.mkdirSync(apiNameDir, { recursive: true });
+                        const mainFileName = `${entry.apiName}.page.json`;
+                        const schemaFileName = `${entry.apiName}.page.schema.json`;
+                        fs.writeFileSync(path.join(apiNameDir, mainFileName), mainContent, 'utf-8');
+                        if (schemaContent) {
+                            fs.writeFileSync(path.join(apiNameDir, schemaFileName), schemaContent, 'utf-8');
+                        }
+                        totalBytes += Buffer.byteLength(mainContent, 'utf-8');
+                        totalBytes += Buffer.byteLength(schemaContent, 'utf-8');
+                    }
+                    if (!loaded.manifest.includedMetadataKinds.includes('pages')) {
+                        loaded.manifest.includedMetadataKinds.push('pages');
+                    }
+                    pageStats = { count: scannedEntries.length, bytes: totalBytes };
+                }
+            }
+        }
+        catch (err) {
+            if (err.message?.includes('Duplicate apiName')) {
+                (0, structured_error_1.emitStructuredError)({
+                    command: 'dx:pack',
+                    phase: 'scan',
+                    metadataKind: 'pages',
+                    reason: 'duplicate-apiname',
+                    detail: err.message,
+                });
+                throw err;
+            }
+            if (err.message?.includes('parse error')) {
+                throw err;
+            }
+        }
+        const validation = (0, package_manifest_1.validateLocalPackageManifest)(loaded.manifest, {
+            packageDirectory: loaded.packageDirectory,
+        });
+        console.log(chalk_1.default.cyan(`${loaded.manifest.name}@${loaded.manifest.version}`));
+        console.log(`  schemaVersion: ${loaded.manifest.schemaVersion}`);
+        console.log(`  packageType: ${loaded.manifest.packageType}`);
+        console.log(`  packageClass: ${loaded.manifest.packageClass ?? 'legacy-v0'}`);
+        console.log(`  metadataKinds: ${loaded.manifest.includedMetadataKinds.join(', ') || 'none'}`);
+        console.log(`  seedKinds: ${loaded.manifest.includedSeedKinds.join(', ') || 'none'}`);
+        if (pageStats) {
+            console.log(`  pages: ${pageStats.count} records, ${pageStats.bytes} bytes`);
+        }
+        if (validation.warnings.length > 0) {
+            console.log(chalk_1.default.yellow('\nWarnings:'));
+            validation.warnings.forEach((warning) => console.log(`  - ${warning}`));
+        }
+        if (validation.errors.length > 0) {
+            console.log(chalk_1.default.red('\nErrors:'));
+            validation.errors.forEach((error) => console.log(`  - ${error}`));
+            process.exit(1);
+        }
+    });
+}
+function registerPublish(program) {
+    program
+        .command('publish')
+        .description('Preview publish inputs using workspace registry settings')
+        .requiredOption('--source <path>', 'Package directory or manifest path')
+        .option('--workspace <path>', 'Workspace root', '.')
+        .action((options) => {
+        const loaded = (0, package_manifest_1.loadPackageManifest)(options.source);
+        const validation = (0, package_manifest_1.validateLocalPackageManifest)(loaded.manifest, {
+            packageDirectory: loaded.packageDirectory,
+        });
+        if (!validation.valid) {
+            validation.errors.forEach((error) => logger_1.logger.error(error));
+            process.exit(1);
+        }
+        const workspace = (0, workspace_contract_1.loadWorkspaceManifest)(options.workspace);
+        console.log(chalk_1.default.cyan(`${loaded.manifest.name}@${loaded.manifest.version}`));
+        console.log(`  registry.url: ${workspace.manifest.registry?.url ?? 'not-configured'}`);
+        console.log(`  registry.channel: ${workspace.manifest.registry?.channel ?? 'not-configured'}`);
+        console.log('  publishMode: contract-preview');
+    });
+}
+function registerInstall(program) {
+    program
+        .command('install')
+        .description('Install a local metadata package using workspace/env contract resolution')
+        .requiredOption('--source <path>', 'Package directory or manifest path')
+        .option('--workspace <path>', 'Workspace root', '.')
+        .option('--env <name>', 'Environment descriptor name')
+        .option('--target-org <alias>', 'Target org alias override')
+        .option('--workspace-id <id>', 'Target workspace id override')
+        .option('--dry-run', 'Only generate the install plan', false)
+        .action(async (options) => {
+        const loaded = (0, package_manifest_1.loadPackageManifest)(options.source);
+        const validation = (0, package_manifest_1.validateLocalPackageManifest)(loaded.manifest, {
+            packageDirectory: loaded.packageDirectory,
+        });
+        if (!validation.valid) {
+            validation.errors.forEach((error) => logger_1.logger.error(error));
+            process.exit(1);
+        }
+        const { context } = (0, target_context_1.resolveTargetContext)({
+            workspaceDir: options.workspace,
+            workspaceId: options.workspaceId,
+            targetOrg: options.targetOrg,
+            environmentName: options.env,
+        });
+        const { workspaceId } = context;
+        const client = (0, api_client_1.createApiClient)(context.targetOrg);
+        (0, target_context_1.printTargetSummary)(context);
+        let handledPages = false;
+        if (loaded.manifest.includedMetadataKinds.includes('pages')) {
+            const workspaceDir = path.resolve(options.workspace);
+            const packPageDir = path.join(loaded.packageDirectory, 'custompage');
+            if (fs.existsSync(packPageDir)) {
+                const apiNameDirs = fs.readdirSync(packPageDir).filter((entry) => {
+                    const entryPath = path.join(packPageDir, entry);
+                    return fs.statSync(entryPath).isDirectory();
+                });
+                let sourceOfTruthMode = 'REQUIRE_EXPLICIT';
+                try {
+                    const workspace = (0, workspace_contract_1.loadWorkspaceManifest)(workspaceDir);
+                    const pageRoot = (0, dx_pages_1.findPagesSourceRoot)(workspace.manifest);
+                    if (pageRoot?.sourceOfTruthMode) {
+                        const modeMap = {
+                            'source-wins': 'SOURCE_WINS',
+                            'runtime-wins': 'RUNTIME_WINS',
+                            'require-explicit': 'REQUIRE_EXPLICIT',
+                        };
+                        sourceOfTruthMode = modeMap[pageRoot.sourceOfTruthMode] ?? 'REQUIRE_EXPLICIT';
+                    }
+                }
+                catch {
+                }
+                const ledgerStorage = new revision_ledger_1.LedgerStorage(workspaceDir);
+                const baselineStore = new revision_ledger_1.PageSourceBaselineStore(ledgerStorage);
+                const bundles = [];
+                for (const apiName of apiNameDirs) {
+                    const apiNamePath = path.join(packPageDir, apiName);
+                    const mainFile = path.join(apiNamePath, `${apiName}.page.json`);
+                    const schemaFile = path.join(apiNamePath, `${apiName}.page.schema.json`);
+                    if (!fs.existsSync(mainFile)) {
+                        continue;
+                    }
+                    const mainContent = fs.readFileSync(mainFile, 'utf-8');
+                    const schemaContent = fs.existsSync(schemaFile)
+                        ? fs.readFileSync(schemaFile, 'utf-8')
+                        : '';
+                    const baseline = baselineStore.getByApiName(apiName);
+                    bundles.push({
+                        apiName,
+                        mainContent,
+                        schemaContent,
+                        baselineRemoteUpdatedAt: baseline?.remoteUpdatedAt ?? null,
+                    });
+                }
+                if (bundles.length > 0) {
+                    const applyResult = await client.graphql(`mutation ApplyCustomPageSources($input: ApplyCustomPageSourcesInput!) {
+                applyCustomPageSources(input: $input) {
+                  applied {
+                    apiName
+                    action
+                    remoteUpdatedAt
+                  }
+                  errors {
+                    apiName
+                    reason
+                  }
+                }
+              }`, {
+                        input: {
+                            workspaceId,
+                            bundles,
+                            sourceOfTruthMode,
+                            dryRun: !!options.dryRun,
+                        },
+                    });
+                    const { applied, errors } = applyResult.applyCustomPageSources;
+                    handledPages = errors.length === 0;
+                    for (const entry of applied) {
+                        console.log(`  pages: ${entry.action.toLowerCase()} ${entry.apiName}`);
+                        (0, structured_error_1.debugPageAction)('pages', entry.action.toLowerCase(), entry.apiName);
+                    }
+                    if (options.dryRun && applied.length === 0 && errors.length === 0) {
+                        for (const bundle of bundles) {
+                            console.log(`  pages: dry-run ${bundle.apiName}`);
+                        }
+                    }
+                    if (errors.length > 0) {
+                        for (const err of errors) {
+                            (0, structured_error_1.emitStructuredError)({
+                                command: 'dx:install',
+                                phase: 'apply',
+                                metadataKind: 'pages',
+                                apiName: err.apiName ?? undefined,
+                                reason: err.reason,
+                            });
+                        }
+                    }
+                    if (!options.dryRun && errors.length === 0) {
+                        for (const entry of applied) {
+                            if (entry.action !== 'SKIP') {
+                                baselineStore.upsert({
+                                    apiName: entry.apiName,
+                                    remoteUpdatedAt: entry.remoteUpdatedAt,
+                                    localHash: '',
+                                    sidecarHash: '',
+                                });
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        const metadataKindsHandledByDedicatedPaths = new Set(['pages']);
+        const remainingMetadataKinds = loaded.manifest.includedMetadataKinds.filter((kind) => !metadataKindsHandledByDedicatedPaths.has(kind));
+        if (handledPages
+            && remainingMetadataKinds.length === 0
+            && loaded.manifest.includedSeedKinds.length === 0) {
+            console.log(chalk_1.default.cyan(`${loaded.manifest.name}`));
+            console.log(`  status: ${options.dryRun ? 'dry-run' : 'applied'}`);
+            console.log('  metadata: pages');
+            console.log('  seeds: none');
+            return;
+        }
+        const result = await client.installMetadataPackage({
+            workspaceId,
+            manifest: loaded.manifest,
+            dryRun: !!options.dryRun,
+            packageDirectory: loaded.packageDirectory,
+        });
+        console.log(chalk_1.default.cyan(`${result.packageName}`));
+        console.log(`  status: ${result.status}`);
+        console.log(`  metadata: ${result.appliedMetadataKinds.join(', ') || 'none'}`);
+        console.log(`  seeds: ${result.appliedSeedKinds.join(', ') || 'none'}`);
+        result.warnings.forEach((warning) => console.log(`  - ${warning}`));
+    });
+}
+function registerDiff(program) {
+    program
+        .command('diff')
+        .description('Unified DX diff entry for runtime, source, package, and composer preview')
+        .option('--mode <mode>', 'runtime | source | source-page | package | composer', 'runtime')
+        .option('--workspace <path>', 'Workspace root', '.')
+        .option('--env <name>', 'Environment descriptor name')
+        .option('--target-org <alias>', 'Target org alias override')
+        .option('--workspace-id <id>', 'Target workspace id override')
+        .option('--source <path>', 'Package directory for package diff')
+        .option('--against <path>', 'Compare package against another manifest')
+        .action(async (options) => {
+        if (options.mode === 'runtime') {
+            const { context } = (0, target_context_1.resolveTargetContext)({ workspaceDir: options.workspace, workspaceId: options.workspaceId, targetOrg: options.targetOrg, environmentName: options.env });
+            const client = (0, api_client_1.createApiClient)(context.targetOrg);
+            (0, target_context_1.printTargetSummary)(context);
+            const files = (0, source_tracker_1.readSourceFiles)(options.workspace);
+            const result = await client.diffRuntimeMetadata(files);
+            if (!result.validation.valid) {
+                result.validation.summary.forEach((line) => console.log(`  - ${line}`));
+                process.exit(1);
+            }
+            result.diff.humanSummary.forEach((line) => console.log(line));
+            return;
+        }
+        if (options.mode === 'source') {
+            const { context } = (0, target_context_1.resolveTargetContext)({ workspaceDir: options.workspace, workspaceId: options.workspaceId, targetOrg: options.targetOrg, environmentName: options.env });
+            const client = (0, api_client_1.createApiClient)(context.targetOrg);
+            (0, target_context_1.printTargetSummary)(context);
+            const sourceStatus = await client.getSourceStatus();
+            const files = (0, source_tracker_1.calculateSourceStatus)({
+                baseDir: options.workspace,
+                remoteFiles: sourceStatus.files,
+                baselineFiles: sourceStatus.baselineFiles,
+            });
+            files.forEach((entry) => {
+                if (entry.syncStatus !== 'synced' || entry.driftStatus === 'drifted') {
+                    console.log(`${entry.syncStatus} ${entry.path}`);
+                }
+            });
+            return;
+        }
+        if (options.mode === 'package') {
+            if (!options.source || !options.against) {
+                throw new Error('package diff requires --source and --against');
+            }
+            const current = (0, package_manifest_1.loadPackageManifest)(options.source).manifest;
+            const next = (0, package_manifest_1.loadPackageManifest)(options.against).manifest;
+            const removedMetadata = current.includedMetadataKinds.filter((kind) => !next.includedMetadataKinds.includes(kind));
+            const addedMetadata = next.includedMetadataKinds.filter((kind) => !current.includedMetadataKinds.includes(kind));
+            const removedSeeds = current.includedSeedKinds.filter((kind) => !next.includedSeedKinds.includes(kind));
+            const addedSeeds = next.includedSeedKinds.filter((kind) => !current.includedSeedKinds.includes(kind));
+            console.log(chalk_1.default.cyan(`${current.name} ${current.version} -> ${next.version}`));
+            console.log(`  metadata + ${addedMetadata.join(', ') || 'none'}`);
+            console.log(`  metadata - ${removedMetadata.join(', ') || 'none'}`);
+            console.log(`  seeds + ${addedSeeds.join(', ') || 'none'}`);
+            console.log(`  seeds - ${removedSeeds.join(', ') || 'none'}`);
+            return;
+        }
+        if (options.mode === 'composer') {
+            const { context } = (0, target_context_1.resolveTargetContext)({ workspaceDir: options.workspace, workspaceId: options.workspaceId, targetOrg: options.targetOrg, environmentName: options.env });
+            const client = (0, api_client_1.createApiClient)(context.targetOrg);
+            (0, target_context_1.printTargetSummary)(context);
+            const composer = (0, workspace_dx_1.buildRuntimeComposerInput)(options.workspace, options.env);
+            const result = await client.runtimeComposerPreview({
+                input: composer.input,
+                registryRootDirectories: composer.registryRootDirectories,
+            });
+            result.plan.orderedPackages.forEach((pkg) => {
+                console.log(`${pkg.packageType} ${pkg.packageName}@${pkg.version ?? 'latest'}`);
+            });
+            if (result.effective.diff.humanSummary.length > 0) {
+                console.log(chalk_1.default.cyan('\nDiff:'));
+                result.effective.diff.humanSummary.forEach((line) => console.log(`  - ${line}`));
+            }
+            if (result.effective.warnings.length > 0) {
+                console.log(chalk_1.default.yellow('\nWarnings:'));
+                result.effective.warnings.forEach((line) => console.log(`  - ${line}`));
+            }
+            return;
+        }
+        if (options.mode === 'source-page') {
+            const { context } = (0, target_context_1.resolveTargetContext)({ workspaceDir: options.workspace, workspaceId: options.workspaceId, targetOrg: options.targetOrg, environmentName: options.env });
+            const client = (0, api_client_1.createApiClient)(context.targetOrg);
+            (0, target_context_1.printTargetSummary)(context);
+            await dxDiffPages(options.workspace, client, context.workspaceId);
+            return;
+        }
+        throw new Error(`Unsupported diff mode: ${options.mode}`);
+    });
+}
+async function dxDiffPages(workspaceDir, client, workspaceId) {
+    const resolvedDir = path.resolve(workspaceDir);
+    const workspace = (0, workspace_contract_1.loadWorkspaceManifest)(resolvedDir);
+    const manifest = workspace.manifest;
+    const pageRoot = (0, dx_pages_1.findPagesSourceRoot)(manifest);
+    if (!pageRoot) {
+        console.log('Skipping pages diff: no source root declared for kind=pages.');
+        return [];
+    }
+    const pageRootAbsPath = path.resolve(workspace.workspaceRoot, pageRoot.path);
+    const localEntries = (0, page_source_file_1.scanPageSourceRoot)(pageRootAbsPath);
+    const localByApiName = new Map();
+    for (const entry of localEntries) {
+        const mainContent = fs.readFileSync(entry.main, 'utf-8');
+        const schemaContent = entry.sidecar ? fs.readFileSync(entry.sidecar, 'utf-8') : null;
+        const parsed = (0, page_source_file_1.parsePageSourceFile)({
+            mainContent,
+            schemaContent,
+            sourcePath: entry.main,
+        });
+        if (parsed.ok) {
+            localByApiName.set(entry.apiName, parsed.partial);
+        }
+    }
+    const query = `
+    query CustomPageSourceFiles($workspaceId: ID!) {
+      customPageSourceFiles(workspaceId: $workspaceId) {
+        apiName
+        mainFileName
+        mainContent
+        schemaFileName
+        schemaContent
+        remoteUpdatedAt
+      }
+    }
+  `;
+    const result = await client.graphql(query, { workspaceId });
+    const remoteByApiName = new Map();
+    for (const bundle of result.customPageSourceFiles) {
+        const parsed = (0, page_source_file_1.parsePageSourceFile)({
+            mainContent: bundle.mainContent,
+            schemaContent: bundle.schemaContent,
+            sourcePath: bundle.mainFileName,
+        });
+        if (parsed.ok) {
+            remoteByApiName.set(bundle.apiName, parsed.partial);
+        }
+    }
+    const allApiNames = new Set([...localByApiName.keys(), ...remoteByApiName.keys()]);
+    const diffEntries = [];
+    for (const apiName of allApiNames) {
+        const local = localByApiName.get(apiName);
+        const remote = remoteByApiName.get(apiName);
+        if (local && !remote) {
+            diffEntries.push({ apiName, status: 'added' });
+            console.log(chalk_1.default.green(`  added    ${apiName}`));
+        }
+        else if (!local && remote) {
+            diffEntries.push({ apiName, status: 'removed' });
+            console.log(chalk_1.default.red(`  removed  ${apiName}`));
+        }
+        else if (local && remote) {
+            const fieldDiffs = [];
+            let hasFieldDiff = false;
+            for (const field of page_source_file_2.DEPLOYABLE_FIELDS) {
+                if (field === 'schema')
+                    continue;
+                const localVal = local[field];
+                const remoteVal = remote[field];
+                if (!valuesEqual(localVal, remoteVal)) {
+                    fieldDiffs.push({ field, local: localVal, remote: remoteVal });
+                    hasFieldDiff = true;
+                }
+            }
+            const localSchema = local['schema'];
+            const remoteSchema = remote['schema'];
+            const schemaDiffs = (0, json_diff_1.jsonDiff)(remoteSchema ?? {}, localSchema ?? {});
+            if (hasFieldDiff || schemaDiffs.length > 0) {
+                const entry = { apiName, status: 'modified', fieldDiffs };
+                if (schemaDiffs.length > 0) {
+                    entry.schemaDiffs = schemaDiffs.map((d) => ({
+                        path: d.path,
+                        type: d.type,
+                        oldValue: d.oldValue,
+                        newValue: d.newValue,
+                    }));
+                }
+                diffEntries.push(entry);
+                console.log(chalk_1.default.yellow(`  modified ${apiName}`));
+                for (const fd of fieldDiffs) {
+                    console.log(`    field ${fd.field}: ${JSON.stringify(fd.remote)} → ${JSON.stringify(fd.local)}`);
+                }
+                for (const sd of schemaDiffs) {
+                    console.log(`    schema ${sd.type} ${sd.path}${sd.oldValue !== undefined ? `: ${JSON.stringify(sd.oldValue)}` : ''}${sd.newValue !== undefined ? ` → ${JSON.stringify(sd.newValue)}` : ''}`);
+                }
+            }
+            else {
+                diffEntries.push({ apiName, status: 'unchanged' });
+                console.log(chalk_1.default.gray(`  unchanged ${apiName}`));
+            }
+        }
+    }
+    const added = diffEntries.filter((e) => e.status === 'added').length;
+    const removed = diffEntries.filter((e) => e.status === 'removed').length;
+    const modified = diffEntries.filter((e) => e.status === 'modified').length;
+    const unchanged = diffEntries.filter((e) => e.status === 'unchanged').length;
+    console.log(`\nPages diff: added=${added} removed=${removed} modified=${modified} unchanged=${unchanged}`);
+    return diffEntries;
+}
+function valuesEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null)
+        return a === b;
+    if (typeof a !== typeof b)
+        return false;
+    if (typeof a === 'object') {
+        return JSON.stringify(a) === JSON.stringify(b);
+    }
+    return false;
+}
+function registerPull(program) {
+    program
+        .command('pull')
+        .description('Pull remote source changes using the workspace metadata roots contract')
+        .option('--workspace <path>', 'Workspace root', '.')
+        .option('--env <name>', 'Environment descriptor name')
+        .option('--target-org <alias>', 'Target org alias override')
+        .option('--workspace-id <id>', 'Target workspace id override')
+        .option('--force', 'Overwrite local conflicts', false)
+        .option('--kind <kind>', 'Filter by metadata kind (e.g. pages, *)', '*')
+        .option('--dry-run', 'Only print the plan without writing files', false)
+        .action(async (options) => {
+        const workspaceDir = path.resolve(options.workspace);
+        const workspace = (0, workspace_contract_1.loadWorkspaceManifest)(workspaceDir);
+        const { context } = (0, target_context_1.resolveTargetContext)({
+            workspaceDir: options.workspace,
+            workspaceId: options.workspaceId,
+            targetOrg: options.targetOrg,
+            environmentName: options.env,
+        });
+        const client = (0, api_client_1.createApiClient)(context.targetOrg);
+        (0, target_context_1.printTargetSummary)(context);
+        await (0, dx_pages_1.dxPullPages)({
+            workspaceRoot: workspace.workspaceRoot,
+            manifest: workspace.manifest,
+            client,
+            workspaceId: context.workspaceId,
+            kindFilter: options.kind,
+            dryRun: options.dryRun,
+        });
+        if (options.kind && options.kind !== '*' && options.kind !== 'source') {
+            return;
+        }
+        const sourceStatus = await client.getSourceStatus();
+        const statuses = (0, source_tracker_1.calculateSourceStatus)({
+            baseDir: options.workspace,
+            remoteFiles: sourceStatus.files,
+            baselineFiles: sourceStatus.baselineFiles,
+        });
+        const toPull = statuses.filter((entry) => ['remote-new', 'remote-changed', 'remote-delete'].includes(entry.syncStatus)
+            || (options.force && entry.syncStatus === 'conflict'));
+        const filePaths = toPull.filter((entry) => entry.remoteHash).map((entry) => entry.path);
+        const sourceFiles = filePaths.length > 0
+            ? await client.getSourceFiles({ paths: filePaths, recordAccess: true })
+            : { remoteRevision: sourceStatus.remoteRevision, files: [] };
+        const contentByPath = new Map(sourceFiles.files.map((file) => [file.path, file.content]));
+        if (!options.dryRun) {
+            for (const entry of toPull) {
+                if (!entry.remoteHash) {
+                    (0, source_tracker_1.deleteTrackedSourceFile)(options.workspace, entry.path);
+                    continue;
+                }
+                const content = contentByPath.get(entry.path);
+                if (typeof content !== 'string') {
+                    throw new Error(`Remote content missing for ${entry.path}`);
+                }
+                (0, source_tracker_1.writeTrackedSourceFile)(options.workspace, entry.path, content);
+            }
+            (0, source_tracker_1.syncTrackingWithStatus)({
+                baseDir: options.workspace,
+                status: sourceStatus,
+                targetPaths: toPull.map((entry) => entry.path),
+            });
+        }
+        console.log(`Pulled ${toPull.length} file(s).`);
+    });
+}
+function registerPromote(program) {
+    program
+        .command('promote')
+        .description('Promote a sandbox-backed environment using the environment descriptor contract')
+        .option('--workspace <path>', 'Workspace root', '.')
+        .option('--env <name>', 'Environment descriptor name')
+        .option('--sandbox-id <id>', 'Sandbox id override')
+        .option('--reason <reason>', 'Promotion reason override')
+        .action(async (options) => {
+        const { descriptor } = (0, workspace_contract_1.loadEnvironmentDescriptor)(options.workspace, options.env);
+        const { context } = (0, target_context_1.resolveTargetContext)({ workspaceDir: options.workspace, environmentName: options.env });
+        const workspaceId = context.workspaceId;
+        (0, target_context_1.printTargetSummary)(context);
+        if (descriptor.codePackages?.length) {
+            const client = (0, api_client_1.createApiClient)(context.targetOrg);
+            const packages = resolveCodePromotionPackages(options.workspace, descriptor.codePackages);
+            const result = await client.promoteCodeEnvironment({
+                targetWorkspaceId: workspaceId,
+                sourceEnvironment: descriptor.promotePolicy?.sourceEnvironment ?? descriptor.name,
+                runtimePolicyRef: descriptor.runtimePolicyRef ?? null,
+                allowPartialFailure: descriptor.promotePolicy?.allowPartialFailure ?? false,
+                reason: options.reason
+                    ?? descriptor.promotePolicy?.reason
+                    ?? `Promote ${descriptor.name}`,
+                packages,
+            });
+            console.log(chalk_1.default.cyan(`${result.success ? 'Promoted' : 'Promotion finished with issues'} ${result.targetWorkspaceId}`));
+            result.appliedPackages.forEach((pkg) => {
+                console.log(`  ${pkg.action} ${pkg.packageName}@${pkg.version} -> ${pkg.status}`);
+                pkg.warnings.forEach((warning) => console.log(`    - ${warning}`));
+            });
+            result.rollbackResults.forEach((rollback) => {
+                console.log(chalk_1.default.yellow(`  rollback ${rollback.packageName} -> ${rollback.status}`));
+                rollback.warnings.forEach((warning) => console.log(`    - ${warning}`));
+            });
+            result.errors.forEach((error) => console.log(chalk_1.default.red(`  - ${error}`)));
+            return;
+        }
+        const sandboxId = options.sandboxId
+            ?? descriptor.promotePolicy?.sandboxId
+            ?? descriptor.target.sandboxId;
+        if (!sandboxId) {
+            throw new Error('promote requires target.sandboxId or promotePolicy.sandboxId in the environment descriptor, or --sandbox-id');
+        }
+        const client = (0, api_client_1.createApiClient)(context.targetOrg);
+        const success = await client.promoteSandbox({
+            sandboxId,
+            promoteFrontend: descriptor.promotePolicy?.promoteFrontend ?? true,
+            promoteBackend: descriptor.promotePolicy?.promoteBackend ?? true,
+            reason: options.reason ?? descriptor.promotePolicy?.reason ?? `Promote ${descriptor.name}`,
+        });
+        console.log(success ? `Promoted sandbox ${sandboxId}.` : `Promotion request for sandbox ${sandboxId} did not complete.`);
+    });
+}
+function registerRollback(program) {
+    program
+        .command('rollback')
+        .description('Rollback a package install or deployment history through the existing audit-aware paths')
+        .option('--workspace <path>', 'Workspace root', '.')
+        .option('--env <name>', 'Environment descriptor name')
+        .option('--workspace-id <id>', 'Target workspace id override')
+        .option('--target-org <alias>', 'Target org alias override')
+        .option('--source <path>', 'Package directory or manifest path for package rollback')
+        .option('--history-id <id>', 'Deployment history id for deployment rollback or package rollback')
+        .action(async (options) => {
+        const { context } = (0, target_context_1.resolveTargetContext)({ workspaceDir: options.workspace, workspaceId: options.workspaceId, targetOrg: options.targetOrg, environmentName: options.env });
+        const client = (0, api_client_1.createApiClient)(context.targetOrg);
+        (0, target_context_1.printTargetSummary)(context);
+        if (options.source) {
+            const loaded = (0, package_manifest_1.loadPackageManifest)(options.source);
+            const workspaceId = context.workspaceId;
+            const result = await client.rollbackMetadataPackageInstall({
+                workspaceId,
+                manifest: loaded.manifest,
+                deploymentHistoryId: options.historyId,
+            });
+            console.log(chalk_1.default.cyan(`${result.packageName}`));
+            console.log(`  status: ${result.status}`);
+            result.warnings.forEach((warning) => console.log(`  - ${warning}`));
+            return;
+        }
+        if (options.historyId) {
+            const result = await client.rollbackDeployment({ historyId: options.historyId });
+            console.log(chalk_1.default.cyan(`rollback history ${result.id}`));
+            console.log(`  result: ${result.result ?? 'unknown'}`);
+            if (result.errorMessage) {
+                console.log(`  error: ${result.errorMessage}`);
+            }
+            return;
+        }
+        throw new Error('rollback requires either --source <package> or --history-id <deployment-history>');
+    });
+}
+function registerDxCommands(program) {
+    program.option('--debug', 'Enable debug output for per-page actions', false);
+    program.hook('preAction', (thisCommand) => {
+        const opts = thisCommand.opts();
+        if (opts.debug) {
+            (0, structured_error_1.setDebugEnabled)(true);
+        }
+    });
+    registerInit(program);
+    registerValidate(program);
+    registerPack(program);
+    registerPublish(program);
+    registerInstall(program);
+    registerDiff(program);
+    registerPull(program);
+    registerPromote(program);
+    registerRollback(program);
+}
+//# sourceMappingURL=dx.js.map