@lightdash/cli 0.3399.1 → 0.3400.0

package/dist/handlers/download.d.ts

@@ -1,4 +1,5 @@
 import { AgentAsCode, ChartAsCode, DashboardAsCode, type SpaceAsCode } from '@lightdash/common';
+import { type SpaceCodeFile } from './spacesAsCode';
 export type DownloadHandlerOptions = {
     verbose: boolean;
     charts: string[];
@@ -21,7 +22,9 @@ export type DownloadHandlerOptions = {
     public: boolean;
     includeCharts: boolean;
     nested: boolean;
+    rootSpaces: boolean;
     skipSpaces: boolean;
+    spacesOnly?: boolean;
     skipCharts: boolean;
     skipDashboards: boolean;
     skipAlerts: boolean;
@@ -48,17 +51,27 @@ type MetadataEntry = {
     downloadedAt: string;
 };
 type DownloadContentType = 'charts' | 'dashboards' | 'sqlCharts';
-export declare const downloadContent: (ids: string[], type: DownloadContentType, projectId: string, projectName: string, customPath?: string, languageMap?: boolean, nested?: boolean, skipSpaces?: boolean, stripPivotSeries?: boolean) => Promise<[number, string[], MetadataEntry[], SpaceAsCode[]]>;
+export declare const downloadContent: (ids: string[], type: DownloadContentType, projectId: string, projectName: string, customPath?: string, languageMap?: boolean, nested?: boolean, skipSpaces?: boolean, stripPivotSeries?: boolean, rootSpaces?: boolean) => Promise<[number, string[], MetadataEntry[], SpaceAsCode[]]>;
 export declare const downloadHandler: (options: DownloadHandlerOptions) => Promise<void>;
 export declare const uploadHandler: (options: DownloadHandlerOptions) => Promise<void>;
 export declare const testHelpers: {
+    assertUniqueSpacePaths: (files: SpaceCodeFile[]) => void;
+    downloadSpaces: (projectId: string, projectName: string, customPath?: string, nested?: boolean, rootSpaces?: boolean) => Promise<number>;
+    getFlatSpaceFileNames: (spaces: SpaceAsCode[]) => string[];
     getDashboardChartSlugs: (dashboardSlugs: string[], customPath?: string, looseDashboards?: (DashboardAsCode & {
         needsUpdating: boolean;
     })[]) => Promise<string[]>;
     readAiAgentFiles: (customPath?: string) => Promise<AgentAsCode[]>;
+    readSpaceFiles: (customPath?: string) => Promise<SpaceCodeFile[]>;
+    readSpaceNames: (customPath?: string) => Promise<Record<string, string>>;
     sanitizeChartForDownload: (chart: ChartAsCode, stripPivotSeries: boolean) => ChartAsCode;
+    shouldFallBackToEmbeddedSpaces: (error: unknown, spacesOnly: boolean | undefined) => boolean;
     shouldDownloadAiAgents: ({ includeAll, includeAgents, agents, appsOnly, }: Pick<DownloadHandlerOptions, "includeAll" | "includeAgents" | "agents" | "appsOnly">) => boolean;
+    sortSpaceFilesParentFirst: (files: SpaceCodeFile[]) => SpaceCodeFile[];
+    upsertSpaces: (projectId: string, files: SpaceCodeFile[], changes: Record<string, number>, skipSpaceCreate: boolean, publicSpaceCreate: boolean) => Promise<Record<string, number>>;
     upsertVirtualViews: (projectId: string, slugs: string[], changes: Record<string, number>, force: boolean, canUpload: boolean, customPath?: string) => Promise<Record<string, number>>;
+    validateSpaceIdentity: (parsed: unknown, filePath: string) => SpaceAsCode;
+    writeSpaceFiles: (spaces: SpaceAsCode[], projectName: string, customPath?: string, folderScheme?: "flat" | "nested", flatSpaceLayout?: "folder" | "root", preserveExistingPolicy?: boolean) => Promise<void>;
 };
 export {};
 //# sourceMappingURL=download.d.ts.map

package/dist/handlers/download.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"download.d.ts","sourceRoot":"","sources":["../../src/handlers/download.ts"],"names":[],"mappings":"AAEA,OAAO,EACH,WAAW,EAuBX,WAAW,EAGX,eAAe,EAef,KAAK,WAAW,EACnB,MAAM,mBAAmB,CAAC;AA8D3B,MAAM,MAAM,sBAAsB,GAAG;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,OAAO,CAAC;IACrB,eAAe,EAAE,OAAO,CAAC;IACzB,MAAM,EAAE,OAAO,CAAC;IAChB,aAAa,EAAE,OAAO,CAAC;IACvB,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,cAAc,EAAE,OAAO,CAAC;IACxB,UAAU,EAAE,OAAO,CAAC;IACpB,UAAU,EAAE,OAAO,CAAC;IACpB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,uBAAuB,EAAE,OAAO,CAAC;IACjC,gBAAgB,EAAE,OAAO,CAAC;IAC1B,aAAa,EAAE,OAAO,CAAC;IACvB,mBAAmB,EAAE,OAAO,CAAC;IAC7B,0BAA0B,EAAE,OAAO,CAAC;IACpC,mBAAmB,EAAE,OAAO,CAAC;IAC7B,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,gBAAgB,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,YAAY,EAAE,OAAO,CAAC;IACtB,WAAW,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AA8FF,KAAK,aAAa,GAAG;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,QAAQ,GAAG,YAAY,CAAC;IAC9B,YAAY,EAAE,MAAM,CAAC;CACxB,CAAC;AA8cF,KAAK,mBAAmB,GAAG,QAAQ,GAAG,YAAY,GAAG,WAAW,CAAC;AAkDjE,eAAO,MAAM,eAAe,GACxB,KAAK,MAAM,EAAE,EACb,MAAM,mBAAmB,EACzB,WAAW,MAAM,EACjB,aAAa,MAAM,EACnB,aAAa,MAAM,EACnB,cAAa,OAAe,EAC5B,SAAQ,OAAe,EACvB,aAAY,OAAe,EAC3B,mBAAkB,OAAe,KAClC,OAAO,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,aAAa,EAAE,EAAE,WAAW,EAAE,CAAC,CA6H5D,CAAC;AA4hBF,eAAO,MAAM,eAAe,GACxB,SAAS,sBAAsB,KAChC,OAAO,CAAC,IAAI,CAuhBd,CAAC;AA8aF,eAAO,MAAM,aAAa,GACtB,SAAS,sBAAsB,KAChC,OAAO,CAAC,IAAI,CAmnBd,CAAC;AAEF,eAAO,MAAM,WAAW;6CAxpBJ,MAAM,EAAE,eACX,MAAM,oBACF,CAAC,eAAe,GAAG;QAAE,aAAa,EAAE,OAAO,CAAA;KAAE,CAAC,EAAE;oCA1rCpD,MAAM,KACpB,OAAO,CAAC,WAAW,EAAE,CAAC;sCA/4Bd,WAAW,oBACA,OAAO,KAC1B,WAAW;+EA9FX,IAAI,CACH,sBAAsB,EACtB,YAAY,GAAG,eAAe,GAAG,QAAQ,GAAG,UAAU,CACzD,KAAG,OAAO;oCAy0BI,MAAM,SACV,MAAM,EAAE,WACN,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,SACxB,OAAO,aACH,OAAO,eACL,MAAM,KACpB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CA8+DjC,CAAC"}
+{"version":3,"file":"download.d.ts","sourceRoot":"","sources":["../../src/handlers/download.ts"],"names":[],"mappings":"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"}

package/dist/handlers/download.js

@@ -24,6 +24,7 @@ const apiClient_1 = require("./dbt/apiClient");
 const metadataFile_1 = require("./metadataFile");
 const organizationContent_1 = require("./organizationContent");
 const selectProject_1 = require("./selectProject");
+const spacesAsCode_1 = require("./spacesAsCode");
 const shouldDownloadAiAgents = ({ includeAll, includeAgents, agents, appsOnly, }) => appsOnly !== true &&
     (includeAll === true || includeAgents === true || agents.length > 0);
 /*
@@ -110,76 +111,21 @@ const writeContent = async (contentAsCode, outputDir, languageMap, stripPivotSer
         downloadedAt: downloadedAtString,
     };
 };
-/**
- * Writes space YAML files for each space in the download results.
- * In flat mode, files go in the base download directory.
- * In nested mode, files go in the root of each space's directory.
- */
-const writeSpaceFiles = async (spaces, projectName, customPath, folderScheme = 'flat') => {
-    if (spaces.length === 0)
-        return;
-    const baseDir = (0, contentAsCodePaths_1.getDownloadFolder)(customPath);
-    const seen = new Set();
-    for (const space of spaces) {
-        // Deduplicate across paginated API responses
-        if (!seen.has(space.slug)) {
-            seen.add(space.slug);
-            let outputDir;
-            if (folderScheme === 'nested') {
-                outputDir = path.join(baseDir, projectName, space.slug);
-            }
-            else {
-                outputDir = baseDir;
-            }
-            await fs_1.promises.mkdir(outputDir, { recursive: true });
-            const fileName = `${(0, common_1.generateSlug)(space.spaceName)}.space.yml`;
-            const filePath = path.join(outputDir, fileName);
-            const content = yaml.dump(space, {
-                quotingType: '"',
-                sortKeys: true,
-            });
-            await fs_1.promises.writeFile(filePath, content);
-            globalState_1.default.debug(`Wrote space file: ${filePath}`);
-        }
-    }
-};
-/**
- * Reads all .space.yml files from the download directory and returns
- * a map of space slug → original space name. Used during upload to
- * preserve human-readable space names instead of deriving them from slugs.
- */
-const readSpaceNames = async (customPath) => {
-    const baseDir = (0, contentAsCodePaths_1.getDownloadFolder)(customPath);
-    const spaceNames = {};
-    try {
-        const allEntries = await fs_1.promises.readdir(baseDir, {
-            recursive: true,
-            withFileTypes: true,
-        });
-        await Promise.all(allEntries
-            .filter((entry) => entry.isFile() && entry.name.endsWith('.space.yml'))
-            .map(async (file) => {
-            try {
-                const filePath = path.join(file.parentPath, file.name);
-                const fileContent = await fs_1.promises.readFile(filePath, 'utf-8');
-                const parsed = yaml.load(fileContent);
-                if (parsed?.contentType ===
-                    common_1.ContentAsCodeType.SPACE &&
-                    typeof parsed.slug === 'string' &&
-                    typeof parsed.spaceName === 'string') {
-                    spaceNames[parsed.slug] = parsed.spaceName;
-                }
-            }
-            catch (e) {
-                globalState_1.default.debug(`Skipping space file ${file.name}: ${(0, common_1.getErrorMessage)(e)}`);
-            }
-        }));
-    }
-    catch {
-        // Directory doesn't exist or can't be read — return empty map
+function getPromoteAction(action) {
+    switch (action) {
+        case common_1.PromotionAction.CREATE:
+            return 'created';
+        case common_1.PromotionAction.UPDATE:
+            return 'updated';
+        case common_1.PromotionAction.DELETE:
+            return 'deleted';
+        case common_1.PromotionAction.NO_CHANGES:
+            return 'skipped';
+        default:
+            (0, common_1.assertUnreachable)(action, `Unknown promotion action: ${action}`);
     }
-    return spaceNames;
-};
+    return 'skipped';
+}
 const hasUnsortedKeys = (obj) => {
     if (typeof obj !== 'object' || obj === null || Array.isArray(obj)) {
         if (Array.isArray(obj)) {
@@ -198,6 +144,7 @@ const isLightdashContentFile = (folder, entry) => entry.isFile() &&
     entry.parentPath &&
     entry.parentPath.endsWith(path.sep + folder) &&
     entry.name.endsWith('.yml') &&
+    !entry.name.endsWith('.space.yml') &&
     !entry.name.endsWith('.language.map.yml');
 const isLooseContentFile = (entry) => entry.isFile() &&
     entry.parentPath &&
@@ -297,7 +244,7 @@ const readLooseCodeFiles = async (customPath) => {
                     dashboards.push(processYamlItem(parsed, file.name, stats, 'dashboards', metadata));
                 }
                 else if (contentType === common_1.ContentAsCodeType.SPACE) {
-                    // Space YAML files are metadata-only until the next PR
+                    // Space files are handled by the dedicated space phase.
                 }
                 else {
                     globalState_1.default.debug(`Skipping ${file.name}: no recognized contentType`);
@@ -369,7 +316,7 @@ const extractChartSlugsFromDashboards = (dashboards) => dashboards.reduce((acc,
         .filter((slug) => slug !== undefined);
     return [...acc, ...slugs];
 }, []);
-const downloadContent = async (ids, type, projectId, projectName, customPath, languageMap = false, nested = false, skipSpaces = false, stripPivotSeries = false) => {
+const downloadContent = async (ids, type, projectId, projectName, customPath, languageMap = false, nested = false, skipSpaces = false, stripPivotSeries = false, rootSpaces = false) => {
     const spinner = globalState_1.default.getActiveSpinner();
     const contentFilters = parseContentFilters(ids);
     const folderScheme = nested ? 'nested' : 'flat';
@@ -466,7 +413,10 @@ const downloadContent = async (ids, type, projectId, projectName, customPath, la
     } while (offset < total);
     // Write space YAML files
     if (!skipSpaces) {
-        await writeSpaceFiles(allSpaces, projectName, customPath, folderScheme);
+        const uniqueSpaces = [
+            ...new Map(allSpaces.map((space) => [space.slug, space])).values(),
+        ];
+        await (0, spacesAsCode_1.writeSpaceFiles)(uniqueSpaces, projectName, customPath, folderScheme, rootSpaces ? 'root' : 'folder', true);
     }
     return [total, [...new Set(chartSlugs)], allMetadataEntries, allSpaces];
 };
@@ -476,21 +426,6 @@ const getAiAgentsFolder = (customPath) => path.join((0, contentAsCodePaths_1.get
 const getAlertsFolder = (customPath) => path.join((0, contentAsCodePaths_1.getDownloadFolder)(customPath), 'alerts');
 const getGoogleSheetsFolder = (customPath) => path.join((0, contentAsCodePaths_1.getDownloadFolder)(customPath), 'google-sheets');
 const getVirtualViewsFolder = (customPath) => path.join((0, contentAsCodePaths_1.getDownloadFolder)(customPath), 'virtual-views');
-function getPromoteAction(action) {
-    switch (action) {
-        case common_1.PromotionAction.CREATE:
-            return 'created';
-        case common_1.PromotionAction.UPDATE:
-            return 'updated';
-        case common_1.PromotionAction.DELETE:
-            return 'deleted';
-        case common_1.PromotionAction.NO_CHANGES:
-            return 'skipped';
-        default:
-            (0, common_1.assertUnreachable)(action, `Unknown promotion action: ${action}`);
-    }
-    return 'skipped';
-}
 const downloadVirtualViews = async (projectId, slugs, customPath) => {
     const folder = getVirtualViewsFolder(customPath);
     await fs_1.promises.mkdir(folder, { recursive: true });
@@ -813,8 +748,8 @@ const downloadHandler = async (options) => {
     globalState_1.default.setVerbose(options.verbose);
     const isOrganizationDownload = options.organization === true;
     const includeAll = options.includeAll === true;
-    const includeApps = options.includeApps === true || includeAll;
-    const includeAllOptionalContent = includeAll && !options.appsOnly;
+    const includeApps = !options.spacesOnly && (options.includeApps === true || includeAll);
+    const includeAllOptionalContent = includeAll && !options.appsOnly && !options.spacesOnly;
     const { limit: appsLimit, noEffectWarning: appsLimitWarning } = (0, appsDownload_1.resolveAppsLimit)(options.appsLimit, includeApps);
     if (appsLimitWarning) {
         globalState_1.default.log(styles.warning(appsLimitWarning));
@@ -836,6 +771,46 @@ const downloadHandler = async (options) => {
         options.includeScheduledDeliveries = false;
         options.includeVirtualViews = false;
     }
+    if (options.spacesOnly) {
+        if (options.skipSpaces) {
+            throw new common_1.ParameterError('Nothing to download: --spaces-only cannot be combined with --skip-spaces.');
+        }
+        options.skipCharts = true;
+        options.skipDashboards = true;
+        options.agents = [];
+        options.alerts = [];
+        options.apps = [];
+        options.googleSheets = [];
+        options.scheduledDeliveries = [];
+        options.virtualViews = [];
+        options.includeAgents = false;
+        options.includeApps = false;
+        options.includeAlerts = false;
+        options.includeGoogleSheets = false;
+        options.includeScheduledDeliveries = false;
+        options.includeVirtualViews = false;
+    }
+    if (options.rootSpaces && options.nested) {
+        throw new common_1.ParameterError('--root-spaces cannot be combined with --nested');
+    }
+    const hasFilters = !options.spacesOnly &&
+        (options.charts.length > 0 ||
+            options.dashboards.length > 0 ||
+            options.agents.length > 0 ||
+            options.alerts.length > 0 ||
+            options.googleSheets.length > 0 ||
+            options.scheduledDeliveries.length > 0 ||
+            options.virtualViews.length > 0);
+    const shouldDownloadSpaces = !isOrganizationDownload && !options.skipSpaces && !hasFilters;
+    let skipEmbeddedSpaces = !hasFilters || options.skipSpaces;
+    if (shouldDownloadSpaces) {
+        try {
+            await (0, spacesAsCode_1.getUniqueExistingSpaceFilePathsBySlug)((0, contentAsCodePaths_1.getDownloadFolder)(options.path));
+        }
+        catch (error) {
+            throw (0, spacesAsCode_1.createSpaceAsCodeDownloadError)((0, common_1.getErrorMessage)(error));
+        }
+    }
     await (0, apiClient_1.checkLightdashVersion)();
     const config = await (0, config_1.getConfig)();
     if (!config.context?.apiKey || !config.context.serverUrl) {
@@ -860,8 +835,9 @@ const downloadHandler = async (options) => {
     const projectId = projectSelection.projectUuid;
     // Log current project info
     (0, selectProject_1.logSelectedProject)(projectSelection, config, 'Downloading from');
-    const spinner = globalState_1.default.startSpinner(`Downloading charts`);
-    spinner.start(`Downloading content from project`);
+    const spinner = globalState_1.default.startSpinner(options.spacesOnly
+        ? `Downloading spaces`
+        : `Downloading content from project`);
     // Fetch project details to get project name for folder structure
     const project = await (0, apiClient_1.lightdashApi)({
         method: 'GET',
@@ -882,17 +858,25 @@ const downloadHandler = async (options) => {
         },
     });
     try {
-        const hasFilters = options.charts.length > 0 ||
-            options.dashboards.length > 0 ||
-            options.agents.length > 0 ||
-            options.alerts.length > 0 ||
-            options.googleSheets.length > 0 ||
-            options.scheduledDeliveries.length > 0 ||
-            options.virtualViews.length > 0;
-        // When downloading specific charts or dashboards, skip space metadata
-        const skipSpaces = options.skipSpaces || hasFilters;
         let allMetadataEntries = [];
-        let allSpaces = [];
+        if (shouldDownloadSpaces) {
+            if (!options.spacesOnly)
+                spinner.start(`Downloading spaces`);
+            try {
+                const spaceTotal = await (0, spacesAsCode_1.downloadSpaces)(projectId, projectName, options.path, options.nested, options.rootSpaces);
+                spinner.succeed(`Downloaded ${spaceTotal} spaces`);
+            }
+            catch (error) {
+                if (!(0, spacesAsCode_1.shouldFallBackToEmbeddedSpaces)(error, options.spacesOnly)) {
+                    throw (0, spacesAsCode_1.isSpaceAsCodeFetchError)(error)
+                        ? (0, spacesAsCode_1.createSpaceAsCodeDownloadError)((0, common_1.getErrorMessage)(error))
+                        : error;
+                }
+                skipEmbeddedSpaces = false;
+                spinner.warn(styles.warning('Space access is unavailable; continuing with legacy space metadata where available.'));
+                globalState_1.default.debug(`Could not download access-aware spaces: ${(0, common_1.getErrorMessage)(error)}`);
+            }
+        }
         if (includeAllOptionalContent ||
             options.includeVirtualViews ||
             options.virtualViews.length > 0) {
@@ -906,19 +890,17 @@ const downloadHandler = async (options) => {
                 globalState_1.default.log(styles.warning(`No charts filters provided, skipping`));
             }
             else {
-                const [regularChartTotal, , regularChartMeta, regularChartSpaces,] = await (0, exports.downloadContent)(options.charts, 'charts', projectId, projectName, options.path, options.languageMap, options.nested, skipSpaces, options.stripPivotSeries);
+                const [regularChartTotal, , regularChartMeta] = await (0, exports.downloadContent)(options.charts, 'charts', projectId, projectName, options.path, options.languageMap, options.nested, skipEmbeddedSpaces, options.stripPivotSeries, options.rootSpaces);
                 spinner.succeed(`Downloaded ${regularChartTotal} charts`);
                 allMetadataEntries = [
                     ...allMetadataEntries,
                     ...regularChartMeta,
                 ];
-                allSpaces = [...allSpaces, ...regularChartSpaces];
                 // Download SQL charts
                 spinner.start(`Downloading SQL charts`);
-                const [sqlChartTotal, , sqlChartMeta, sqlChartSpaces] = await (0, exports.downloadContent)(options.charts, 'sqlCharts', projectId, projectName, options.path, options.languageMap, options.nested, skipSpaces, false);
+                const [sqlChartTotal, , sqlChartMeta] = await (0, exports.downloadContent)(options.charts, 'sqlCharts', projectId, projectName, options.path, options.languageMap, options.nested, skipEmbeddedSpaces, false, options.rootSpaces);
                 spinner.succeed(`Downloaded ${sqlChartTotal} SQL charts`);
                 allMetadataEntries = [...allMetadataEntries, ...sqlChartMeta];
-                allSpaces = [...allSpaces, ...sqlChartSpaces];
                 chartTotal = regularChartTotal + sqlChartTotal;
             }
         }
@@ -930,33 +912,28 @@ const downloadHandler = async (options) => {
             else {
                 let chartSlugs = [];
                 let dashMeta;
-                let dashSpaces;
-                [dashboardTotal, chartSlugs, dashMeta, dashSpaces] =
-                    await (0, exports.downloadContent)(options.dashboards, 'dashboards', projectId, projectName, options.path, options.languageMap, options.nested, skipSpaces, false);
+                [dashboardTotal, chartSlugs, dashMeta] = await (0, exports.downloadContent)(options.dashboards, 'dashboards', projectId, projectName, options.path, options.languageMap, options.nested, skipEmbeddedSpaces, false, options.rootSpaces);
                 allMetadataEntries = [...allMetadataEntries, ...dashMeta];
-                allSpaces = [...allSpaces, ...dashSpaces];
                 spinner.succeed(`Downloaded ${dashboardTotal} dashboards`);
                 if (hasFilters &&
                     chartSlugs.length > 0 &&
                     !options.skipCharts) {
                     spinner.start(`Downloading ${chartSlugs.length} charts linked to dashboards`);
-                    const [regularCharts, , linkedChartMeta, linkedChartSpaces,] = await (0, exports.downloadContent)(chartSlugs, 'charts', projectId, projectName, options.path, options.languageMap, options.nested, skipSpaces, options.stripPivotSeries);
+                    const [regularCharts, , linkedChartMeta] = await (0, exports.downloadContent)(chartSlugs, 'charts', projectId, projectName, options.path, options.languageMap, options.nested, skipEmbeddedSpaces, options.stripPivotSeries, options.rootSpaces);
                     allMetadataEntries = [
                         ...allMetadataEntries,
                         ...linkedChartMeta,
                     ];
-                    allSpaces = [...allSpaces, ...linkedChartSpaces];
-                    const [sqlCharts, , linkedSqlMeta, linkedSqlSpaces] = await (0, exports.downloadContent)(chartSlugs, 'sqlCharts', projectId, projectName, options.path, options.languageMap, options.nested, skipSpaces);
+                    const [sqlCharts, , linkedSqlMeta] = await (0, exports.downloadContent)(chartSlugs, 'sqlCharts', projectId, projectName, options.path, options.languageMap, options.nested, skipEmbeddedSpaces, false, options.rootSpaces);
                     allMetadataEntries = [
                         ...allMetadataEntries,
                         ...linkedSqlMeta,
                     ];
-                    allSpaces = [...allSpaces, ...linkedSqlSpaces];
                     spinner.succeed(`Downloaded ${regularCharts + sqlCharts} charts linked to dashboards`);
                 }
             }
         }
-        if (shouldDownloadAiAgents(options)) {
+        if (!options.spacesOnly && shouldDownloadAiAgents(options)) {
             spinner.start(`Downloading AI agents`);
             const agentTotal = await downloadAiAgents(projectId, options.agents, options.path);
             spinner.succeed(`Downloaded ${agentTotal} AI agents`);
@@ -1101,11 +1078,6 @@ const downloadHandler = async (options) => {
                 }
             }
         }
-        // Report space definitions count
-        if (!skipSpaces) {
-            const uniqueSpaceCount = new Set(allSpaces.map((s) => s.slug)).size;
-            spinner.succeed(`Downloaded ${uniqueSpaceCount} space definitions`);
-        }
         // Write metadata file with all downloadedAt timestamps
         const metadataToWrite = {
             version: 1,
@@ -1149,6 +1121,8 @@ const downloadHandler = async (options) => {
                 error: `${error}`,
             },
         });
+        if ((0, spacesAsCode_1.isSpaceAsCodeDownloadError)(error))
+            throw error;
     }
 };
 exports.downloadHandler = downloadHandler;
@@ -1173,14 +1147,6 @@ const storeUploadChanges = (changes, promoteChanges) => {
     });
     return updatedChanges;
 };
-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.`));
-    }
-};
 // SQL charts have 'sql' field instead of 'tableName'/'metricQuery'
 const isSqlChart = (item) => 'sql' in item && !('tableName' in item);
 const upsertSingleItem = async (item, type, projectId, changes, force, config, skipSpaceCreate, publicSpaceCreate, validate, spaceNames) => {
@@ -1386,7 +1352,28 @@ const getDashboardChartSlugs = async (dashboardSlugs, customPath, looseDashboard
 };
 const uploadHandler = async (options) => {
     globalState_1.default.setVerbose(options.verbose);
+    if (options.spacesOnly && options.skipSpaces) {
+        throw new common_1.ParameterError('Nothing to upload: --spaces-only cannot be combined with --skip-spaces.');
+    }
     const isOrganizationUpload = options.organization === true;
+    const hasFilters = !options.spacesOnly &&
+        (options.charts.length > 0 ||
+            options.dashboards.length > 0 ||
+            options.agents.length > 0 ||
+            options.alerts.length > 0 ||
+            options.googleSheets.length > 0 ||
+            options.scheduledDeliveries.length > 0 ||
+            options.virtualViews.length > 0);
+    const shouldReconcileSpaces = !isOrganizationUpload && !options.skipSpaces && !hasFilters;
+    let preflightSpaceFiles = [];
+    if (shouldReconcileSpaces) {
+        try {
+            preflightSpaceFiles = await (0, spacesAsCode_1.readSpaceFiles)(options.path);
+        }
+        catch (error) {
+            throw (0, spacesAsCode_1.createSpaceAsCodeUploadError)((0, common_1.getErrorMessage)(error));
+        }
+    }
     if (options.gzip) {
         (0, apiClient_1.setGzipEnabled)(true);
     }
@@ -1430,16 +1417,34 @@ const uploadHandler = async (options) => {
     });
     let uploadResource = 'content as code';
     try {
+        uploadResource = 'space definitions';
+        const spaceFiles = preflightSpaceFiles;
+        const spaceNames = shouldReconcileSpaces
+            ? (0, spacesAsCode_1.getSpaceNames)(spaceFiles)
+            : await (0, spacesAsCode_1.readSpaceNames)(options.path);
+        if (spaceFiles.length > 0) {
+            globalState_1.default.log(`Found ${spaceFiles.length} space definition(s)`);
+        }
+        if (shouldReconcileSpaces) {
+            changes = await (0, spacesAsCode_1.upsertSpaces)(projectId, spaceFiles, changes, options.skipSpaceCreate, options.public);
+        }
+        else if (hasFilters) {
+            globalState_1.default.debug('Skipping space access reconciliation for a filtered content upload');
+        }
+        if (options.spacesOnly) {
+            await analytics_1.LightdashAnalytics.track({
+                event: 'upload.completed',
+                properties: {
+                    userId: config.user?.userUuid,
+                    organizationId: config.user?.organizationUuid,
+                    projectId,
+                    timeToCompleted: (Date.now() - start) / 1000,
+                },
+            });
+            (0, spacesAsCode_1.logUploadChanges)(changes);
+            return;
+        }
         const uploadPermissions = await (0, apiClient_1.getContentAsCodeUploadPermissions)(projectId);
-        // If any filter is provided, we skip those items without filters
-        // eg: if a --charts filter is provided, we skip dashboards if no --dashboards filter is provided
-        const hasFilters = options.charts.length > 0 ||
-            options.dashboards.length > 0 ||
-            options.agents.length > 0 ||
-            options.alerts.length > 0 ||
-            options.googleSheets.length > 0 ||
-            options.scheduledDeliveries.length > 0 ||
-            options.virtualViews.length > 0;
         // Discover loose YAML files (outside charts/ and dashboards/) classified by contentType
         uploadResource = 'content files';
         const looseFiles = await readLooseCodeFiles(options.path);
@@ -1461,12 +1466,6 @@ const uploadHandler = async (options) => {
         if (parseInt(String(options.concurrency), 10) > 1000) {
             globalState_1.default.log(styles.warning(`Concurrency limit exceeded. Using maximum of 1000 instead of ${options.concurrency}`));
         }
-        // Read space definition files to preserve original space names during upload
-        uploadResource = 'space definitions';
-        const spaceNames = await readSpaceNames(options.path);
-        if (Object.keys(spaceNames).length > 0) {
-            globalState_1.default.log(`Found ${Object.keys(spaceNames).length} space definition(s)`);
-        }
         if (!options.skipVirtualViews) {
             if (hasFilters && options.virtualViews.length === 0) {
                 globalState_1.default.log(styles.warning(`No virtual view filters provided, skipping`));
@@ -1762,7 +1761,7 @@ const uploadHandler = async (options) => {
                 timeToCompleted: (end - start) / 1000, // in seconds
             },
         });
-        logUploadChanges(changes);
+        (0, spacesAsCode_1.logUploadChanges)(changes);
     }
     catch (error) {
         globalState_1.default.log(styles.error(`\nError uploading ${uploadResource}: ${(0, common_1.getErrorMessage)(error)}`));
@@ -1775,16 +1774,27 @@ const uploadHandler = async (options) => {
                 error: (0, common_1.getErrorMessage)(error),
             },
         });
-        if (error instanceof AiAgentAsCodeUploadError) {
+        if ((0, spacesAsCode_1.isSpaceAsCodeUploadError)(error))
+            throw error;
+        if (error instanceof AiAgentAsCodeUploadError)
             throw error.originalError;
-        }
     }
 };
 exports.uploadHandler = uploadHandler;
 exports.testHelpers = {
+    assertUniqueSpacePaths: spacesAsCode_1.assertUniqueSpacePaths,
+    downloadSpaces: spacesAsCode_1.downloadSpaces,
+    getFlatSpaceFileNames: spacesAsCode_1.getFlatSpaceFileNames,
     getDashboardChartSlugs,
     readAiAgentFiles,
+    readSpaceFiles: spacesAsCode_1.readSpaceFiles,
+    readSpaceNames: spacesAsCode_1.readSpaceNames,
     sanitizeChartForDownload,
+    shouldFallBackToEmbeddedSpaces: spacesAsCode_1.shouldFallBackToEmbeddedSpaces,
     shouldDownloadAiAgents,
+    sortSpaceFilesParentFirst: spacesAsCode_1.sortSpaceFilesParentFirst,
+    upsertSpaces: spacesAsCode_1.upsertSpaces,
     upsertVirtualViews,
+    validateSpaceIdentity: spacesAsCode_1.validateSpaceIdentity,
+    writeSpaceFiles: spacesAsCode_1.writeSpaceFiles,
 };