@lightdash/cli 1.45.0 → 1.46.0

package/dist/config.d.ts

@@ -23,6 +23,10 @@ export type Config = {
         metadataFileGitignoreNoticeShown?: boolean;
     };
 };
+/** @internal Exported for filesystem-permission regression tests. */
+export declare const ensureConfigFilePermissions: (filePath: string) => Promise<void>;
+/** @internal Exported for filesystem-permission regression tests. */
+export declare const writeConfigToFile: (filePath: string, config: Config) => Promise<void>;
 export declare const getConfig: () => Promise<Config>;
 export declare const setProject: (projectUuid: string, projectName: string) => Promise<void>;
 export declare const unsetProject: () => Promise<void>;

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAQA,eAAO,MAAM,cAAc,QAAsC,CAAC;AAElE,MAAM,MAAM,MAAM,GAAG;IACjB,IAAI,CAAC,EAAE;QACH,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;KAC7B,CAAC;IACF,OAAO,CAAC,EAAE;QACN,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB;;;WAGG;QACH,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,WAAW,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;IACF,OAAO,CAAC,EAAE;QACN,qCAAqC,CAAC,EAAE,OAAO,CAAC;QAChD,gCAAgC,CAAC,EAAE,OAAO,CAAC;KAC9C,CAAC;CACL,CAAC;AAgCF,eAAO,MAAM,SAAS,QAAa,OAAO,CAAC,MAAM,CAmBhD,CAAC;AAEF,eAAO,MAAM,UAAU,gBAAuB,MAAM,eAAe,MAAM,kBAUxE,CAAC;AAEF,eAAO,MAAM,YAAY,qBAUxB,CAAC;AAEF,eAAO,MAAM,iBAAiB,gBAAuB,MAAM,QAAQ,MAAM,kBAUxE,CAAC;AAEF,eAAO,MAAM,mBAAmB,qBAU/B,CAAC;AAEF,eAAO,MAAM,cAAc,aACb,MAAM,oBACE,MAAM,kBAW3B,CAAC;AAEF,eAAO,MAAM,UAAU,YAAmB,MAAM,CAAC,SAAS,CAAC,kBAM1D,CAAC;AAEF,eAAO,MAAM,SAAS,WAAkB,MAAM,CAAC,SAAS,CAAC,kBAMxD,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAQA,eAAO,MAAM,cAAc,QAAsC,CAAC;AAElE,MAAM,MAAM,MAAM,GAAG;IACjB,IAAI,CAAC,EAAE;QACH,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;KAC7B,CAAC;IACF,OAAO,CAAC,EAAE;QACN,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB;;;WAGG;QACH,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,WAAW,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;IACF,OAAO,CAAC,EAAE;QACN,qCAAqC,CAAC,EAAE,OAAO,CAAC;QAChD,gCAAgC,CAAC,EAAE,OAAO,CAAC;KAC9C,CAAC;CACL,CAAC;AAEF,qEAAqE;AACrE,eAAO,MAAM,2BAA2B,aAC1B,MAAM,KACjB,OAAO,CAAC,IAAI,CAgBd,CAAC;AAEF,qEAAqE;AACrE,eAAO,MAAM,iBAAiB,aAChB,MAAM,UACR,MAAM,KACf,OAAO,CAAC,IAAI,CAed,CAAC;AAiCF,eAAO,MAAM,SAAS,QAAa,OAAO,CAAC,MAAM,CAmBhD,CAAC;AAEF,eAAO,MAAM,UAAU,gBAAuB,MAAM,eAAe,MAAM,kBAUxE,CAAC;AAEF,eAAO,MAAM,YAAY,qBAUxB,CAAC;AAEF,eAAO,MAAM,iBAAiB,gBAAuB,MAAM,QAAQ,MAAM,kBAUxE,CAAC;AAEF,eAAO,MAAM,mBAAmB,qBAU/B,CAAC;AAEF,eAAO,MAAM,cAAc,aACb,MAAM,oBACE,MAAM,kBAW3B,CAAC;AAEF,eAAO,MAAM,UAAU,YAAmB,MAAM,CAAC,SAAS,CAAC,kBAM1D,CAAC;AAEF,eAAO,MAAM,SAAS,WAAkB,MAAM,CAAC,SAAS,CAAC,kBAMxD,CAAC"}

package/dist/config.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.setAnswer = exports.setContext = exports.setDefaultUser = exports.unsetPreviewProject = exports.setPreviewProject = exports.unsetProject = exports.setProject = exports.getConfig = exports.configFilePath = void 0;
+exports.setAnswer = exports.setContext = exports.setDefaultUser = exports.unsetPreviewProject = exports.setPreviewProject = exports.unsetProject = exports.setProject = exports.getConfig = exports.writeConfigToFile = exports.ensureConfigFilePermissions = exports.configFilePath = void 0;
 const tslib_1 = require("tslib");
 const fs_1 = require("fs");
 const yaml = tslib_1.__importStar(require("js-yaml"));
@@ -10,13 +10,48 @@ const path = tslib_1.__importStar(require("path"));
 const uuid_1 = require("uuid");
 const configDir = path.join(os.homedir(), '.config', 'lightdash');
 exports.configFilePath = path.join(configDir, 'config.yaml');
+/** @internal Exported for filesystem-permission regression tests. */
+const ensureConfigFilePermissions = async (filePath) => {
+    if (process.platform === 'win32')
+        return;
+    await fs_1.promises.chmod(path.dirname(filePath), 0o700);
+    try {
+        await fs_1.promises.chmod(filePath, 0o600);
+    }
+    catch (error) {
+        if (!(error instanceof Error &&
+            'code' in error &&
+            error.code === 'ENOENT')) {
+            throw error;
+        }
+    }
+};
+exports.ensureConfigFilePermissions = ensureConfigFilePermissions;
+/** @internal Exported for filesystem-permission regression tests. */
+const writeConfigToFile = async (filePath, config) => {
+    const directory = path.dirname(filePath);
+    await fs_1.promises.mkdir(directory, { recursive: true, mode: 0o700 });
+    // Tighten an existing config before overwriting it. `mode` on writeFile
+    // only applies when it creates a new file.
+    await (0, exports.ensureConfigFilePermissions)(filePath);
+    await fs_1.promises.writeFile(filePath, yaml.dump(config), {
+        encoding: 'utf8',
+        mode: 0o600,
+    });
+    // `mode` only applies when mkdir/writeFile creates a path. Tighten
+    // existing CLI config paths as well; Windows does not implement POSIX
+    // permission bits, so leave ACL management to the OS there.
+    await (0, exports.ensureConfigFilePermissions)(filePath);
+};
+exports.writeConfigToFile = writeConfigToFile;
 const setConfig = async (config) => {
-    await fs_1.promises.mkdir(path.dirname(exports.configFilePath), { recursive: true });
-    await fs_1.promises.writeFile(exports.configFilePath, yaml.dump(config), 'utf8');
+    await (0, exports.writeConfigToFile)(exports.configFilePath, config);
 };
 const getRawConfig = async () => {
     try {
-        const raw = yaml.load(await fs_1.promises.readFile(exports.configFilePath, 'utf8'));
+        await (0, exports.ensureConfigFilePermissions)(exports.configFilePath);
+        const contents = await fs_1.promises.readFile(exports.configFilePath, 'utf8');
+        const raw = yaml.load(contents);
         return raw;
     }
     catch (e) {

package/dist/config.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=config.test.d.ts.map

package/dist/config.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.test.d.ts","sourceRoot":"","sources":["../src/config.test.ts"],"names":[],"mappings":""}

package/dist/config.test.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const fs_1 = require("fs");
+const os = tslib_1.__importStar(require("os"));
+const path = tslib_1.__importStar(require("path"));
+const config_1 = require("./config");
+// Masking file-type bits is the standard way to assert POSIX permissions.
+// eslint-disable-next-line no-bitwise
+const permissionBits = (mode) => mode & 0o777;
+const describePosix = process.platform === 'win32' ? describe.skip : describe;
+describePosix('CLI config permissions', () => {
+    let tempDir;
+    let configDir;
+    let configPath;
+    beforeEach(async () => {
+        tempDir = await fs_1.promises.mkdtemp(path.join(os.tmpdir(), 'ld-config-'));
+        configDir = path.join(tempDir, 'lightdash');
+        configPath = path.join(configDir, 'config.yaml');
+    });
+    afterEach(async () => {
+        await fs_1.promises.rm(tempDir, { recursive: true, force: true });
+    });
+    it('creates the config directory and file with private permissions', async () => {
+        await (0, config_1.writeConfigToFile)(configPath, {
+            context: { apiKey: 'ldpat_secret' },
+        });
+        expect(permissionBits((await fs_1.promises.stat(configDir)).mode)).toBe(0o700);
+        expect(permissionBits((await fs_1.promises.stat(configPath)).mode)).toBe(0o600);
+    });
+    it('tightens permissions on an existing config path', async () => {
+        await fs_1.promises.mkdir(configDir, { recursive: true, mode: 0o755 });
+        await fs_1.promises.writeFile(configPath, 'context: {}', { mode: 0o644 });
+        await fs_1.promises.chmod(configDir, 0o755);
+        await fs_1.promises.chmod(configPath, 0o644);
+        await (0, config_1.ensureConfigFilePermissions)(configPath);
+        expect(permissionBits((await fs_1.promises.stat(configDir)).mode)).toBe(0o700);
+        expect(permissionBits((await fs_1.promises.stat(configPath)).mode)).toBe(0o600);
+    });
+});

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

@@ -53,5 +53,6 @@ export declare const applySdkMirrorToTemplateDeps: (templateDependencies: Record
  * deps (payload stays identical to today's format).
  */
 export declare const attachDependenciesToCode: (code: DataAppCode, customDeps: Record<string, string>, deps: DataAppDependencies) => DataAppCode;
+export declare const readManifestFromDir: (dir: string) => Promise<DataAppManifest>;
 export declare const readBundleFromDir: (dir: string) => Promise<DataAppCode>;
 //# sourceMappingURL=appCodeFiles.d.ts.map

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,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"}
+{"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,mBAAmB,QACvB,MAAM,KACZ,OAAO,CAAC,eAAe,CAYzB,CAAC;AAEF,eAAO,MAAM,iBAAiB,QAAe,MAAM,KAAG,OAAO,CAAC,WAAW,CAYxE,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.resolveAppFolderName = exports.buildImportBody = exports.writeBundleToDir = exports.writeContextToDir = exports.writeFilesToDir = exports.appFolderName = void 0;
+exports.readBundleFromDir = exports.readManifestFromDir = 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");
@@ -209,15 +209,18 @@ exports.applySdkMirrorToTemplateDeps = applySdkMirrorToTemplateDeps;
  */
 const attachDependenciesToCode = (code, customDeps, deps) => Object.keys(customDeps).length > 0 ? { ...code, dependencies: deps } : code;
 exports.attachDependenciesToCode = attachDependenciesToCode;
-const readBundleFromDir = async (dir) => {
+const readManifestFromDir = async (dir) => {
     const manifestRaw = await fs_1.promises.readFile(path.join(dir, MANIFEST_FILENAME), 'utf-8');
-    let manifest;
     try {
-        manifest = YAML.parse(manifestRaw);
+        return YAML.parse(manifestRaw);
     }
     catch (err) {
         throw new Error(`Could not parse ${MANIFEST_FILENAME}: ${(0, common_1.getErrorMessage)(err)}`);
     }
+};
+exports.readManifestFromDir = readManifestFromDir;
+const readBundleFromDir = async (dir) => {
+    const manifest = await (0, exports.readManifestFromDir)(dir);
     const srcDir = path.join(dir, 'src');
     const srcExists = await fs_1.promises
         .stat(srcDir)

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

@@ -107,6 +107,12 @@ const bundle = {
         },
     ],
 };
+it('readManifestFromDir returns just the manifest', async () => {
+    const dir = await fs_1.promises.mkdtemp(path.join(os.tmpdir(), 'ld-app-'));
+    await (0, appCodeFiles_1.writeBundleToDir)(dir, bundle);
+    const manifest = await (0, appCodeFiles_1.readManifestFromDir)(dir);
+    expect(manifest).toEqual(bundle.manifest);
+});
 it('writes then reads back an identical bundle', async () => {
     const dir = await fs_1.promises.mkdtemp(path.join(os.tmpdir(), 'ld-app-'));
     await (0, appCodeFiles_1.writeBundleToDir)(dir, bundle);
@@ -141,8 +147,10 @@ it('upload reads back only src/ files, ignoring scaffolding and context', async
     await fs_1.promises.writeFile(path.join(dir, 'package.json'), '{"name":"x"}');
     await fs_1.promises.writeFile(path.join(dir, '.lightdash/context/semantic-layer.yml'), 'models: []');
     await fs_1.promises.writeFile(path.join(dir, '.claude/skills/x/SKILL.md'), '# skill');
+    await fs_1.promises.writeFile(path.join(dir, '.env.local'), 'VITE_LIGHTDASH_API_KEY=secret');
     const read = await (0, appCodeFiles_1.readBundleFromDir)(dir);
     expect(read.files.every((f) => f.path.startsWith('src/'))).toBe(true);
+    expect(read.files.map((f) => f.path)).not.toContain('.env.local');
     expect(read.files.map((f) => f.path).sort()).toEqual(bundle.files.map((f) => f.path).sort());
 });
 it('throws a clear error when the manifest is not valid YAML', async () => {

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

@@ -0,0 +1,56 @@
+/**
+ * Environment passed to the `npm run dev` child process. Only the small set of
+ * host variables needed to launch a portable child process is inherited. In
+ * particular, no Lightdash credential or unrelated parent-process secret is
+ * copied into vite. The nonce is exposed to browser code as a run-scoped,
+ * project- and route-limited capability; it is not a Lightdash credential.
+ */
+export declare const buildPreviewChildEnv: (args: {
+    serverUrl: string;
+    projectUuid: string;
+    proxyPort: number;
+    proxyNonce: string;
+    parentEnv?: NodeJS.ProcessEnv;
+}) => Record<string, string>;
+/**
+ * Older downloads have a vite.config.js that proxies /api straight to the
+ * instance and expects the credential in .env.local — incompatible with the
+ * proxy-based flow (requests would go out uncredentialed and 401).
+ */
+export declare const assertScaffoldingSupportsPreviewProxy: (appDir: string) => Promise<void>;
+export declare const resolvePreviewTarget: (args: {
+    pathArg?: string;
+    projectFlag?: string;
+    cwd: string;
+}) => Promise<{
+    appDir: string;
+    projectUuid: string;
+}>;
+export declare const assertNodeModulesPresent: (appDir: string) => Promise<void>;
+/**
+ * The login context can point at a different instance than the one the app
+ * was downloaded from — the credential pre-flight passes there, but the
+ * app's project doesn't exist, which would surface as a confusing 404
+ * inside the running app.
+ */
+export declare const projectNotFoundMessage: (args: {
+    projectUuid: string;
+    serverUrl: string;
+}) => string;
+export declare const preflightPreviewRequest: (args: {
+    apiPath: string;
+    serverUrl: string;
+    authorization: string;
+    proxyAuthorization?: string;
+    fetchFn?: typeof fetch;
+}) => Promise<boolean>;
+export declare const removeLegacyPreviewCredential: (appDir: string) => Promise<boolean>;
+type AppsPreviewOptions = {
+    project?: string;
+    url?: string;
+    token?: string;
+    verbose: boolean;
+};
+export declare const appsPreviewHandler: (pathArg: string | undefined, options: AppsPreviewOptions) => Promise<void>;
+export {};
+//# sourceMappingURL=preview.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"preview.d.ts","sourceRoot":"","sources":["../../../src/handlers/apps/preview.ts"],"names":[],"mappings":"AAaA;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,SAAU;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACjC,KAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CA2CxB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,qCAAqC,WACtC,MAAM,KACf,OAAO,CAAC,IAAI,CASd,CAAC;AAEF,eAAO,MAAM,oBAAoB,SAAgB;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;CACf,KAAG,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAqBlD,CAAC;AAEF,eAAO,MAAM,wBAAwB,WACzB,MAAM,KACf,OAAO,CAAC,IAAI,CAUd,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,SAAU;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;CACrB,KAAG,MACgT,CAAC;AAErT,eAAO,MAAM,uBAAuB,SAAgB;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B,KAAG,OAAO,CAAC,OAAO,CAmBlB,CAAC;AAKF,eAAO,MAAM,6BAA6B,WAC9B,MAAM,KACf,OAAO,CAAC,OAAO,CAmBjB,CAAC;AAkBF,KAAK,kBAAkB,GAAG;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,eAAO,MAAM,kBAAkB,YAClB,MAAM,GAAG,SAAS,WAClB,kBAAkB,KAC5B,OAAO,CAAC,IAAI,CA+Gd,CAAC"}

package/dist/handlers/apps/preview.js

@@ -0,0 +1,262 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.appsPreviewHandler = exports.removeLegacyPreviewCredential = exports.preflightPreviewRequest = exports.projectNotFoundMessage = exports.assertNodeModulesPresent = exports.resolvePreviewTarget = exports.assertScaffoldingSupportsPreviewProxy = exports.buildPreviewChildEnv = void 0;
+const tslib_1 = require("tslib");
+const common_1 = require("@lightdash/common");
+const crypto_1 = require("crypto");
+const execa_1 = tslib_1.__importDefault(require("execa"));
+const fs_1 = require("fs");
+const path = tslib_1.__importStar(require("path"));
+const config_1 = require("../../config");
+const globalState_1 = tslib_1.__importDefault(require("../../globalState"));
+const styles = tslib_1.__importStar(require("../../styles"));
+const apiClient_1 = require("../dbt/apiClient");
+const utils_1 = require("../utils");
+const appCodeFiles_1 = require("./appCodeFiles");
+const previewProxy_1 = require("./previewProxy");
+/**
+ * Environment passed to the `npm run dev` child process. Only the small set of
+ * host variables needed to launch a portable child process is inherited. In
+ * particular, no Lightdash credential or unrelated parent-process secret is
+ * copied into vite. The nonce is exposed to browser code as a run-scoped,
+ * project- and route-limited capability; it is not a Lightdash credential.
+ */
+const buildPreviewChildEnv = (args) => {
+    const parentEnv = args.parentEnv ?? process.env;
+    const passthroughKeys = [
+        'APPDATA',
+        'CI',
+        'COLORTERM',
+        'COMSPEC',
+        'ComSpec',
+        'FORCE_COLOR',
+        'HOME',
+        'LANG',
+        'LC_ALL',
+        'LOCALAPPDATA',
+        'NODE_OPTIONS',
+        'NODE_PATH',
+        'NO_COLOR',
+        'PATH',
+        'PATHEXT',
+        'PNPM_HOME',
+        'SHELL',
+        'SYSTEMROOT',
+        'SystemRoot',
+        'TEMP',
+        'TERM',
+        'TMP',
+        'TMPDIR',
+        'USERPROFILE',
+        'WINDIR',
+    ];
+    const childEnv = {};
+    for (const key of passthroughKeys) {
+        const value = parentEnv[key];
+        if (value !== undefined)
+            childEnv[key] = value;
+    }
+    return {
+        ...childEnv,
+        VITE_LIGHTDASH_URL: args.serverUrl.replace(/\/+$/, ''),
+        VITE_LIGHTDASH_API_KEY: args.proxyNonce,
+        VITE_LIGHTDASH_PROJECT_UUID: args.projectUuid,
+        LIGHTDASH_PREVIEW_PROXY_TARGET: `http://127.0.0.1:${args.proxyPort}`,
+        LIGHTDASH_PREVIEW_PROXY_NONCE: args.proxyNonce,
+    };
+};
+exports.buildPreviewChildEnv = buildPreviewChildEnv;
+/**
+ * Older downloads have a vite.config.js that proxies /api straight to the
+ * instance and expects the credential in .env.local — incompatible with the
+ * proxy-based flow (requests would go out uncredentialed and 401).
+ */
+const assertScaffoldingSupportsPreviewProxy = async (appDir) => {
+    const viteConfig = await fs_1.promises
+        .readFile(path.join(appDir, 'vite.config.js'), 'utf-8')
+        .catch(() => '');
+    if (!viteConfig.includes('LIGHTDASH_PREVIEW_PROXY_TARGET')) {
+        throw new Error(`This app's scaffolding predates the secure preview proxy. Re-download the app ('lightdash download --apps <appUuid>') to refresh vite.config.js, then run preview again.`);
+    }
+};
+exports.assertScaffoldingSupportsPreviewProxy = assertScaffoldingSupportsPreviewProxy;
+const resolvePreviewTarget = async (args) => {
+    const appDir = args.pathArg
+        ? path.resolve(args.cwd, args.pathArg)
+        : args.cwd;
+    let manifest;
+    try {
+        manifest = await (0, appCodeFiles_1.readManifestFromDir)(appDir);
+    }
+    catch (err) {
+        if (err.code === 'ENOENT') {
+            throw new Error(`No lightdash-app.yml found in ${appDir}. Run this from a downloaded app folder (apps/<slug>/), or pass it as an argument: lightdash apps preview <path>.`);
+        }
+        throw err;
+    }
+    return {
+        appDir,
+        projectUuid: args.projectFlag ?? manifest.projectUuid,
+    };
+};
+exports.resolvePreviewTarget = resolvePreviewTarget;
+const assertNodeModulesPresent = async (appDir) => {
+    const isDir = await fs_1.promises
+        .stat(path.join(appDir, 'node_modules'))
+        .then((s) => s.isDirectory())
+        .catch(() => false);
+    if (!isDir) {
+        throw new Error(`Dependencies are not installed. Run 'npm install' in ${appDir} first (preview does not auto-install).`);
+    }
+};
+exports.assertNodeModulesPresent = assertNodeModulesPresent;
+/**
+ * The login context can point at a different instance than the one the app
+ * was downloaded from — the credential pre-flight passes there, but the
+ * app's project doesn't exist, which would surface as a confusing 404
+ * inside the running app.
+ */
+const projectNotFoundMessage = (args) => `Project ${args.projectUuid} was not found on ${args.serverUrl} (or you don't have access). This app belongs to a different project or instance than the one you're logged into — run 'lightdash login <url>' for the server the app was downloaded from, or pass --project to preview against another project.`;
+exports.projectNotFoundMessage = projectNotFoundMessage;
+const preflightPreviewRequest = async (args) => {
+    const fetchFn = args.fetchFn ?? fetch;
+    try {
+        const res = await fetchFn(new URL(args.apiPath, args.serverUrl), {
+            headers: {
+                Authorization: args.authorization,
+                ...(args.proxyAuthorization
+                    ? { 'Proxy-Authorization': args.proxyAuthorization }
+                    : {}),
+            },
+        });
+        return res.ok;
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : 'Unknown network error';
+        throw new Error(`Could not connect to ${args.serverUrl} while starting preview: ${reason}`);
+    }
+};
+exports.preflightPreviewRequest = preflightPreviewRequest;
+const LEGACY_PREVIEW_CREDENTIAL = /^[ \t]*(?:export[ \t]+)?LIGHTDASH_PREVIEW_API_KEY[ \t]*=.*(?:\r?\n|$)/gm;
+const removeLegacyPreviewCredential = async (appDir) => {
+    const legacyEnvPath = path.join(appDir, '.env.local');
+    let legacyEnv;
+    try {
+        legacyEnv = await fs_1.promises.readFile(legacyEnvPath, 'utf-8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+    const sanitizedEnv = legacyEnv.replace(LEGACY_PREVIEW_CREDENTIAL, '');
+    if (sanitizedEnv === legacyEnv)
+        return false;
+    if (sanitizedEnv.trim() === '') {
+        await fs_1.promises.unlink(legacyEnvPath);
+    }
+    else {
+        await fs_1.promises.writeFile(legacyEnvPath, sanitizedEnv, 'utf-8');
+    }
+    return true;
+};
+exports.removeLegacyPreviewCredential = removeLegacyPreviewCredential;
+// Ctrl-C is the documented way to stop the dev server, so an interrupted child
+// is a normal exit rather than a crash to report. The runner may either die
+// from the signal or translate it into the conventional 128+signal exit code.
+const isUserStoppedDevServer = (error) => {
+    if (!(error instanceof Error)) {
+        return false;
+    }
+    const { signal, exitCode } = error;
+    return (signal === 'SIGINT' ||
+        signal === 'SIGTERM' ||
+        exitCode === 130 ||
+        exitCode === 143);
+};
+const appsPreviewHandler = async (pathArg, options) => {
+    globalState_1.default.setVerbose(options.verbose);
+    const config = await (0, config_1.getConfig)();
+    const serverUrl = options.url ?? config.context?.serverUrl;
+    // getConfig() already folds LIGHTDASH_API_KEY into context.apiKey, so the
+    // env-var path is safe. The only exposure is an explicit --token on the
+    // command line (visible in shell history / `ps aux`) — warn rather than
+    // block, since --token is a supported CI path.
+    const apiKey = options.token ?? config.context?.apiKey;
+    if (!serverUrl || !apiKey) {
+        throw new common_1.AuthorizationError(`Not logged in or missing server URL. Run 'lightdash login <url>' first, or set LIGHTDASH_URL and LIGHTDASH_API_KEY.`);
+    }
+    const authorization = (0, utils_1.getAuthHeader)(apiKey);
+    const proxyAuthorization = config.context?.proxyAuthorization;
+    if (options.token) {
+        globalState_1.default.log(styles.warning(`Passing --token on the command line exposes it in your shell history and process list. Prefer 'lightdash login' or the LIGHTDASH_API_KEY environment variable.`));
+    }
+    const target = await (0, exports.resolvePreviewTarget)({
+        pathArg,
+        projectFlag: options.project,
+        cwd: process.cwd(),
+    });
+    await (0, exports.assertNodeModulesPresent)(target.appDir);
+    await (0, exports.assertScaffoldingSupportsPreviewProxy)(target.appDir);
+    // Pre-flight the credential before starting vite: an expired/revoked
+    // token would otherwise surface as opaque query failures inside the app.
+    // Flag-supplied credentials (--url/--token) bypass the stored config, so
+    // hit the API directly with exactly what the proxy will forward.
+    if (!options.url && !options.token) {
+        await (0, apiClient_1.checkLightdashVersion)();
+    }
+    const preflight = (apiPath) => (0, exports.preflightPreviewRequest)({
+        apiPath,
+        serverUrl,
+        authorization,
+        proxyAuthorization,
+    });
+    if (!(await preflight('/api/v1/user'))) {
+        throw new common_1.AuthorizationError(`Your Lightdash credential was rejected by ${serverUrl}. Run 'lightdash login ${serverUrl}' to refresh it, or check the --url/--token values.`);
+    }
+    if (!(await preflight(`/api/v1/projects/${target.projectUuid}`))) {
+        throw new Error((0, exports.projectNotFoundMessage)({
+            projectUuid: target.projectUuid,
+            serverUrl,
+        }));
+    }
+    // Previous versions persisted this credential in .env.local. Remove only
+    // that obsolete entry, preserving any unrelated user-managed settings.
+    if (await (0, exports.removeLegacyPreviewCredential)(target.appDir)) {
+        globalState_1.default.log(styles.warning(`Removed an obsolete preview credential from ${path.join(target.appDir, '.env.local')}.`));
+    }
+    const proxyNonce = (0, crypto_1.randomBytes)(16).toString('hex');
+    const proxy = await (0, previewProxy_1.startPreviewProxy)({
+        upstreamUrl: serverUrl,
+        authorization,
+        proxyAuthorization,
+        projectUuid: target.projectUuid,
+        nonce: proxyNonce,
+    });
+    globalState_1.default.log(`Preview proxy on 127.0.0.1:${proxy.port} — your credential is not passed to the app; SDK traffic is restricted to project ${target.projectUuid}.`);
+    globalState_1.default.log(styles.warning(`Preview renders YOUR data with YOUR permissions and user attributes — viewers of the deployed app may see different data.`));
+    globalState_1.default.log(`Starting dev server (Ctrl-C to stop)…`);
+    try {
+        await (0, execa_1.default)('npm', ['run', 'dev'], {
+            cwd: target.appDir,
+            stdio: 'inherit',
+            extendEnv: false,
+            env: (0, exports.buildPreviewChildEnv)({
+                serverUrl,
+                projectUuid: target.projectUuid,
+                proxyPort: proxy.port,
+                proxyNonce,
+            }),
+        });
+    }
+    catch (e) {
+        if (!isUserStoppedDevServer(e)) {
+            throw e;
+        }
+        globalState_1.default.log('Preview stopped.');
+    }
+    finally {
+        await proxy.close();
+    }
+};
+exports.appsPreviewHandler = appsPreviewHandler;

package/dist/handlers/apps/preview.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=preview.test.d.ts.map

package/dist/handlers/apps/preview.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview.test.d.ts","sourceRoot":"","sources":["../../../src/handlers/apps/preview.test.ts"],"names":[],"mappings":""}