@nexusclawhq/cli 0.2.1

package/dist/nexus-cli/src/services/workspace-contract.js

@@ -0,0 +1,744 @@
+"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;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NEXUS_APP_REQUIRED_ROOTS = exports.NEXUS_APP_METADATA_ROOTS = exports.NEXUS_APP_SOURCE_ROOT = void 0;
+exports.findWorkspaceRoot = findWorkspaceRoot;
+exports.getWorkspaceManifestPath = getWorkspaceManifestPath;
+exports.validateWorkspaceManifest = validateWorkspaceManifest;
+exports.validateWorkspaceSourceLayout = validateWorkspaceSourceLayout;
+exports.loadWorkspaceManifest = loadWorkspaceManifest;
+exports.renderWorkspaceManifestYaml = renderWorkspaceManifestYaml;
+exports.saveWorkspaceManifest = saveWorkspaceManifest;
+exports.checkManifestSingleSource = checkManifestSingleSource;
+exports.syncWorkspaceManifestJson = syncWorkspaceManifestJson;
+exports.upsertWorkspacePackageRef = upsertWorkspacePackageRef;
+exports.removeWorkspacePackageRef = removeWorkspacePackageRef;
+exports.getMetadataSourceRoots = getMetadataSourceRoots;
+exports.getCodeSourceRoots = getCodeSourceRoots;
+exports.resolvePreferredMetadataRoot = resolvePreferredMetadataRoot;
+exports.resolvePhysicalSourcePath = resolvePhysicalSourcePath;
+exports.normalizeTrackedMetadataPath = normalizeTrackedMetadataPath;
+exports.loadEnvironmentDescriptor = loadEnvironmentDescriptor;
+exports.validateEnvironmentDescriptor = validateEnvironmentDescriptor;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const yaml = __importStar(require("js-yaml"));
+const WORKSPACE_MANIFEST_FILES = [
+    'nexus-project.yaml',
+    'nexus-project.yml',
+    'nexus-project.json',
+];
+exports.NEXUS_APP_SOURCE_ROOT = 'nexus-app/main/default';
+exports.NEXUS_APP_METADATA_ROOTS = [
+    'applications',
+    'tabs',
+    'objects',
+    'layouts',
+    'pages',
+    'nwc',
+    'classes',
+    'triggers',
+    'flows',
+    'permissionsets',
+    'profiles',
+    'permissionSetGroups',
+    'roles',
+    'groups',
+    'queues',
+    'labels',
+    'customMetadata',
+    'customSettings',
+    'staticresources',
+    'namedCredentials',
+    'remoteSiteSettings',
+    'notificationTemplates',
+    'isolated',
+];
+exports.NEXUS_APP_REQUIRED_ROOTS = [
+    'applications',
+    'tabs',
+    'objects',
+    'layouts',
+    'pages',
+    'nwc',
+    'classes',
+    'triggers',
+    'flows',
+    'permissionsets',
+    'profiles',
+];
+const DEFAULT_METADATA_ROOTS = [exports.NEXUS_APP_SOURCE_ROOT, 'src/metadata', 'metadata', '.'];
+const DEFAULT_CODE_ROOTS = [
+    'nexus-app/main/default/classes',
+    'nexus-app/main/default/triggers',
+    'nexus-app/main/default/nwc',
+    'nexus-app/main/default/isolated',
+    'src/functions',
+    'src/classes',
+    'src/triggers',
+    'src/components',
+    'src/tests',
+];
+const LEGACY_METADATA_ROOTS = [
+    'roles',
+    'apps',
+    'objects',
+    'fields',
+    'relationships',
+    'layouts',
+    'views',
+    'menus',
+    'dashboards',
+    'reports',
+    'actions',
+    'flows',
+    'approvals',
+    'prompts',
+    'agents',
+    'permissions',
+    'permissionsets',
+    'seed',
+];
+const FULL_METADATA_ROOTS = [...exports.NEXUS_APP_METADATA_ROOTS, ...LEGACY_METADATA_ROOTS];
+function parseStructuredFile(filePath) {
+    const content = fs.readFileSync(filePath, 'utf8');
+    if (filePath.endsWith('.json')) {
+        return JSON.parse(content);
+    }
+    return (yaml.load(content) ?? {});
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function normalizePathLike(value) {
+    const normalized = value.replace(/\\/g, '/').replace(/^\.?\//, '').replace(/\/$/, '');
+    return normalized.length === 0 ? '.' : normalized;
+}
+function inferSourceRootKind(rootPath) {
+    const normalized = normalizePathLike(rootPath);
+    if (normalized === exports.NEXUS_APP_SOURCE_ROOT
+        || normalized === 'metadata'
+        || normalized === 'src/metadata'
+        || normalized === '.'
+        || normalized.endsWith('/metadata')) {
+        return 'metadata-runtime';
+    }
+    if (normalized.startsWith('packages/')) {
+        return 'local-package';
+    }
+    return 'code-extension';
+}
+function normalizeSourceRoot(root) {
+    if (typeof root === 'string') {
+        const normalizedPath = normalizePathLike(root);
+        const kind = inferSourceRootKind(normalizedPath);
+        const isNexusAppSourceRoot = normalizedPath === exports.NEXUS_APP_SOURCE_ROOT;
+        return {
+            path: normalizedPath,
+            kind,
+            writeTarget: kind === 'metadata-runtime' && (isNexusAppSourceRoot || normalizedPath === 'src/metadata'),
+            metadataKinds: kind === 'metadata-runtime'
+                ? isNexusAppSourceRoot
+                    ? [...exports.NEXUS_APP_METADATA_ROOTS]
+                    : [...FULL_METADATA_ROOTS]
+                : undefined,
+        };
+    }
+    const normalizedPath = normalizePathLike(root.path);
+    const kind = root.kind ?? inferSourceRootKind(normalizedPath);
+    const isNexusAppSourceRoot = normalizedPath === exports.NEXUS_APP_SOURCE_ROOT;
+    return {
+        ...root,
+        path: normalizedPath,
+        kind,
+        writeTarget: root.writeTarget ?? (kind === 'metadata-runtime' && (isNexusAppSourceRoot || normalizedPath === 'src/metadata')),
+        metadataKinds: root.metadataKinds?.length
+            ? root.metadataKinds
+            : kind === 'metadata-runtime'
+                ? isNexusAppSourceRoot
+                    ? [...exports.NEXUS_APP_METADATA_ROOTS]
+                    : [...FULL_METADATA_ROOTS]
+                : undefined,
+    };
+}
+function normalizeLocalPackage(entry) {
+    if (typeof entry === 'string') {
+        return {
+            name: path.basename(entry),
+            path: normalizePathLike(entry),
+        };
+    }
+    return {
+        ...entry,
+        path: normalizePathLike(entry.path),
+    };
+}
+function normalizeEnvironmentRefs(value) {
+    if (!value) {
+        return [];
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry) => {
+            if (typeof entry === 'string') {
+                const normalizedPath = normalizePathLike(entry);
+                return {
+                    name: path.basename(normalizedPath).replace(/\.(ya?ml|json)$/i, ''),
+                    path: normalizedPath,
+                };
+            }
+            return {
+                name: entry.name,
+                path: normalizePathLike(entry.path),
+            };
+        });
+    }
+    return Object.entries(value).map(([name, filePath]) => ({
+        name,
+        path: normalizePathLike(filePath),
+    }));
+}
+function migrateLegacyManifest(candidate) {
+    const sourceRoots = Array.isArray(candidate.sourceRoots) && candidate.sourceRoots.length > 0
+        ? candidate.sourceRoots.map((root) => normalizeSourceRoot(root))
+        : candidate.sourceRoot
+            ? [normalizeSourceRoot(candidate.sourceRoot)]
+            : [
+                normalizeSourceRoot(exports.NEXUS_APP_SOURCE_ROOT),
+                ...DEFAULT_CODE_ROOTS.map((root) => normalizeSourceRoot(root)),
+            ];
+    const sourceDir = candidate.sourceDir;
+    if (sourceDir && !sourceRoots.some((root) => root.path === normalizePathLike(sourceDir))) {
+        sourceRoots.unshift(normalizeSourceRoot(sourceDir));
+    }
+    const localPackages = Array.isArray(candidate.localPackages)
+        ? candidate.localPackages.map((entry) => normalizeLocalPackage(entry))
+        : [];
+    const environments = normalizeEnvironmentRefs(candidate.environments);
+    return {
+        schemaVersion: candidate.schemaVersion === 'nexus-project/v2' ? 'nexus-project/v2' : 'dx-workspace/v1',
+        projectName: candidate.projectName ?? 'nexus-workspace',
+        apiVersion: candidate.apiVersion ?? '1.0',
+        compatibleCoreVersion: candidate.compatibleCoreVersion ?? '0.1.x',
+        packageDirectories: candidate.packageDirectories
+            ?.filter((entry) => typeof entry.path === 'string' && entry.path.trim().length > 0)
+            .map((entry) => ({
+            path: normalizePathLike(entry.path),
+            default: entry.default,
+        })),
+        sourceRoot: candidate.sourceRoot ? normalizePathLike(candidate.sourceRoot) : undefined,
+        sourceRoots,
+        localPackages,
+        registry: candidate.registry,
+        defaultOrg: candidate.defaultOrg ?? '',
+        defaultEnvironment: candidate.defaultEnvironment ?? (environments[0]?.name ?? 'dev'),
+        environments,
+        packageRefs: candidate.packageRefs ?? [],
+        starterTemplate: candidate.starterTemplate,
+        features: candidate.features ?? {},
+    };
+}
+function findWorkspaceRoot(startDir = '.') {
+    let current = path.resolve(startDir);
+    while (true) {
+        for (const fileName of WORKSPACE_MANIFEST_FILES) {
+            if (fs.existsSync(path.join(current, fileName))) {
+                return current;
+            }
+        }
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return path.resolve(startDir);
+        }
+        current = parent;
+    }
+}
+function getWorkspaceManifestPath(startDir = '.') {
+    const workspaceRoot = findWorkspaceRoot(startDir);
+    for (const fileName of WORKSPACE_MANIFEST_FILES) {
+        const filePath = path.join(workspaceRoot, fileName);
+        if (fs.existsSync(filePath)) {
+            return filePath;
+        }
+    }
+    return null;
+}
+function validateWorkspaceManifest(manifest) {
+    const errors = [];
+    const warnings = [];
+    if (!manifest.projectName?.trim()) {
+        errors.push('projectName is required');
+    }
+    if (!manifest.compatibleCoreVersion?.trim()) {
+        errors.push('compatibleCoreVersion is required');
+    }
+    if (!Array.isArray(manifest.sourceRoots) || manifest.sourceRoots.length === 0) {
+        errors.push('sourceRoots must declare at least one root');
+    }
+    else {
+        const seen = new Set();
+        for (const root of manifest.sourceRoots) {
+            if (!root.path?.trim()) {
+                errors.push('sourceRoots[].path is required');
+                continue;
+            }
+            if (seen.has(root.path)) {
+                errors.push(`duplicate sourceRoot path: ${root.path}`);
+            }
+            seen.add(root.path);
+            if (!root.kind) {
+                errors.push(`sourceRoots[${root.path}] is missing kind`);
+            }
+        }
+    }
+    if (!manifest.defaultEnvironment?.trim()) {
+        warnings.push('defaultEnvironment is empty; CLI aliases will require --env for environment-aware flows.');
+    }
+    else if (manifest.environments.length > 0
+        && !manifest.environments.some((entry) => entry.name === manifest.defaultEnvironment)) {
+        errors.push(`defaultEnvironment "${manifest.defaultEnvironment}" is not declared in environments`);
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+    };
+}
+function listChildDirectories(directoryPath) {
+    if (!fs.existsSync(directoryPath)) {
+        return [];
+    }
+    return fs.readdirSync(directoryPath, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && !entry.name.startsWith('.'))
+        .map((entry) => entry.name);
+}
+function listChildFiles(directoryPath) {
+    if (!fs.existsSync(directoryPath)) {
+        return [];
+    }
+    return fs.readdirSync(directoryPath, { withFileTypes: true })
+        .filter((entry) => entry.isFile() && !entry.name.startsWith('.'))
+        .map((entry) => entry.name);
+}
+function validateFilesWithSuffix(errors, workspaceRoot, relativeDirectory, suffix) {
+    const absoluteDirectory = path.join(workspaceRoot, relativeDirectory);
+    for (const fileName of listChildFiles(absoluteDirectory)) {
+        if (!fileName.endsWith(suffix)) {
+            errors.push(`${relativeDirectory}/${fileName} must use ${suffix}`);
+        }
+    }
+}
+function validateWorkspaceSourceLayout(workspaceRoot, manifest) {
+    const errors = [];
+    const warnings = [];
+    const canonicalRoot = manifest.sourceRoot
+        ? normalizePathLike(manifest.sourceRoot)
+        : manifest.sourceRoots.find((root) => root.path === exports.NEXUS_APP_SOURCE_ROOT)?.path;
+    if (canonicalRoot !== exports.NEXUS_APP_SOURCE_ROOT) {
+        warnings.push(`Workspace is using a legacy source layout; new projects should declare ${exports.NEXUS_APP_SOURCE_ROOT}.`);
+        return {
+            valid: true,
+            errors,
+            warnings,
+        };
+    }
+    const absoluteSourceRoot = path.join(workspaceRoot, exports.NEXUS_APP_SOURCE_ROOT);
+    if (!fs.existsSync(absoluteSourceRoot)) {
+        errors.push(`Missing canonical source root: ${exports.NEXUS_APP_SOURCE_ROOT}`);
+        return {
+            valid: false,
+            errors,
+            warnings,
+        };
+    }
+    for (const root of exports.NEXUS_APP_REQUIRED_ROOTS) {
+        const relativePath = path.posix.join(exports.NEXUS_APP_SOURCE_ROOT, root);
+        if (!fs.existsSync(path.join(workspaceRoot, relativePath))) {
+            errors.push(`Missing required Nexus App source directory: ${relativePath}`);
+        }
+    }
+    const nwcRoot = path.join(workspaceRoot, exports.NEXUS_APP_SOURCE_ROOT, 'nwc');
+    for (const componentName of listChildDirectories(nwcRoot)) {
+        const componentRelativePath = path.posix.join(exports.NEXUS_APP_SOURCE_ROOT, 'nwc', componentName);
+        const componentPath = path.join(workspaceRoot, componentRelativePath);
+        for (const requiredFile of [
+            `${componentName}.html`,
+            `${componentName}.js`,
+            `${componentName}.js-meta.xml`,
+        ]) {
+            if (!fs.existsSync(path.join(componentPath, requiredFile))) {
+                errors.push(`NWC ${componentName} is missing ${componentRelativePath}/${requiredFile}`);
+            }
+        }
+    }
+    const classesRoot = path.join(workspaceRoot, exports.NEXUS_APP_SOURCE_ROOT, 'classes');
+    for (const fileName of listChildFiles(classesRoot).filter((entry) => entry.endsWith('.npex'))) {
+        const baseName = fileName.replace(/\.npex$/, '');
+        const metaFile = `${baseName}.npex-meta.xml`;
+        if (!fs.existsSync(path.join(classesRoot, metaFile))) {
+            errors.push(`Npex class ${fileName} is missing ${exports.NEXUS_APP_SOURCE_ROOT}/classes/${metaFile}`);
+        }
+    }
+    const triggersRoot = path.join(workspaceRoot, exports.NEXUS_APP_SOURCE_ROOT, 'triggers');
+    for (const fileName of listChildFiles(triggersRoot).filter((entry) => entry.endsWith('.trigger'))) {
+        const baseName = fileName.replace(/\.trigger$/, '');
+        const metaFile = `${baseName}.trigger-meta.xml`;
+        if (!fs.existsSync(path.join(triggersRoot, metaFile))) {
+            errors.push(`Trigger ${fileName} is missing ${exports.NEXUS_APP_SOURCE_ROOT}/triggers/${metaFile}`);
+        }
+    }
+    const objectsRoot = path.join(workspaceRoot, exports.NEXUS_APP_SOURCE_ROOT, 'objects');
+    for (const objectApiName of listChildDirectories(objectsRoot)) {
+        const objectMetaPath = path.join(objectsRoot, objectApiName, `${objectApiName}.object-meta.xml`);
+        if (!fs.existsSync(objectMetaPath)) {
+            errors.push(`Object ${objectApiName} is missing ${exports.NEXUS_APP_SOURCE_ROOT}/objects/${objectApiName}/${objectApiName}.object-meta.xml`);
+        }
+    }
+    validateFilesWithSuffix(errors, workspaceRoot, `${exports.NEXUS_APP_SOURCE_ROOT}/applications`, '.app-meta.xml');
+    validateFilesWithSuffix(errors, workspaceRoot, `${exports.NEXUS_APP_SOURCE_ROOT}/tabs`, '.tab-meta.xml');
+    validateFilesWithSuffix(errors, workspaceRoot, `${exports.NEXUS_APP_SOURCE_ROOT}/layouts`, '.layout-meta.xml');
+    validateFilesWithSuffix(errors, workspaceRoot, `${exports.NEXUS_APP_SOURCE_ROOT}/pages`, '.page-meta.xml');
+    validateFilesWithSuffix(errors, workspaceRoot, `${exports.NEXUS_APP_SOURCE_ROOT}/flows`, '.flow-meta.xml');
+    validateFilesWithSuffix(errors, workspaceRoot, `${exports.NEXUS_APP_SOURCE_ROOT}/permissionsets`, '.permissionset-meta.xml');
+    validateFilesWithSuffix(errors, workspaceRoot, `${exports.NEXUS_APP_SOURCE_ROOT}/profiles`, '.profile-meta.xml');
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+    };
+}
+function loadWorkspaceManifest(startDir = '.') {
+    const manifestPath = getWorkspaceManifestPath(startDir);
+    const workspaceRoot = findWorkspaceRoot(startDir);
+    if (!manifestPath) {
+        const manifest = migrateLegacyManifest({
+            sourceRoots: ['.'],
+        });
+        return {
+            workspaceRoot,
+            manifestPath: path.join(workspaceRoot, 'nexus-project.yaml'),
+            format: 'yaml',
+            migrated: true,
+            warnings: ['Workspace manifest not found; using compatibility defaults.'],
+            manifest,
+        };
+    }
+    const raw = parseStructuredFile(manifestPath);
+    if (!isObject(raw)) {
+        throw new Error(`Workspace manifest ${manifestPath} must be an object`);
+    }
+    const migrated = !('schemaVersion' in raw)
+        || (raw.schemaVersion !== 'dx-workspace/v1' && raw.schemaVersion !== 'nexus-project/v2');
+    const manifest = migrateLegacyManifest(raw);
+    const validation = validateWorkspaceManifest(manifest);
+    const pagesRoots = manifest.sourceRoots.filter((root) => root.metadataKinds?.includes('pages'));
+    if (pagesRoots.length > 1) {
+        const conflictingPaths = pagesRoots.map((root) => root.path);
+        throw new Error(`Multiple source roots declare metadataKinds containing 'pages': [${conflictingPaths.join(', ')}]. `
+            + `Only one pages source root is allowed per workspace.`);
+    }
+    return {
+        workspaceRoot,
+        manifestPath,
+        format: manifestPath.endsWith('.json') ? 'json' : 'yaml',
+        migrated,
+        warnings: validation.warnings,
+        manifest,
+    };
+}
+function renderWorkspaceManifestYaml(manifest) {
+    return yaml.dump(manifest, {
+        noRefs: true,
+        sortKeys: false,
+        lineWidth: 120,
+    });
+}
+function saveWorkspaceManifest(workspaceRoot, manifest, preferredFormat = 'yaml') {
+    const yamlPath = path.join(workspaceRoot, 'nexus-project.yaml');
+    const jsonPath = path.join(workspaceRoot, 'nexus-project.json');
+    fs.writeFileSync(yamlPath, renderWorkspaceManifestYaml(manifest), 'utf8');
+    fs.writeFileSync(jsonPath, JSON.stringify(manifest, null, 2), 'utf8');
+    if (preferredFormat === 'json') {
+        return;
+    }
+}
+function canonicalManifestStringify(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map(canonicalManifestStringify).join(',')}]`;
+    }
+    if (value && typeof value === 'object') {
+        const entries = Object.entries(value)
+            .filter(([, v]) => v !== undefined)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalManifestStringify(v)}`).join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+function checkManifestSingleSource(workspaceRoot) {
+    const yamlPath = path.join(workspaceRoot, 'nexus-project.yaml');
+    const ymlPath = path.join(workspaceRoot, 'nexus-project.yml');
+    const jsonPath = path.join(workspaceRoot, 'nexus-project.json');
+    const yamlSource = fs.existsSync(yamlPath)
+        ? yamlPath
+        : fs.existsSync(ymlPath)
+            ? ymlPath
+            : null;
+    if (!yamlSource) {
+        return {
+            inSync: true,
+            yamlMissing: true,
+            jsonMissing: !fs.existsSync(jsonPath),
+            message: 'No nexus-project.yaml found; single-source drift check skipped.',
+        };
+    }
+    const yamlRaw = fs.readFileSync(yamlSource, 'utf8');
+    let yamlParsed;
+    try {
+        yamlParsed = yaml.load(yamlRaw);
+    }
+    catch (error) {
+        return {
+            inSync: false,
+            yamlMissing: false,
+            jsonMissing: false,
+            message: `nexus-project.yaml is not parseable: ${error.message}`,
+        };
+    }
+    const schemaVersion = yamlParsed && typeof yamlParsed === 'object' && 'schemaVersion' in yamlParsed
+        ? yamlParsed.schemaVersion
+        : undefined;
+    const isCanonicalV2 = schemaVersion === 'nexus-project/v2';
+    if (!fs.existsSync(jsonPath)) {
+        if (isCanonicalV2) {
+            return {
+                inSync: false,
+                yamlMissing: false,
+                jsonMissing: true,
+                message: 'nexus-project.json is missing. Run `nexus project sync-manifest --fix` to regenerate it from nexus-project.yaml.',
+            };
+        }
+        return {
+            inSync: true,
+            yamlMissing: false,
+            jsonMissing: true,
+            message: 'nexus-project.json projection is missing; regenerate it with `nexus project sync-manifest --fix` after migrating to nexus-project/v2.',
+        };
+    }
+    const jsonRaw = fs.readFileSync(jsonPath, 'utf8');
+    let jsonParsed;
+    try {
+        jsonParsed = JSON.parse(jsonRaw);
+    }
+    catch (error) {
+        return {
+            inSync: false,
+            yamlMissing: false,
+            jsonMissing: false,
+            message: `nexus-project.json is not parseable: ${error.message}`,
+        };
+    }
+    if (canonicalManifestStringify(yamlParsed) === canonicalManifestStringify(jsonParsed)) {
+        return {
+            inSync: true,
+            yamlMissing: false,
+            jsonMissing: false,
+            message: 'nexus-project.yaml and nexus-project.json are in sync.',
+        };
+    }
+    return {
+        inSync: false,
+        yamlMissing: false,
+        jsonMissing: false,
+        message: 'nexus-project.json has drifted from nexus-project.yaml. ' +
+            'Run `nexus project sync-manifest --fix` to regenerate the JSON projection from the canonical YAML.',
+    };
+}
+function syncWorkspaceManifestJson(workspaceRoot) {
+    const yamlPath = path.join(workspaceRoot, 'nexus-project.yaml');
+    const ymlPath = path.join(workspaceRoot, 'nexus-project.yml');
+    const source = fs.existsSync(yamlPath) ? yamlPath : fs.existsSync(ymlPath) ? ymlPath : null;
+    if (!source) {
+        throw new Error('nexus-project.yaml not found; nothing to sync from.');
+    }
+    const raw = fs.readFileSync(source, 'utf8');
+    let parsed;
+    try {
+        parsed = yaml.load(raw);
+    }
+    catch (error) {
+        throw new Error(`nexus-project.yaml is not parseable: ${error.message}`);
+    }
+    const jsonPath = path.join(workspaceRoot, 'nexus-project.json');
+    fs.writeFileSync(jsonPath, `${JSON.stringify(parsed, null, 2)}\n`, 'utf8');
+    return { yamlPath: source, jsonPath };
+}
+function normalizePackageRef(packageRef) {
+    if (typeof packageRef !== 'string') {
+        return packageRef;
+    }
+    const [packageName, version] = packageRef.split('@');
+    return {
+        packageName,
+        version: version || undefined,
+    };
+}
+function upsertWorkspacePackageRef(startDir, packageRef) {
+    const loaded = loadWorkspaceManifest(startDir);
+    const packageRefs = (loaded.manifest.packageRefs ?? []).map((entry) => normalizePackageRef(entry));
+    const nextRefs = packageRefs.filter((entry) => entry.packageName !== packageRef.packageName);
+    nextRefs.push(packageRef);
+    nextRefs.sort((left, right) => left.packageName.localeCompare(right.packageName));
+    loaded.manifest.packageRefs = nextRefs.map((entry) => ({
+        packageName: entry.packageName,
+        version: entry.version,
+        packageType: entry.packageType,
+        source: entry.source,
+        directory: entry.directory,
+    }));
+    saveWorkspaceManifest(loaded.workspaceRoot, loaded.manifest, loaded.format);
+    return loaded.manifest;
+}
+function removeWorkspacePackageRef(startDir, packageName) {
+    const loaded = loadWorkspaceManifest(startDir);
+    loaded.manifest.packageRefs = (loaded.manifest.packageRefs ?? [])
+        .map((entry) => normalizePackageRef(entry))
+        .filter((entry) => entry.packageName !== packageName);
+    saveWorkspaceManifest(loaded.workspaceRoot, loaded.manifest, loaded.format);
+    return loaded.manifest;
+}
+function getMetadataSourceRoots(startDir = '.') {
+    const { manifest } = loadWorkspaceManifest(startDir);
+    const metadataRoots = manifest.sourceRoots.filter((root) => root.kind === 'metadata-runtime');
+    return metadataRoots.length > 0
+        ? metadataRoots
+        : DEFAULT_METADATA_ROOTS.map((rootPath) => normalizeSourceRoot(rootPath));
+}
+function getCodeSourceRoots(startDir = '.') {
+    const { manifest } = loadWorkspaceManifest(startDir);
+    const codeRoots = manifest.sourceRoots.filter((root) => root.kind === 'code-extension');
+    return codeRoots.length > 0
+        ? codeRoots
+        : DEFAULT_CODE_ROOTS.map((rootPath) => normalizeSourceRoot(rootPath));
+}
+function resolvePreferredMetadataRoot(startDir = '.') {
+    const workspaceRoot = findWorkspaceRoot(startDir);
+    const metadataRoots = getMetadataSourceRoots(workspaceRoot);
+    const declaredTarget = metadataRoots.find((root) => root.writeTarget);
+    if (declaredTarget) {
+        return declaredTarget;
+    }
+    const existing = metadataRoots.find((root) => fs.existsSync(path.join(workspaceRoot, root.path === '.' ? '' : root.path)));
+    return existing ?? normalizeSourceRoot(exports.NEXUS_APP_SOURCE_ROOT);
+}
+function resolvePhysicalSourcePath(workspaceRoot, trackedPath, preferredRoot) {
+    const root = preferredRoot ?? resolvePreferredMetadataRoot(workspaceRoot);
+    return path.join(workspaceRoot, root.path === '.' ? trackedPath : path.join(root.path, trackedPath));
+}
+function normalizeTrackedMetadataPath(workspaceRoot, absolutePath) {
+    const normalizedAbsolute = absolutePath.replace(/\\/g, '/');
+    for (const root of getMetadataSourceRoots(workspaceRoot)) {
+        const prefix = root.path === '.'
+            ? `${workspaceRoot.replace(/\\/g, '/')}/`
+            : `${path.join(workspaceRoot, root.path).replace(/\\/g, '/')}/`;
+        if (normalizedAbsolute.startsWith(prefix)) {
+            return normalizedAbsolute.slice(prefix.length);
+        }
+    }
+    return null;
+}
+function loadEnvironmentDescriptor(startDir = '.', environmentNameOrPath) {
+    const { workspaceRoot, manifest } = loadWorkspaceManifest(startDir);
+    const directPath = environmentNameOrPath
+        ? path.resolve(workspaceRoot, environmentNameOrPath)
+        : null;
+    const candidatePath = directPath && fs.existsSync(directPath)
+        ? directPath
+        : (() => {
+            const defaultName = environmentNameOrPath ?? manifest.defaultEnvironment;
+            const fromManifest = manifest.environments.find((entry) => entry.name === defaultName);
+            if (fromManifest) {
+                return path.join(workspaceRoot, fromManifest.path);
+            }
+            if (!defaultName) {
+                return null;
+            }
+            for (const extension of ['yaml', 'yml', 'json']) {
+                const guessed = path.join(workspaceRoot, 'env', `${defaultName}.${extension}`);
+                if (fs.existsSync(guessed)) {
+                    return guessed;
+                }
+            }
+            return null;
+        })();
+    if (!candidatePath || !fs.existsSync(candidatePath)) {
+        throw new Error(`Environment descriptor "${environmentNameOrPath ?? manifest.defaultEnvironment ?? 'default'}" was not found.`);
+    }
+    const raw = parseStructuredFile(candidatePath);
+    if (!isObject(raw)) {
+        throw new Error(`Environment descriptor ${candidatePath} must be an object`);
+    }
+    const descriptor = raw;
+    if (descriptor.schemaVersion !== 'dx-environment/v1') {
+        throw new Error(`Unsupported environment descriptor schemaVersion "${String(descriptor.schemaVersion)}"`);
+    }
+    return {
+        descriptorPath: candidatePath,
+        descriptor,
+    };
+}
+function validateEnvironmentDescriptor(descriptor) {
+    const errors = [];
+    const warnings = [];
+    if (!descriptor.name?.trim()) {
+        errors.push('environment.name is required');
+    }
+    if (!descriptor.packageStack?.baseline?.packageName) {
+        errors.push('environment.packageStack.baseline.packageName is required');
+    }
+    if (descriptor.codePackages && !Array.isArray(descriptor.codePackages)) {
+        errors.push('environment.codePackages must be an array when declared');
+    }
+    if (!descriptor.target?.workspaceId && !descriptor.target?.orgAlias && !descriptor.target?.sandboxId) {
+        warnings.push('environment.target has no workspaceId/orgAlias/sandboxId; remote install flows may require overrides.');
+    }
+    if (descriptor.runtimePolicyRef && !descriptor.runtimePolicyRef.trim()) {
+        errors.push('environment.runtimePolicyRef must not be empty when declared');
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+    };
+}
+//# sourceMappingURL=workspace-contract.js.map