@lightdash/cli 0.3399.0 → 0.3400.0

package/dist/handlers/spacesAsCode.js

@@ -0,0 +1,603 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.upsertSpaces = exports.logUploadChanges = exports.isSpaceAsCodeUploadError = exports.createSpaceAsCodeUploadError = exports.downloadSpaces = exports.shouldFallBackToEmbeddedSpaces = exports.isSpaceAsCodeFetchError = exports.isSpaceAsCodeDownloadError = exports.createSpaceAsCodeDownloadError = exports.getSpaceNames = exports.readSpaceNames = exports.readSpaceFiles = exports.writeSpaceFiles = exports.getUniqueExistingSpaceFilePathsBySlug = exports.sortSpaceFilesParentFirst = exports.assertUniqueSpacePaths = exports.validateSpaceIdentity = exports.getFlatSpaceFileNames = void 0;
+const tslib_1 = require("tslib");
+/* eslint-disable no-await-in-loop */
+/* eslint-disable no-param-reassign */
+const common_1 = require("@lightdash/common");
+const crypto_1 = require("crypto");
+const fs_1 = require("fs");
+const yaml = tslib_1.__importStar(require("js-yaml"));
+const path = tslib_1.__importStar(require("path"));
+const globalState_1 = tslib_1.__importDefault(require("../globalState"));
+const styles = tslib_1.__importStar(require("../styles"));
+const appsDownload_1 = require("./apps/appsDownload");
+const contentAsCodePaths_1 = require("./contentAsCodePaths");
+const apiClient_1 = require("./dbt/apiClient");
+const SPACE_FILENAME_MAX_LENGTH = 200;
+const SPACE_FILENAME_HASH_LENGTH = 8;
+const isSpaceIdentity = (value) => typeof value === 'object' &&
+    value !== null &&
+    !Array.isArray(value) &&
+    'contentType' in value &&
+    value.contentType === common_1.ContentAsCodeType.SPACE &&
+    'slug' in value &&
+    typeof value.slug === 'string';
+const listSpaceFilePaths = async (baseDir) => (await fs_1.promises.readdir(baseDir, {
+    recursive: true,
+    withFileTypes: true,
+}))
+    .filter((entry) => entry.isFile() && entry.name.endsWith('.space.yml'))
+    .map((entry) => path.join(entry.parentPath, entry.name))
+    .sort((left, right) => left.localeCompare(right));
+const hasRootSpaceFile = async (baseDir) => {
+    try {
+        return (await fs_1.promises.readdir(baseDir, { withFileTypes: true })).some((entry) => entry.isFile() && entry.name.endsWith('.space.yml'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+};
+const getStableSpaceHash = (value, length = SPACE_FILENAME_HASH_LENGTH) => (0, crypto_1.createHash)('sha256').update(value).digest('hex').slice(0, length);
+const getSpaceFilenameBase = (space) => {
+    const normalizedName = space.spaceName
+        .normalize('NFKD')
+        .replace(/[\u0300-\u036f]/g, '');
+    const base = /[a-z0-9]/i.test(normalizedName)
+        ? (0, common_1.generateSlug)(normalizedName)
+        : `space-${getStableSpaceHash(space.slug)}`;
+    return base.slice(0, SPACE_FILENAME_MAX_LENGTH);
+};
+const getFlatSpaceFileNames = (spaces) => {
+    const bases = spaces.map(getSpaceFilenameBase);
+    const counts = bases.reduce((result, base) => result.set(base, (result.get(base) ?? 0) + 1), new Map());
+    return spaces.map((space, index) => {
+        const base = bases[index];
+        if ((counts.get(base) ?? 0) === 1)
+            return `${base}.space.yml`;
+        const suffix = `-${getStableSpaceHash(space.slug)}`;
+        return `${base.slice(0, SPACE_FILENAME_MAX_LENGTH - suffix.length)}${suffix}.space.yml`;
+    });
+};
+exports.getFlatSpaceFileNames = getFlatSpaceFileNames;
+const assertKnownKeys = (value, allowedKeys, field, filePath) => {
+    const unknownKeys = Object.keys(value).filter((key) => !allowedKeys.includes(key));
+    if (unknownKeys.length > 0) {
+        throw new common_1.ParameterError(`Invalid ${field} in space file "${filePath}": unknown ${unknownKeys.length === 1 ? 'property' : 'properties'} ${unknownKeys.map((key) => `"${key}"`).join(', ')}`);
+    }
+};
+const isSpaceMemberRole = (value) => Object.values(common_1.SpaceMemberRole).includes(value);
+const validateSpaceIdentity = (parsed, filePath) => {
+    if (typeof parsed !== 'object' ||
+        parsed === null ||
+        Array.isArray(parsed)) {
+        throw new common_1.ParameterError(`Invalid space file "${filePath}": expected a YAML object`);
+    }
+    assertKnownKeys(parsed, ['contentType', 'version', 'spaceName', 'slug', 'access'], 'space document', filePath);
+    if (!('contentType' in parsed) ||
+        parsed.contentType !== common_1.ContentAsCodeType.SPACE) {
+        throw new common_1.ParameterError(`Invalid contentType in space file "${filePath}": expected "${common_1.ContentAsCodeType.SPACE}"`);
+    }
+    if (!('spaceName' in parsed) ||
+        typeof parsed.spaceName !== 'string' ||
+        parsed.spaceName.trim().length === 0) {
+        throw new common_1.ParameterError(`Invalid spaceName in space file "${filePath}": expected a non-empty string`);
+    }
+    if (!('slug' in parsed) ||
+        typeof parsed.slug !== 'string' ||
+        parsed.slug.trim().length === 0 ||
+        parsed.slug !== parsed.slug.trim() ||
+        !/^[a-z0-9-]+(?:\/[a-z0-9-]+)*$/.test(parsed.slug) ||
+        (0, common_1.getContentAsCodePathFromLtreePath)((0, common_1.getLtreePathFromContentAsCodePath)(parsed.slug)) !== parsed.slug ||
+        parsed.slug
+            .split('/')
+            .some((part) => part.length === 0 || part === '.' || part === '..')) {
+        throw new common_1.ParameterError(`Invalid slug in space file "${filePath}": expected a canonical lowercase slash-separated path`);
+    }
+    if ('version' in parsed && parsed.version !== 1) {
+        throw new common_1.ParameterError(`Invalid version in space file "${filePath}": expected 1`);
+    }
+    if ('access' in parsed && parsed.access !== undefined) {
+        if (!('version' in parsed) || parsed.version !== 1) {
+            throw new common_1.ParameterError(`Invalid version in space file "${filePath}": version 1 is required when access is present`);
+        }
+        if (typeof parsed.access !== 'object' ||
+            parsed.access === null ||
+            Array.isArray(parsed.access)) {
+            throw new common_1.ParameterError(`Invalid access in space file "${filePath}": expected an object`);
+        }
+        const access = parsed.access;
+        assertKnownKeys(access, [
+            'inheritParentPermissions',
+            'projectMemberAccessRole',
+            'users',
+            'groups',
+        ], 'access', filePath);
+        if (typeof access.inheritParentPermissions !== 'boolean') {
+            throw new common_1.ParameterError(`Invalid access.inheritParentPermissions in space file "${filePath}": expected a boolean`);
+        }
+        if (access.projectMemberAccessRole !== null &&
+            !isSpaceMemberRole(access.projectMemberAccessRole)) {
+            throw new common_1.ParameterError(`Invalid access.projectMemberAccessRole in space file "${filePath}": expected viewer, editor, admin, or null`);
+        }
+        if (!Array.isArray(access.users) || !Array.isArray(access.groups)) {
+            throw new common_1.ParameterError(`Invalid access in space file "${filePath}": users and groups must be arrays`);
+        }
+        const userEmails = new Set();
+        const users = access.users.map((item, index) => {
+            if (typeof item !== 'object' ||
+                item === null ||
+                Array.isArray(item)) {
+                throw new common_1.ParameterError(`Invalid access.users[${index}] in space file "${filePath}": expected an object`);
+            }
+            const user = item;
+            assertKnownKeys(user, ['email', 'role'], `access.users[${index}]`, filePath);
+            if (typeof user.email !== 'string' ||
+                user.email.trim().length === 0 ||
+                !(0, common_1.validateEmail)(user.email.trim()) ||
+                !isSpaceMemberRole(user.role)) {
+                throw new common_1.ParameterError(`Invalid access.users[${index}] in space file "${filePath}": expected a valid email and a viewer, editor, or admin role`);
+            }
+            const email = user.email.trim().toLowerCase();
+            if (userEmails.has(email)) {
+                throw new common_1.ParameterError(`Duplicate user email "${email}" in space file "${filePath}"`);
+            }
+            userEmails.add(email);
+            return { email, role: user.role };
+        });
+        const groupNames = new Set();
+        const groups = access.groups.map((item, index) => {
+            if (typeof item !== 'object' ||
+                item === null ||
+                Array.isArray(item)) {
+                throw new common_1.ParameterError(`Invalid access.groups[${index}] in space file "${filePath}": expected an object`);
+            }
+            const group = item;
+            assertKnownKeys(group, ['name', 'role'], `access.groups[${index}]`, filePath);
+            if (typeof group.name !== 'string' ||
+                group.name.trim().length === 0 ||
+                !isSpaceMemberRole(group.role)) {
+                throw new common_1.ParameterError(`Invalid access.groups[${index}] in space file "${filePath}": expected a non-empty name and a viewer, editor, or admin role`);
+            }
+            if (groupNames.has(group.name)) {
+                throw new common_1.ParameterError(`Duplicate group name "${group.name}" in space file "${filePath}"`);
+            }
+            groupNames.add(group.name);
+            return { name: group.name, role: group.role };
+        });
+        return {
+            ...parsed,
+            access: {
+                inheritParentPermissions: access.inheritParentPermissions,
+                projectMemberAccessRole: access.projectMemberAccessRole,
+                users,
+                groups,
+            },
+        };
+    }
+    return parsed;
+};
+exports.validateSpaceIdentity = validateSpaceIdentity;
+const assertUniqueSpacePaths = (files) => {
+    const exactPaths = new Map();
+    const normalizedPaths = new Map();
+    files.forEach(({ filePath, space }) => {
+        const existingExact = exactPaths.get(space.slug);
+        if (existingExact) {
+            throw new common_1.ParameterError(`Duplicate space slug "${space.slug}" in "${existingExact}" and "${filePath}"`);
+        }
+        exactPaths.set(space.slug, filePath);
+        const normalizedPath = (0, common_1.getLtreePathFromContentAsCodePath)(space.slug);
+        const existingNormalized = normalizedPaths.get(normalizedPath);
+        if (existingNormalized) {
+            throw new common_1.ParameterError(`Space paths "${existingNormalized.slug}" (${existingNormalized.filePath}) and "${space.slug}" (${filePath}) resolve to the same normalized path "${normalizedPath}"`);
+        }
+        normalizedPaths.set(normalizedPath, { slug: space.slug, filePath });
+    });
+};
+exports.assertUniqueSpacePaths = assertUniqueSpacePaths;
+const sortSpaceFilesParentFirst = (files) => [...files].sort((left, right) => {
+    const depthDifference = left.space.slug.split('/').length -
+        right.space.slug.split('/').length;
+    return (depthDifference || left.space.slug.localeCompare(right.space.slug));
+});
+exports.sortSpaceFilesParentFirst = sortSpaceFilesParentFirst;
+const getExistingSpaceFileNames = async (outputDir) => {
+    let entries;
+    try {
+        entries = await fs_1.promises.readdir(outputDir, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return new Map();
+        }
+        throw error;
+    }
+    const filesBySlug = new Map();
+    for (const entry of entries.filter(({ name }) => name.endsWith('.space.yml'))) {
+        let slug = null;
+        if (entry.isFile()) {
+            try {
+                const parsed = yaml.load(await fs_1.promises.readFile(path.join(outputDir, entry.name), 'utf-8'));
+                if (isSpaceIdentity(parsed)) {
+                    slug = parsed.slug;
+                }
+            }
+            catch {
+                // An unreadable existing file still reserves its filename.
+            }
+        }
+        const ownerKey = slug ?? `\0${entry.name}`;
+        filesBySlug.set(ownerKey, [
+            ...(filesBySlug.get(ownerKey) ?? []),
+            entry.name,
+        ]);
+    }
+    return filesBySlug;
+};
+const getExistingSpaceFilePathsBySlug = async (baseDir) => {
+    let filePaths;
+    try {
+        filePaths = await listSpaceFilePaths(baseDir);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return new Map();
+        }
+        throw error;
+    }
+    const filesBySlug = new Map();
+    for (const filePath of filePaths) {
+        try {
+            const parsed = yaml.load(await fs_1.promises.readFile(filePath, 'utf-8'));
+            if (isSpaceIdentity(parsed)) {
+                filesBySlug.set(parsed.slug, [
+                    ...(filesBySlug.get(parsed.slug) ?? []),
+                    filePath,
+                ]);
+            }
+        }
+        catch {
+            // Filename allocation still reserves unreadable files in their directory.
+        }
+    }
+    return filesBySlug;
+};
+const getUniqueExistingSpaceFilePathsBySlug = async (baseDir) => {
+    const filesBySlug = await getExistingSpaceFilePathsBySlug(baseDir);
+    for (const [slug, filePaths] of filesBySlug) {
+        if (filePaths.length > 1) {
+            throw new common_1.ParameterError(`Multiple existing space files use slug "${slug}": ${filePaths
+                .map((filePath) => path.relative(baseDir, filePath))
+                .join(', ')}`);
+        }
+    }
+    return filesBySlug;
+};
+exports.getUniqueExistingSpaceFilePathsBySlug = getUniqueExistingSpaceFilePathsBySlug;
+const getCollisionSafeSpaceFileName = (space, usedFileNames) => {
+    const base = getSpaceFilenameBase(space);
+    const getCandidate = (suffix) => `${base.slice(0, SPACE_FILENAME_MAX_LENGTH - suffix.length)}${suffix}.space.yml`;
+    for (const hashLength of [8, 12, 16, 24, 32, 64]) {
+        const candidate = getCandidate(`-${getStableSpaceHash(space.slug, hashLength)}`);
+        if (!usedFileNames.has(candidate.toLowerCase()))
+            return candidate;
+    }
+    for (let index = 1; index <= 100; index += 1) {
+        const candidate = getCandidate(`-${getStableSpaceHash(space.slug, 64)}-${index}`);
+        if (!usedFileNames.has(candidate.toLowerCase()))
+            return candidate;
+    }
+    throw new common_1.ParameterError(`Could not allocate a safe filename for space "${space.slug}"`);
+};
+const allocateSpaceFileNames = async (spaces, outputDir, preferredFileNames) => {
+    const existingFilesBySlug = await getExistingSpaceFileNames(outputDir);
+    const usedFileNames = new Set([...existingFilesBySlug.values()]
+        .flat()
+        .map((fileName) => fileName.toLowerCase()));
+    return spaces.map((space, index) => {
+        const existingFileName = existingFilesBySlug.get(space.slug)?.[0];
+        if (existingFileName !== undefined)
+            return existingFileName;
+        const preferredFileName = preferredFileNames[index];
+        const fileName = !usedFileNames.has(preferredFileName.toLowerCase())
+            ? preferredFileName
+            : getCollisionSafeSpaceFileName(space, usedFileNames);
+        usedFileNames.add(fileName.toLowerCase());
+        return fileName;
+    });
+};
+/** Writes first-class space YAML files returned by GET /spaces/code. */
+const writeSpaceFiles = async (spaces, projectName, customPath, folderScheme = 'flat', flatSpaceLayout = 'folder', preserveExistingPolicy = false) => {
+    const baseDir = (0, contentAsCodePaths_1.getDownloadFolder)(customPath);
+    if (spaces.length === 0)
+        return;
+    const existingFilesBySlug = preserveExistingPolicy
+        ? await getExistingSpaceFilePathsBySlug(baseDir)
+        : await (0, exports.getUniqueExistingSpaceFilePathsBySlug)(baseDir);
+    if (preserveExistingPolicy) {
+        spaces.forEach(({ slug }) => {
+            const existingPaths = existingFilesBySlug.get(slug) ?? [];
+            if (existingPaths.length > 1) {
+                throw new common_1.ParameterError(`Multiple existing space files use slug "${slug}": ${existingPaths
+                    .map((filePath) => path.relative(baseDir, filePath))
+                    .join(', ')}`);
+            }
+        });
+    }
+    const files = spaces.map((space) => ({
+        filePath: `downloaded space "${space.slug}"`,
+        space,
+    }));
+    (0, exports.assertUniqueSpacePaths)(files);
+    const useRootFlatLayout = flatSpaceLayout === 'root' ||
+        (folderScheme === 'flat' && (await hasRootSpaceFile(baseDir)));
+    const plannedPathsBySlug = new Map();
+    const newSpacesByDirectory = new Map();
+    for (const space of spaces) {
+        const existingFilePath = existingFilesBySlug.get(space.slug)?.[0];
+        if (existingFilePath !== undefined) {
+            plannedPathsBySlug.set(space.slug, existingFilePath);
+        }
+        else {
+            let outputDir;
+            if (folderScheme === 'nested') {
+                outputDir = path.join(baseDir, projectName, space.slug);
+            }
+            else if (useRootFlatLayout) {
+                outputDir = baseDir;
+            }
+            else {
+                outputDir = path.join(baseDir, 'spaces');
+            }
+            newSpacesByDirectory.set(outputDir, [
+                ...(newSpacesByDirectory.get(outputDir) ?? []),
+                space,
+            ]);
+        }
+    }
+    for (const [outputDir, newSpaces] of [...newSpacesByDirectory].sort(([left], [right]) => left.localeCompare(right))) {
+        const fileNames = await allocateSpaceFileNames(newSpaces, outputDir, (0, exports.getFlatSpaceFileNames)(newSpaces));
+        newSpaces.forEach((space, index) => {
+            plannedPathsBySlug.set(space.slug, path.join(outputDir, fileNames[index]));
+        });
+    }
+    const plannedPaths = [...plannedPathsBySlug.values()].map((filePath) => filePath.toLowerCase());
+    if (new Set(plannedPaths).size !== plannedPaths.length) {
+        throw new common_1.ParameterError('Multiple spaces would be written to the same file path');
+    }
+    for (const space of spaces) {
+        const filePath = plannedPathsBySlug.get(space.slug);
+        if (filePath === undefined) {
+            throw new common_1.ParameterError(`Could not determine a filename for space "${space.slug}"`);
+        }
+        let spaceToWrite = space;
+        if (preserveExistingPolicy &&
+            space.access === undefined &&
+            existingFilesBySlug.has(space.slug)) {
+            const existing = yaml.load(await fs_1.promises.readFile(filePath, 'utf-8'));
+            if (typeof existing !== 'object' ||
+                existing === null ||
+                Array.isArray(existing) ||
+                !('contentType' in existing) ||
+                existing.contentType !== common_1.ContentAsCodeType.SPACE ||
+                !('slug' in existing) ||
+                existing.slug !== space.slug) {
+                throw new common_1.ParameterError(`Existing space file "${filePath}" changed while downloading`);
+            }
+            spaceToWrite = {
+                ...space,
+                ...('version' in existing ? { version: existing.version } : {}),
+                ...('access' in existing ? { access: existing.access } : {}),
+            };
+        }
+        await fs_1.promises.mkdir(path.dirname(filePath), { recursive: true });
+        await fs_1.promises.writeFile(filePath, yaml.dump(spaceToWrite, { quotingType: '"', sortKeys: true }));
+        globalState_1.default.debug(`Wrote space file: ${filePath}`);
+    }
+};
+exports.writeSpaceFiles = writeSpaceFiles;
+const readSpaceFiles = async (customPath) => {
+    const baseDir = (0, contentAsCodePaths_1.getDownloadFolder)(customPath);
+    try {
+        const files = [];
+        for (const filePath of await listSpaceFilePaths(baseDir)) {
+            let parsed;
+            try {
+                parsed = yaml.load(await fs_1.promises.readFile(filePath, 'utf-8'));
+            }
+            catch (error) {
+                throw new common_1.ParameterError(`Invalid YAML in space file "${filePath}": ${(0, common_1.getErrorMessage)(error)}`);
+            }
+            files.push({
+                filePath,
+                space: (0, exports.validateSpaceIdentity)(parsed, filePath),
+            });
+        }
+        (0, exports.assertUniqueSpacePaths)(files);
+        return (0, exports.sortSpaceFilesParentFirst)(files);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+};
+exports.readSpaceFiles = readSpaceFiles;
+/** Reads legacy identity fields without validating unrelated access policy. */
+const readSpaceNames = async (customPath) => {
+    const baseDir = (0, contentAsCodePaths_1.getDownloadFolder)(customPath);
+    const spaceNames = [];
+    try {
+        for (const filePath of await listSpaceFilePaths(baseDir)) {
+            try {
+                const parsed = yaml.load(await fs_1.promises.readFile(filePath, 'utf-8'));
+                if (isSpaceIdentity(parsed) &&
+                    'spaceName' in parsed &&
+                    typeof parsed.spaceName === 'string') {
+                    spaceNames.push([parsed.slug, parsed.spaceName]);
+                }
+            }
+            catch (error) {
+                globalState_1.default.debug(`Skipping space file ${path.basename(filePath)}: ${(0, common_1.getErrorMessage)(error)}`);
+            }
+        }
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            globalState_1.default.debug(`Skipping space names in ${baseDir}: ${(0, common_1.getErrorMessage)(error)}`);
+        }
+    }
+    return Object.fromEntries(spaceNames);
+};
+exports.readSpaceNames = readSpaceNames;
+const getSpaceNames = (files) => Object.fromEntries(files.map(({ space }) => [space.slug, space.spaceName]));
+exports.getSpaceNames = getSpaceNames;
+const getSpacePromoteAction = (action) => {
+    switch (action) {
+        case common_1.SpaceAsCodeAction.CREATE:
+            return 'created';
+        case common_1.SpaceAsCodeAction.UPDATE:
+            return 'updated';
+        case common_1.SpaceAsCodeAction.NO_CHANGES:
+            return 'unchanged';
+        default:
+            return (0, common_1.assertUnreachable)(action, `Unknown space promotion action: ${action}`);
+    }
+};
+const SPACE_AS_CODE_DOWNLOAD_ERROR_NAME = 'SpaceAsCodeDownloadError';
+const createSpaceAsCodeDownloadError = (message) => {
+    const error = new common_1.ParameterError(message);
+    error.name = SPACE_AS_CODE_DOWNLOAD_ERROR_NAME;
+    return error;
+};
+exports.createSpaceAsCodeDownloadError = createSpaceAsCodeDownloadError;
+const isSpaceAsCodeDownloadError = (error) => error instanceof Error && error.name === SPACE_AS_CODE_DOWNLOAD_ERROR_NAME;
+exports.isSpaceAsCodeDownloadError = isSpaceAsCodeDownloadError;
+const SPACE_AS_CODE_FETCH_ERROR_NAME = 'SpaceAsCodeFetchError';
+const createSpaceAsCodeFetchError = (message) => {
+    const error = new common_1.ParameterError(message);
+    error.name = SPACE_AS_CODE_FETCH_ERROR_NAME;
+    return error;
+};
+const isSpaceAsCodeFetchError = (error) => error instanceof Error && error.name === SPACE_AS_CODE_FETCH_ERROR_NAME;
+exports.isSpaceAsCodeFetchError = isSpaceAsCodeFetchError;
+const shouldFallBackToEmbeddedSpaces = (error, spacesOnly) => (0, exports.isSpaceAsCodeFetchError)(error) && spacesOnly !== true;
+exports.shouldFallBackToEmbeddedSpaces = shouldFallBackToEmbeddedSpaces;
+const downloadSpaces = async (projectId, projectName, customPath, nested = false, rootSpaces = false) => {
+    try {
+        await (0, exports.getUniqueExistingSpaceFilePathsBySlug)((0, contentAsCodePaths_1.getDownloadFolder)(customPath));
+        let results;
+        try {
+            results = await (0, apiClient_1.lightdashApi)({
+                method: 'GET',
+                url: `/api/v1/projects/${projectId}/spaces/code`,
+                body: undefined,
+            });
+        }
+        catch (error) {
+            throw createSpaceAsCodeFetchError((0, common_1.getErrorMessage)(error));
+        }
+        const downloadedWithoutAccessSlugs = new Set(results.spaces
+            .filter((space) => space.access === undefined)
+            .map((space) => space.slug));
+        results.skipped.forEach((skipped) => globalState_1.default.log(styles.warning(downloadedWithoutAccessSlugs.has(skipped.slug)
+            ? `Downloaded space "${skipped.slug}" without access: ${skipped.reason}`
+            : `Skipped space "${skipped.slug}": ${skipped.reason}`)));
+        const spaces = (0, exports.sortSpaceFilesParentFirst)(results.spaces.map((space) => ({
+            filePath: `downloaded space "${space.slug}"`,
+            space,
+        }))).map(({ space }) => space);
+        await (0, exports.writeSpaceFiles)(spaces, projectName, customPath, nested ? 'nested' : 'flat', rootSpaces ? 'root' : 'folder');
+        return spaces.length;
+    }
+    catch (error) {
+        if ((0, exports.isSpaceAsCodeFetchError)(error))
+            throw error;
+        throw (0, exports.createSpaceAsCodeDownloadError)((0, common_1.getErrorMessage)(error));
+    }
+};
+exports.downloadSpaces = downloadSpaces;
+const SPACE_AS_CODE_UPLOAD_ERROR_NAME = 'SpaceAsCodeUploadError';
+const createSpaceAsCodeUploadError = (message) => {
+    const error = new common_1.ParameterError(message);
+    error.name = SPACE_AS_CODE_UPLOAD_ERROR_NAME;
+    return error;
+};
+exports.createSpaceAsCodeUploadError = createSpaceAsCodeUploadError;
+const isSpaceAsCodeUploadError = (error) => error instanceof Error && error.name === SPACE_AS_CODE_UPLOAD_ERROR_NAME;
+exports.isSpaceAsCodeUploadError = isSpaceAsCodeUploadError;
+const logUploadChanges = (changes) => {
+    Object.entries(changes).forEach(([key, value]) => {
+        console.info(`Total ${key}: ${value} `);
+    });
+    if ((0, appsDownload_1.shouldWarnAllSkipped)(changes)) {
+        console.warn(styles.warning(`\nAll content was skipped (no local changes detected). Use --force to upload all content, e.g. when uploading to a new project.`));
+    }
+};
+exports.logUploadChanges = logUploadChanges;
+const upsertSpaces = async (projectId, files, changes, skipSpaceCreate, publicSpaceCreate) => {
+    if (files.length === 0)
+        return changes;
+    const failedPaths = new Set();
+    const skippedPaths = new Set();
+    for (const { filePath, space } of (0, exports.sortSpaceFilesParentFirst)(files)) {
+        const failedParent = [...failedPaths].find((failedPath) => space.slug.startsWith(`${failedPath}/`));
+        const skippedParent = [...skippedPaths].find((skippedPath) => space.slug.startsWith(`${skippedPath}/`));
+        if (failedParent !== undefined) {
+            changes['spaces dependency skipped'] =
+                (changes['spaces dependency skipped'] ?? 0) + 1;
+            failedPaths.add(space.slug);
+            globalState_1.default.log(styles.warning(`Skipped space "${space.slug}" (${filePath}) because parent "${failedParent}" failed`));
+        }
+        else if (skippedParent !== undefined) {
+            changes['spaces skipped'] = (changes['spaces skipped'] ?? 0) + 1;
+            skippedPaths.add(space.slug);
+            globalState_1.default.log(styles.warning(`Skipped space "${space.slug}" (${filePath}) because parent "${skippedParent}" does not exist and --skip-space-create is true`));
+        }
+        else {
+            try {
+                const params = new URLSearchParams({
+                    skipSpaceCreate: String(skipSpaceCreate),
+                    publicSpaceCreate: String(publicSpaceCreate && space.access === undefined),
+                });
+                const result = await (0, apiClient_1.lightdashApi)({
+                    method: 'POST',
+                    url: `/api/v1/projects/${projectId}/spaces/code?${params.toString()}`,
+                    body: JSON.stringify(space),
+                });
+                const action = getSpacePromoteAction(result.action);
+                const key = `spaces ${action}`;
+                changes[key] = (changes[key] ?? 0) + 1;
+                result.warnings?.forEach((warning) => globalState_1.default.log(styles.warning(`Space "${space.slug}" (${filePath}): ${warning}`)));
+                globalState_1.default.debug(`Space "${space.slug}" (${filePath}): ${result.action}`);
+            }
+            catch (error) {
+                if (skipSpaceCreate &&
+                    error instanceof common_1.LightdashError &&
+                    error.name === 'NotFoundError') {
+                    skippedPaths.add(space.slug);
+                    changes['spaces skipped'] =
+                        (changes['spaces skipped'] ?? 0) + 1;
+                    globalState_1.default.log(styles.warning(`Skipped space "${space.slug}" (${filePath}) because it does not exist and --skip-space-create is true`));
+                }
+                else {
+                    failedPaths.add(space.slug);
+                    changes['spaces with errors'] =
+                        (changes['spaces with errors'] ?? 0) + 1;
+                    globalState_1.default.log(styles.error(`Error upserting space "${space.slug}" (${filePath}): ${(0, common_1.getErrorMessage)(error)}`));
+                }
+            }
+        }
+    }
+    const failed = changes['spaces with errors'] ?? 0;
+    const dependencySkipped = changes['spaces dependency skipped'] ?? 0;
+    if (failed > 0 || dependencySkipped > 0) {
+        (0, exports.logUploadChanges)(changes);
+        throw (0, exports.createSpaceAsCodeUploadError)(`${failed} space definition(s) failed and ${dependencySkipped} dependent definition(s) were skipped; content upload was not started`);
+    }
+    return changes;
+};
+exports.upsertSpaces = upsertSpaces;

package/dist/index.js

@@ -353,8 +353,10 @@ const downloadCommand = commander_1.program
     .option('-l, --language-map', 'generate a language maps for the downloaded charts and dashboards', false)
     .option('-p, --path <path>', 'specify a custom path to download content', undefined)
     .option('--nested', 'organize downloads in nested folders by project and space (default: flat structure)', false)
+    .option('--root-spaces', 'write new flat space definitions at the content root instead of spaces/ (legacy layout)', false)
     .option('--project <project uuid>', 'specify a project UUID to download', parseProjectArgument, undefined)
-    .option('--skip-spaces', 'skip writing space metadata files during download', false)
+    .option('--skip-spaces', 'skip downloading space definitions and access', false)
+    .option('--spaces-only', 'download only space definitions and access', false)
     .option('--skip-charts', 'skip downloading charts', false)
     .option('--skip-dashboards', 'skip downloading dashboards', false)
     .option('--include-alerts', 'include all alerts in the download', false)
@@ -384,6 +386,8 @@ const uploadCommand = commander_1.program
     .option('-p, --path <path>', 'specify a custom path to upload content from', undefined)
     .option('--project <project uuid>', 'specify a project UUID to upload', parseProjectArgument, undefined)
     .option('--skip-space-create', 'Skip space creation if it does not exist', false)
+    .option('--skip-spaces', 'skip uploading space definitions and access', false)
+    .option('--spaces-only', 'upload only space definitions and access', false)
     .option('--public', 'Create new spaces as public instead of private', false)
     .option('--skip-agents', 'skip uploading AI agents', false)
     .option('--skip-alerts', 'skip uploading alerts', false)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightdash/cli",
-  "version": "0.3399.0",
+  "version": "0.3400.0",
   "description": "Lightdash CLI tool",
   "license": "MIT",
   "repository": {
@@ -41,8 +41,8 @@
     "unique-names-generator": "4.7.1",
     "uuid": "11.1.1",
     "yaml": "2.8.3",
-    "@lightdash/common": "0.3399.0",
-    "@lightdash/warehouses": "0.3399.0"
+    "@lightdash/common": "0.3400.0",
+    "@lightdash/warehouses": "0.3400.0"
   },
   "devDependencies": {
     "@types/inquirer": "8.2.4",