@lightdash/cli 1.34.0 → 1.36.0

package/dist/handlers/apps/appCodeFiles.d.ts

@@ -1,4 +1,4 @@
-import { type DataAppCode, type DataAppCodeFile, type DataAppContext, type DataAppDependencies, type ImportAppCodeRequestBody } from '@lightdash/common';
+import { type DataAppCode, type DataAppCodeFile, type DataAppContext, type DataAppDependencies, type DataAppManifest, type ImportAppCodeRequestBody } from '@lightdash/common';
 /**
  * Derives a collision-safe folder name for a data app.
  * Uses the slugified app name. If that slug is already taken by another app,
@@ -14,14 +14,10 @@ export declare const buildImportBody: (code: DataAppCode, targetProjectUuid: str
     createNew?: boolean;
 }) => ImportAppCodeRequestBody;
 /**
- * Points a downloaded app folder's manifest at a different app, so future
- * uploads update that app instead of the one it was downloaded from.
+ * The persistent slug from a slug-aware server is the folder name (stable
+ * across app renames). Pre-slug servers fall back to name-derived folders.
  */
-export declare const retargetManifest: (dir: string, target: {
-    appUuid: string;
-    projectUuid: string;
-    version: number;
-}) => Promise<void>;
+export declare const resolveAppFolderName: (manifest: DataAppManifest, takenFolders: Set<string>) => string;
 /**
  * Writes server-provided dependency files as the app folder's package.json +
  * pnpm-lock.yaml. Called after the scaffold write so they override the

package/dist/handlers/apps/appCodeFiles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"appCodeFiles.d.ts","sourceRoot":"","sources":["../../../src/handlers/apps/appCodeFiles.ts"],"names":[],"mappings":"AAAA,OAAO,EAIH,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,cAAc,EAEnB,KAAK,mBAAmB,EAExB,KAAK,wBAAwB,EAChC,MAAM,mBAAmB,CAAC;AAO3B;;;;GAIG;AACH,eAAO,MAAM,aAAa,SAChB,MAAM,WACH,MAAM,gBACD,GAAG,CAAC,MAAM,CAAC,KAC1B,MAcF,CAAC;AAEF,eAAO,MAAM,eAAe,QACnB,MAAM,SACJ,eAAe,EAAE,KACzB,OAAO,CAAC,IAAI,CAsBd,CAAC;AAEF,eAAO,MAAM,iBAAiB,QACrB,MAAM,WACF,cAAc,KACxB,OAAO,CAAC,IAAI,CASd,CAAC;AAEF,eAAO,MAAM,gBAAgB,QACpB,MAAM,QACL,WAAW,KAClB,OAAO,CAAC,IAAI,CAWd,CAAC;AAmCF,eAAO,MAAM,eAAe,SAClB,WAAW,qBACE,MAAM,QACnB;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,KAC5D,wBAgBF,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,gBAAgB,QACpB,MAAM,UACH;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,KAClE,OAAO,CAAC,IAAI,CAUd,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,QAC1B,MAAM,QACL,mBAAmB,KAC1B,OAAO,CAAC,IAAI,CAGd,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IAC/B,WAAW,EAAE,MAAM,CAAC;IAKpB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,QAC3B,MAAM,KACZ,OAAO,CAAC,oBAAoB,GAAG,IAAI,CA6BrC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,qBAAqB,eAClB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,wBACZ,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAC7C,MAAM,EAOH,CAAC;AAEP;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,yBACf,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,eAC/B,MAAM,KACpB,MAAM,CAAC,MAAM,EAAE,MAAM,CAgBvB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,SAC3B,WAAW,cACL,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,QAC5B,mBAAmB,KAC1B,WAC4E,CAAC;AAEhF,eAAO,MAAM,iBAAiB,QAAe,MAAM,KAAG,OAAO,CAAC,WAAW,CAuBxE,CAAC"}
+{"version":3,"file":"appCodeFiles.d.ts","sourceRoot":"","sources":["../../../src/handlers/apps/appCodeFiles.ts"],"names":[],"mappings":"AAAA,OAAO,EAKH,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,cAAc,EAEnB,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,wBAAwB,EAChC,MAAM,mBAAmB,CAAC;AAO3B;;;;GAIG;AACH,eAAO,MAAM,aAAa,SAChB,MAAM,WACH,MAAM,gBACD,GAAG,CAAC,MAAM,CAAC,KAC1B,MAcF,CAAC;AAEF,eAAO,MAAM,eAAe,QACnB,MAAM,SACJ,eAAe,EAAE,KACzB,OAAO,CAAC,IAAI,CAsBd,CAAC;AAEF,eAAO,MAAM,iBAAiB,QACrB,MAAM,WACF,cAAc,KACxB,OAAO,CAAC,IAAI,CASd,CAAC;AAEF,eAAO,MAAM,gBAAgB,QACpB,MAAM,QACL,WAAW,KAClB,OAAO,CAAC,IAAI,CAWd,CAAC;AAmCF,eAAO,MAAM,eAAe,SAClB,WAAW,qBACE,MAAM,QACnB;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,KAC5D,wBAoBF,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,oBAAoB,aACnB,eAAe,gBACX,GAAG,CAAC,MAAM,CAAC,KAC1B,MAgBF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,QAC1B,MAAM,QACL,mBAAmB,KAC1B,OAAO,CAAC,IAAI,CAGd,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IAC/B,WAAW,EAAE,MAAM,CAAC;IAKpB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,QAC3B,MAAM,KACZ,OAAO,CAAC,oBAAoB,GAAG,IAAI,CA6BrC,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,qBAAqB,eAClB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,wBACZ,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAC7C,MAAM,EAOH,CAAC;AAEP;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,yBACf,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,eAC/B,MAAM,KACpB,MAAM,CAAC,MAAM,EAAE,MAAM,CAgBvB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,SAC3B,WAAW,cACL,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,QAC5B,mBAAmB,KAC1B,WAC4E,CAAC;AAEhF,eAAO,MAAM,iBAAiB,QAAe,MAAM,KAAG,OAAO,CAAC,WAAW,CAuBxE,CAAC"}

package/dist/handlers/apps/appCodeFiles.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.readBundleFromDir = exports.attachDependenciesToCode = exports.applySdkMirrorToTemplateDeps = exports.buildDepsWarningLines = exports.readDependenciesFromDir = exports.writeDependenciesToDir = exports.retargetManifest = exports.buildImportBody = exports.writeBundleToDir = exports.writeContextToDir = exports.writeFilesToDir = exports.appFolderName = void 0;
+exports.readBundleFromDir = exports.attachDependenciesToCode = exports.applySdkMirrorToTemplateDeps = exports.buildDepsWarningLines = exports.readDependenciesFromDir = exports.writeDependenciesToDir = exports.resolveAppFolderName = exports.buildImportBody = exports.writeBundleToDir = exports.writeContextToDir = exports.writeFilesToDir = exports.appFolderName = void 0;
 const tslib_1 = require("tslib");
 const common_1 = require("@lightdash/common");
 const fs_1 = require("fs");
@@ -95,25 +95,37 @@ const buildImportBody = (code, targetProjectUuid, opts) => {
         targetAppUuid = opts.app;
     }
     else if (targetProjectUuid === code.manifest.projectUuid) {
+        // Pre-slug bundles carry an appUuid (uuid-fallback identity, and
+        // same-project append on pre-slug servers). Slug-only bundles yield
+        // undefined here — slug-aware servers resolve by slug instead.
         targetAppUuid = code.manifest.appUuid;
     }
     return {
         code,
         targetAppUuid,
         spaceUuid: opts.space,
+        ...(opts.createNew ? { createNew: true } : {}),
     };
 };
 exports.buildImportBody = buildImportBody;
 /**
- * Points a downloaded app folder's manifest at a different app, so future
- * uploads update that app instead of the one it was downloaded from.
+ * The persistent slug from a slug-aware server is the folder name (stable
+ * across app renames). Pre-slug servers fall back to name-derived folders.
  */
-const retargetManifest = async (dir, target) => {
-    const manifestPath = path.join(dir, MANIFEST_FILENAME);
-    const manifest = YAML.parse(await fs_1.promises.readFile(manifestPath, 'utf-8'));
-    await fs_1.promises.writeFile(manifestPath, YAML.stringify({ ...manifest, ...target }), 'utf-8');
+const resolveAppFolderName = (manifest, takenFolders) => {
+    // Defense-in-depth: a server of unknown version, or a hand-tampered
+    // manifest on disk, must not steer the local write path via an
+    // unvalidated slug (e.g. `../../etc`) — only trust it once it passes the
+    // same shape check the server enforces on upload.
+    if (manifest.slug !== undefined && (0, common_1.isValidDataAppSlug)(manifest.slug)) {
+        return manifest.slug;
+    }
+    // The fallback needs a uuid for its collision/untitled suffixes. Real
+    // pre-slug servers always emit appUuid; only a tampered slug-only
+    // manifest lands here without one.
+    return (0, exports.appFolderName)(manifest.name, manifest.appUuid ?? 'unknown', takenFolders);
 };
-exports.retargetManifest = retargetManifest;
+exports.resolveAppFolderName = resolveAppFolderName;
 /**
  * Writes server-provided dependency files as the app folder's package.json +
  * pnpm-lock.yaml. Called after the scaffold write so they override the

package/dist/handlers/apps/appCodeFiles.test.js

@@ -73,6 +73,17 @@ describe('buildImportBody', () => {
         });
         expect(body.targetAppUuid).toBeUndefined();
     });
+    it('includes createNew: true in the body when the flag is set', () => {
+        const code = makeCode('app-uuid-1', 'proj-uuid-1');
+        const body = (0, appCodeFiles_1.buildImportBody)(code, 'proj-uuid-1', { createNew: true });
+        expect(body.createNew).toBe(true);
+        expect(body.targetAppUuid).toBeUndefined();
+    });
+    it('omits the createNew key entirely when the flag is not set', () => {
+        const code = makeCode('app-uuid-1', 'proj-uuid-1');
+        const body = (0, appCodeFiles_1.buildImportBody)(code, 'proj-uuid-1', {});
+        expect('createNew' in body).toBe(false);
+    });
 });
 const bundle = {
     manifest: {
@@ -134,23 +145,6 @@ it('upload reads back only src/ files, ignoring scaffolding and context', async
     expect(read.files.every((f) => f.path.startsWith('src/'))).toBe(true);
     expect(read.files.map((f) => f.path).sort()).toEqual(bundle.files.map((f) => f.path).sort());
 });
-describe('retargetManifest', () => {
-    it('rewrites appUuid, projectUuid and version, preserving other fields', async () => {
-        const dir = await fs_1.promises.mkdtemp(path.join(os.tmpdir(), 'ld-app-'));
-        await (0, appCodeFiles_1.writeBundleToDir)(dir, bundle);
-        await (0, appCodeFiles_1.retargetManifest)(dir, {
-            appUuid: 'new-app-uuid',
-            projectUuid: 'new-proj-uuid',
-            version: 1,
-        });
-        const read = await (0, appCodeFiles_1.readBundleFromDir)(dir);
-        expect(read.manifest.appUuid).toBe('new-app-uuid');
-        expect(read.manifest.projectUuid).toBe('new-proj-uuid');
-        expect(read.manifest.version).toBe(1);
-        expect(read.manifest.name).toBe('N');
-        expect(read.manifest.downloadedAt).toBe('2026-06-30T00:00:00.000Z');
-    });
-});
 it('throws a clear error when the manifest is not valid YAML', async () => {
     const dir = await fs_1.promises.mkdtemp(path.join(os.tmpdir(), 'ld-app-'));
     await fs_1.promises.writeFile(path.join(dir, 'lightdash-app.yml'), 'foo: [bar', 'utf-8');
@@ -214,6 +208,32 @@ describe('appFolderName', () => {
         expect((0, appCodeFiles_1.appFolderName)('!!!', 'abcd1234-ef56-7890-ab12-cdef01234567', new Set())).toBe('untitled-app-abcd1234');
     });
 });
+describe('resolveAppFolderName', () => {
+    it('uses the manifest slug when present', () => {
+        const code = makeCode('app-uuid-1', 'proj-uuid-1');
+        expect((0, appCodeFiles_1.resolveAppFolderName)({ ...code.manifest, slug: 'sales-app' }, new Set())).toBe('sales-app');
+    });
+    it('falls back to appFolderName when the manifest has no slug', () => {
+        const uuid = 'abcd1234-ef56-7890-ab12-cdef01234567';
+        const code = makeCode(uuid, 'proj-uuid-1');
+        expect((0, appCodeFiles_1.resolveAppFolderName)(code.manifest, new Set())).toBe((0, appCodeFiles_1.appFolderName)(code.manifest.name, uuid, new Set()));
+    });
+    it('uses the slug for uuid-free manifests (slug-aware servers)', () => {
+        const code = makeCode('app-uuid-1', 'proj-uuid-1');
+        expect((0, appCodeFiles_1.resolveAppFolderName)({ ...code.manifest, appUuid: undefined, slug: 'sales-app' }, new Set())).toBe('sales-app');
+    });
+    // Defense-in-depth: a tampered manifest (or a server of unknown version)
+    // must not be able to steer the write path via an invalid slug.
+    it('falls back to appFolderName when the slug is a path-traversal attempt', () => {
+        const uuid = 'abcd1234-ef56-7890-ab12-cdef01234567';
+        const code = makeCode(uuid, 'proj-uuid-1');
+        expect((0, appCodeFiles_1.resolveAppFolderName)({ ...code.manifest, slug: '../../../../tmp/evil' }, new Set())).toBe((0, appCodeFiles_1.appFolderName)(code.manifest.name, uuid, new Set()));
+    });
+    it('still uses a valid manifest slug (unaffected by the new validation)', () => {
+        const code = makeCode('app-uuid-1', 'proj-uuid-1');
+        expect((0, appCodeFiles_1.resolveAppFolderName)({ ...code.manifest, slug: 'sales-app-2' }, new Set())).toBe('sales-app-2');
+    });
+});
 // ─── readDependenciesFromDir ──────────────────────────────────────────────────
 const makePackageJson = (deps = {}) => JSON.stringify({ name: 'test-app', dependencies: deps });
 const LOCKFILE_CONTENT = 'lockfileVersion: 9.0\n\npackages:\n  react@19.0.0:\n';

package/dist/handlers/apps/appsDownload.d.ts

@@ -1,7 +1,27 @@
-import { type DataAppCodeDownload } from '@lightdash/common';
+import { type DataAppCodeDownload, type DataAppManifest } from '@lightdash/common';
 export declare const DEFAULT_APPS_LIMIT = 50;
-export declare const getDataAppUuidFromReference: (reference: string) => string;
+export declare const getDataAppReference: (reference: string) => string;
 export declare const getDataAppUploadFilter: (references: string[], includeApps: boolean) => Set<string> | null;
+/**
+ * --include-apps uploads every folder; explicit --apps references filter by
+ * the manifest's slug or appUuid (references may be either, or app URLs).
+ */
+export declare const uploadFilterMatches: (filter: Set<string> | null, manifest: DataAppManifest) => boolean;
+/** The filter entries this manifest satisfies (for unmatched-ref reporting). */
+export declare const matchedUploadRefs: (filter: Set<string>, manifest: DataAppManifest) => string[];
+/**
+ * Warning for --apps references that matched no local app folder. Uuid-shaped
+ * refs (including refs parsed out of app URLs) get the slug-identity
+ * explanation: id-free bundles can only be selected by slug.
+ */
+export declare const unmatchedUploadRefsWarning: (unmatched: string[]) => string | null;
+/**
+ * Shown when the upload response carries no slug even though the bundle sent
+ * one — the server predates slug identity, so it ignored the slug and matched
+ * (or created) by uuid only. A same-slug upload may have just created a
+ * duplicate app instead of appending.
+ */
+export declare const preSlugServerHint: (folder: string) => string;
 /**
  * Resolves the --apps-limit flag. Commander passes the raw string (or
  * undefined when the flag was not given, so an explicit flag is
@@ -23,15 +43,15 @@ export type AppsDownloadSelection = {
     mode: 'none';
 } | {
     mode: 'explicit';
-    appUuids: string[];
+    appRefs: string[];
 } | {
     mode: 'list-all';
-    extraAppUuids: string[];
+    extraAppRefs: string[];
 };
 /**
- * Explicit UUIDs (--apps) are fetched directly; --include-apps lists every
- * app in the project via the project-wide apps endpoint, falling back to
- * the space-scoped content API on servers that predate it.
+ * Explicit references (--apps) are fetched directly; --include-apps lists
+ * every app in the project via the project-wide apps endpoint, falling back
+ * to the space-scoped content API on servers that predate it.
  */
 export declare const selectAppsToDownload: (request: {
     apps?: string[];
@@ -45,8 +65,16 @@ export declare const capListedApps: (listedUuids: string[], limit: number) => {
  * Pre-context servers return a download payload without `context`.
  */
 export declare const ensureDownloadedAppContext: (appUuid: string, code: DataAppCodeDownload) => DataAppCodeDownload;
+/**
+ * Shown after uploading a bundle whose manifest predates slug identity —
+ * uploads keep working via the uuid fallback, but the user should upgrade.
+ */
+export declare const preSlugUploadHint: (args: {
+    folder: string;
+    slug: string | undefined;
+}) => string;
 export type AppDownloadFailure = {
-    appUuid: string;
+    appRef: string;
     message: string;
 };
 export type AppDownloadErrorOutcome = {
@@ -62,15 +90,6 @@ export type AppDownloadErrorOutcome = {
  * message over a canned guess.
  */
 export declare const classifyAppDownloadError: (err: unknown) => AppDownloadErrorOutcome;
-/**
- * Shown when a newly created app's folder manifest was NOT retargeted —
- * spells out the consequence and the manual fix.
- */
-export declare const manifestRetargetHint: (args: {
-    folder: string;
-    appUuid: string;
-    projectUuid: string;
-}) => string;
 /**
  * Sums changes entries that represent actual upserts — excluding both
  * 'skipped' and 'failed' keys so that failures don't suppress the
@@ -82,15 +101,6 @@ export declare const computeUpsertedTotal: (changes: Record<string, number>) =>
  * items — the condition that should display the "all skipped" warning.
  */
 export declare const shouldWarnAllSkipped: (changes: Record<string, number>) => boolean;
-/**
- * Determines how an app upload should proceed given a potential project
- * mismatch between the manifest and the upload target.
- *
- * 'proceed'            — upload immediately (same project, or --create-new).
- * 'needs-confirmation' — projects differ and --create-new was not passed;
- *                        caller must prompt (TTY) or reject (non-TTY).
- */
-export declare const classifyAppUpload: (manifestProjectUuid: string, targetProjectUuid: string, createNew: boolean) => 'proceed' | 'needs-confirmation';
 export declare const appsDownloadSummary: (successCount: number, total: number, failures: AppDownloadFailure[], appsDir: string, skippedNotBuiltCount: number) => {
     ok: boolean;
     message: string;

package/dist/handlers/apps/appsDownload.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"appsDownload.d.ts","sourceRoot":"","sources":["../../../src/handlers/apps/appsDownload.ts"],"names":[],"mappings":"AAAA,OAAO,EAIH,KAAK,mBAAmB,EAC3B,MAAM,mBAAmB,CAAC;AAG3B,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAErC,eAAO,MAAM,2BAA2B,cAAe,MAAM,KAAG,MAoB/D,CAAC;AAEF,eAAO,MAAM,sBAAsB,eACnB,MAAM,EAAE,eACP,OAAO,KACrB,GAAG,CAAC,MAAM,CAAC,GAAG,IAC4D,CAAC;AAE9E;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,aACf,MAAM,GAAG,SAAS,eACf,OAAO,KACrB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAA;CAejD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,kCAAkC,QAAS,OAAO,KAAG,OACP,CAAC;AAE5D,MAAM,MAAM,qBAAqB,GAC3B;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,aAAa,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAEpD;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,YAAa;IAC1C,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;CACzB,KAAG,qBASH,CAAC;AAEF,eAAO,MAAM,aAAa,gBACT,MAAM,EAAE,SACd,MAAM,KACd;IAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAG7C,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,0BAA0B,YAC1B,MAAM,QACT,mBAAmB,KAC1B,mBAOF,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtE,MAAM,MAAM,uBAAuB,GAC7B;IAAE,IAAI,EAAE,gBAAgB,CAAA;CAAE,GAC1B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAExC;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,QAC5B,OAAO,KACb,uBAoBF,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,oBAAoB,SAAU;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACvB,KAAG,MAC0O,CAAC;AAE/O;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,YAAa,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAAG,MAGpB,CAAC;AAEpD;;;GAGG;AACH,eAAO,MAAM,oBAAoB,YACpB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,KAChC,OAKF,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,wBACL,MAAM,qBACR,MAAM,aACd,OAAO,KACnB,SAAS,GAAG,oBAKd,CAAC;AAEF,eAAO,MAAM,mBAAmB,iBACd,MAAM,SACb,MAAM,YACH,kBAAkB,EAAE,WACrB,MAAM,wBACO,MAAM,KAC7B;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,EAAE,CAAA;CAiBxD,CAAC"}
+{"version":3,"file":"appsDownload.d.ts","sourceRoot":"","sources":["../../../src/handlers/apps/appsDownload.ts"],"names":[],"mappings":"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"}

package/dist/handlers/apps/appsDownload.js

@@ -1,10 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.appsDownloadSummary = exports.classifyAppUpload = exports.shouldWarnAllSkipped = exports.computeUpsertedTotal = exports.manifestRetargetHint = exports.classifyAppDownloadError = exports.ensureDownloadedAppContext = exports.capListedApps = exports.selectAppsToDownload = exports.shouldFallBackToSpaceScopedListing = exports.resolveAppsLimit = exports.getDataAppUploadFilter = exports.getDataAppUuidFromReference = exports.DEFAULT_APPS_LIMIT = void 0;
+exports.appsDownloadSummary = exports.shouldWarnAllSkipped = exports.computeUpsertedTotal = exports.classifyAppDownloadError = exports.preSlugUploadHint = exports.ensureDownloadedAppContext = exports.capListedApps = exports.selectAppsToDownload = exports.shouldFallBackToSpaceScopedListing = exports.resolveAppsLimit = exports.preSlugServerHint = exports.unmatchedUploadRefsWarning = exports.matchedUploadRefs = exports.uploadFilterMatches = exports.getDataAppUploadFilter = exports.getDataAppReference = exports.DEFAULT_APPS_LIMIT = void 0;
 const common_1 = require("@lightdash/common");
 const uuid_1 = require("uuid");
 exports.DEFAULT_APPS_LIMIT = 50;
-const getDataAppUuidFromReference = (reference) => {
+const getDataAppReference = (reference) => {
     let url;
     try {
         url = new URL(reference);
@@ -20,9 +20,42 @@ const getDataAppUuidFromReference = (reference) => {
         (0, uuid_1.validate)(pathSegments[index + 1]));
     return appSegmentIndex >= 0 ? pathSegments[appSegmentIndex + 1] : reference;
 };
-exports.getDataAppUuidFromReference = getDataAppUuidFromReference;
-const getDataAppUploadFilter = (references, includeApps) => includeApps ? null : new Set(references.map(exports.getDataAppUuidFromReference));
+exports.getDataAppReference = getDataAppReference;
+const getDataAppUploadFilter = (references, includeApps) => includeApps ? null : new Set(references.map(exports.getDataAppReference));
 exports.getDataAppUploadFilter = getDataAppUploadFilter;
+/**
+ * --include-apps uploads every folder; explicit --apps references filter by
+ * the manifest's slug or appUuid (references may be either, or app URLs).
+ */
+const uploadFilterMatches = (filter, manifest) => filter === null ||
+    (manifest.appUuid !== undefined && filter.has(manifest.appUuid)) ||
+    (manifest.slug !== undefined && filter.has(manifest.slug));
+exports.uploadFilterMatches = uploadFilterMatches;
+/** The filter entries this manifest satisfies (for unmatched-ref reporting). */
+const matchedUploadRefs = (filter, manifest) => [manifest.appUuid, manifest.slug].filter((ref) => ref !== undefined && filter.has(ref));
+exports.matchedUploadRefs = matchedUploadRefs;
+/**
+ * Warning for --apps references that matched no local app folder. Uuid-shaped
+ * refs (including refs parsed out of app URLs) get the slug-identity
+ * explanation: id-free bundles can only be selected by slug.
+ */
+const unmatchedUploadRefsWarning = (unmatched) => {
+    if (unmatched.length === 0)
+        return null;
+    const base = `No local app folder matched: ${unmatched.join(', ')}.`;
+    return unmatched.some((ref) => (0, uuid_1.validate)(ref))
+        ? `${base} Bundles downloaded with slug identity carry no uuid — select them by slug (the folder name) instead of a UUID or app URL.`
+        : base;
+};
+exports.unmatchedUploadRefsWarning = unmatchedUploadRefsWarning;
+/**
+ * Shown when the upload response carries no slug even though the bundle sent
+ * one — the server predates slug identity, so it ignored the slug and matched
+ * (or created) by uuid only. A same-slug upload may have just created a
+ * duplicate app instead of appending.
+ */
+const preSlugServerHint = (folder) => `This server predates slug-based app identity, so "${folder}" was matched by uuid only. If you expected to update an existing app, verify no duplicate was created, and upgrade the server (or use a matching CLI version).`;
+exports.preSlugServerHint = preSlugServerHint;
 /**
  * Resolves the --apps-limit flag. Commander passes the raw string (or
  * undefined when the flag was not given, so an explicit flag is
@@ -53,17 +86,17 @@ exports.resolveAppsLimit = resolveAppsLimit;
 const shouldFallBackToSpaceScopedListing = (err) => err instanceof common_1.LightdashError && err.statusCode === 404;
 exports.shouldFallBackToSpaceScopedListing = shouldFallBackToSpaceScopedListing;
 /**
- * Explicit UUIDs (--apps) are fetched directly; --include-apps lists every
- * app in the project via the project-wide apps endpoint, falling back to
- * the space-scoped content API on servers that predate it.
+ * Explicit references (--apps) are fetched directly; --include-apps lists
+ * every app in the project via the project-wide apps endpoint, falling back
+ * to the space-scoped content API on servers that predate it.
  */
 const selectAppsToDownload = (request) => {
-    const explicitUuids = (request.apps ?? []).map(exports.getDataAppUuidFromReference);
+    const explicitRefs = (request.apps ?? []).map(exports.getDataAppReference);
     if (request.includeApps) {
-        return { mode: 'list-all', extraAppUuids: explicitUuids };
+        return { mode: 'list-all', extraAppRefs: explicitRefs };
     }
-    if (explicitUuids.length > 0) {
-        return { mode: 'explicit', appUuids: explicitUuids };
+    if (explicitRefs.length > 0) {
+        return { mode: 'explicit', appRefs: explicitRefs };
     }
     return { mode: 'none' };
 };
@@ -83,6 +116,14 @@ const ensureDownloadedAppContext = (appUuid, code) => {
     return code;
 };
 exports.ensureDownloadedAppContext = ensureDownloadedAppContext;
+/**
+ * Shown after uploading a bundle whose manifest predates slug identity —
+ * uploads keep working via the uuid fallback, but the user should upgrade.
+ */
+const preSlugUploadHint = (args) => `${args.folder}/lightdash-app.yml predates slug identity. Re-download the app to upgrade${args.slug !== undefined
+    ? ` (or add \`slug: ${args.slug}\` to lightdash-app.yml)`
+    : ''}. Uploads keep working via uuid matching meanwhile.`;
+exports.preSlugUploadHint = preSlugUploadHint;
 /**
  * A 404 saying the app has no ready version means it exists but never
  * finished a successful build — nothing to download, so it's a skip, not a
@@ -108,12 +149,6 @@ const classifyAppDownloadError = (err) => {
     return { kind: 'fail', message: (0, common_1.getErrorMessage)(err) };
 };
 exports.classifyAppDownloadError = classifyAppDownloadError;
-/**
- * Shown when a newly created app's folder manifest was NOT retargeted —
- * spells out the consequence and the manual fix.
- */
-const manifestRetargetHint = (args) => `${args.folder}/lightdash-app.yml still targets the original app, so future uploads here will ask to create again. To update the new app instead, set appUuid: ${args.appUuid} and projectUuid: ${args.projectUuid} in lightdash-app.yml.`;
-exports.manifestRetargetHint = manifestRetargetHint;
 /**
  * Sums changes entries that represent actual upserts — excluding both
  * 'skipped' and 'failed' keys so that failures don't suppress the
@@ -134,21 +169,6 @@ const shouldWarnAllSkipped = (changes) => {
     return totalSkipped > 0 && (0, exports.computeUpsertedTotal)(changes) === 0;
 };
 exports.shouldWarnAllSkipped = shouldWarnAllSkipped;
-/**
- * Determines how an app upload should proceed given a potential project
- * mismatch between the manifest and the upload target.
- *
- * 'proceed'            — upload immediately (same project, or --create-new).
- * 'needs-confirmation' — projects differ and --create-new was not passed;
- *                        caller must prompt (TTY) or reject (non-TTY).
- */
-const classifyAppUpload = (manifestProjectUuid, targetProjectUuid, createNew) => {
-    if (createNew || manifestProjectUuid === targetProjectUuid) {
-        return 'proceed';
-    }
-    return 'needs-confirmation';
-};
-exports.classifyAppUpload = classifyAppUpload;
 const appsDownloadSummary = (successCount, total, failures, appsDir, skippedNotBuiltCount) => {
     const attempted = total - skippedNotBuiltCount;
     const skippedSuffix = skippedNotBuiltCount > 0
@@ -161,7 +181,7 @@ const appsDownloadSummary = (successCount, total, failures, appsDir, skippedNotB
     return {
         ok: false,
         message: `${base} — ${failures.length} failed`,
-        failureLines: failures.map((failure) => `  ✖ ${failure.appUuid}: ${failure.message}`),
+        failureLines: failures.map((failure) => `  ✖ ${failure.appRef}: ${failure.message}`),
     };
 };
 exports.appsDownloadSummary = appsDownloadSummary;