@lightdash/cli 1.44.0 → 1.46.0

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

@@ -0,0 +1,189 @@
+"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 utils_1 = require("../utils");
+const appCodeFiles_1 = require("./appCodeFiles");
+const preview_1 = require("./preview");
+const previewBundle = {
+    manifest: {
+        codeVersion: 1,
+        appUuid: 'app-uuid-1',
+        projectUuid: 'proj-uuid-1',
+        version: 2,
+        name: 'Preview App',
+        description: '',
+        template: null,
+        downloadedAt: '2026-07-01T00:00:00.000Z',
+    },
+    files: [],
+};
+describe('getAuthHeader', () => {
+    it('uses ApiKey authentication for personal access tokens', () => {
+        expect((0, utils_1.getAuthHeader)('ldpat_secret')).toBe('ApiKey ldpat_secret');
+    });
+    it('uses Bearer authentication for service-account tokens', () => {
+        expect((0, utils_1.getAuthHeader)('ldsvc_secret')).toBe('Bearer ldsvc_secret');
+    });
+});
+describe('buildPreviewChildEnv', () => {
+    it('passes through only required host variables and no parent secrets', () => {
+        const env = (0, preview_1.buildPreviewChildEnv)({
+            serverUrl: 'http://localhost:3000',
+            projectUuid: 'proj-uuid-1',
+            proxyPort: 45678,
+            proxyNonce: 'nonce-abc',
+            parentEnv: {
+                HOME: '/home/developer',
+                PATH: '/usr/bin',
+                LIGHTDASH_API_KEY: 'ldpat_parent_secret',
+                LIGHTDASH_PROXY_AUTHORIZATION: 'Basic parent-secret',
+                NPM_TOKEN: 'npm_parent_secret',
+                VITE_LIGHTDASH_API_KEY: 'ldpat_browser_secret',
+            },
+        });
+        expect(env).toEqual({
+            HOME: '/home/developer',
+            PATH: '/usr/bin',
+            VITE_LIGHTDASH_URL: 'http://localhost:3000',
+            VITE_LIGHTDASH_API_KEY: 'nonce-abc',
+            VITE_LIGHTDASH_PROJECT_UUID: 'proj-uuid-1',
+            LIGHTDASH_PREVIEW_PROXY_TARGET: 'http://127.0.0.1:45678',
+            LIGHTDASH_PREVIEW_PROXY_NONCE: 'nonce-abc',
+        });
+        expect(env).not.toHaveProperty('LIGHTDASH_API_KEY');
+        expect(env).not.toHaveProperty('LIGHTDASH_PROXY_AUTHORIZATION');
+        expect(env).not.toHaveProperty('NPM_TOKEN');
+        for (const value of Object.values(env)) {
+            expect(value).not.toMatch(/^ld(pat|svc)_/);
+        }
+    });
+    it('strips a trailing slash from the server url', () => {
+        const env = (0, preview_1.buildPreviewChildEnv)({
+            serverUrl: 'http://localhost:3000/',
+            projectUuid: 'p',
+            proxyPort: 1,
+            proxyNonce: 'n',
+        });
+        expect(env.VITE_LIGHTDASH_URL).toBe('http://localhost:3000');
+    });
+});
+describe('assertScaffoldingSupportsPreviewProxy', () => {
+    it('passes when vite.config.js reads the proxy target', async () => {
+        const dir = await fs_1.promises.mkdtemp(path.join(os.tmpdir(), 'ld-prev-'));
+        await fs_1.promises.writeFile(path.join(dir, 'vite.config.js'), 'const t = env.LIGHTDASH_PREVIEW_PROXY_TARGET;');
+        await expect((0, preview_1.assertScaffoldingSupportsPreviewProxy)(dir)).resolves.toBeUndefined();
+    });
+    it('rejects pre-proxy scaffolding with a re-download instruction', async () => {
+        const dir = await fs_1.promises.mkdtemp(path.join(os.tmpdir(), 'ld-prev-'));
+        await fs_1.promises.writeFile(path.join(dir, 'vite.config.js'), 'const k = env.LIGHTDASH_PREVIEW_API_KEY;');
+        await expect((0, preview_1.assertScaffoldingSupportsPreviewProxy)(dir)).rejects.toThrow(/Re-download the app/);
+    });
+});
+describe('resolvePreviewTarget', () => {
+    it('defaults appDir to cwd and project to the manifest projectUuid', async () => {
+        const dir = await fs_1.promises.mkdtemp(path.join(os.tmpdir(), 'ld-prev-'));
+        await (0, appCodeFiles_1.writeBundleToDir)(dir, previewBundle);
+        const target = await (0, preview_1.resolvePreviewTarget)({ cwd: dir });
+        expect(target.appDir).toBe(dir);
+        expect(target.projectUuid).toBe('proj-uuid-1');
+    });
+    it('resolves a relative path arg against cwd and honors --project override', async () => {
+        const parent = await fs_1.promises.mkdtemp(path.join(os.tmpdir(), 'ld-prev-'));
+        const appDir = path.join(parent, 'apps', 'my-app');
+        await (0, appCodeFiles_1.writeBundleToDir)(appDir, previewBundle);
+        const target = await (0, preview_1.resolvePreviewTarget)({
+            pathArg: 'apps/my-app',
+            projectFlag: 'other-proj',
+            cwd: parent,
+        });
+        expect(target.appDir).toBe(appDir);
+        expect(target.projectUuid).toBe('other-proj');
+    });
+    it('errors clearly when the folder has no manifest', async () => {
+        const dir = await fs_1.promises.mkdtemp(path.join(os.tmpdir(), 'ld-prev-'));
+        await expect((0, preview_1.resolvePreviewTarget)({ cwd: dir })).rejects.toThrow(/No lightdash-app\.yml found in/);
+    });
+});
+describe('assertNodeModulesPresent', () => {
+    it('passes when node_modules exists', async () => {
+        const dir = await fs_1.promises.mkdtemp(path.join(os.tmpdir(), 'ld-prev-'));
+        await fs_1.promises.mkdir(path.join(dir, 'node_modules'));
+        await expect((0, preview_1.assertNodeModulesPresent)(dir)).resolves.toBeUndefined();
+    });
+    it('errors telling the user to npm install, without installing', async () => {
+        const dir = await fs_1.promises.mkdtemp(path.join(os.tmpdir(), 'ld-prev-'));
+        await expect((0, preview_1.assertNodeModulesPresent)(dir)).rejects.toThrow(/Run 'npm install' in .* \(preview does not auto-install\)/);
+    });
+});
+describe('projectNotFoundMessage', () => {
+    it('names the project, the server, and both remedies', () => {
+        const msg = (0, preview_1.projectNotFoundMessage)({
+            projectUuid: 'proj-uuid-1',
+            serverUrl: 'https://cloud.example.com',
+        });
+        expect(msg).toContain('proj-uuid-1');
+        expect(msg).toContain('https://cloud.example.com');
+        expect(msg).toMatch(/lightdash login/);
+        expect(msg).toMatch(/--project/);
+    });
+});
+describe('preflightPreviewRequest', () => {
+    it('reports network failures separately from rejected credentials', async () => {
+        const fetchFn = vi
+            .fn()
+            .mockRejectedValue(new Error('connection refused'));
+        await expect((0, preview_1.preflightPreviewRequest)({
+            apiPath: '/api/v1/user',
+            serverUrl: 'http://localhost:8080',
+            authorization: 'ApiKey test',
+            fetchFn,
+        })).rejects.toThrow('Could not connect to http://localhost:8080 while starting preview: connection refused');
+    });
+    it('returns false for an HTTP rejection', async () => {
+        const fetchFn = vi
+            .fn()
+            .mockResolvedValue({ ok: false });
+        await expect((0, preview_1.preflightPreviewRequest)({
+            apiPath: '/api/v1/user',
+            serverUrl: 'http://localhost:8080',
+            authorization: 'ApiKey test',
+            fetchFn,
+        })).resolves.toBe(false);
+    });
+});
+describe('removeLegacyPreviewCredential', () => {
+    it('removes only the obsolete credential and preserves other settings', async () => {
+        const dir = await fs_1.promises.mkdtemp(path.join(os.tmpdir(), 'ld-prev-'));
+        const envPath = path.join(dir, '.env.local');
+        await fs_1.promises.writeFile(envPath, [
+            'VITE_CUSTOM_SETTING=keep-me',
+            'LIGHTDASH_PREVIEW_API_KEY=ldpat_remove_me',
+            '# LIGHTDASH_PREVIEW_API_KEY=commented-out',
+            'ANOTHER_SETTING=also-keep-me',
+            '',
+        ].join('\n'));
+        await expect((0, preview_1.removeLegacyPreviewCredential)(dir)).resolves.toBe(true);
+        await expect(fs_1.promises.readFile(envPath, 'utf-8')).resolves.toBe([
+            'VITE_CUSTOM_SETTING=keep-me',
+            '# LIGHTDASH_PREVIEW_API_KEY=commented-out',
+            'ANOTHER_SETTING=also-keep-me',
+            '',
+        ].join('\n'));
+    });
+    it('deletes an env file that contains only the obsolete credential', async () => {
+        const dir = await fs_1.promises.mkdtemp(path.join(os.tmpdir(), 'ld-prev-'));
+        const envPath = path.join(dir, '.env.local');
+        await fs_1.promises.writeFile(envPath, 'export LIGHTDASH_PREVIEW_API_KEY=ldpat_remove_me\n');
+        await expect((0, preview_1.removeLegacyPreviewCredential)(dir)).resolves.toBe(true);
+        await expect(fs_1.promises.stat(envPath)).rejects.toMatchObject({
+            code: 'ENOENT',
+        });
+    });
+    it('does nothing when there is no legacy credential', async () => {
+        const dir = await fs_1.promises.mkdtemp(path.join(os.tmpdir(), 'ld-prev-'));
+        await expect((0, preview_1.removeLegacyPreviewCredential)(dir)).resolves.toBe(false);
+    });
+});

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

@@ -0,0 +1,20 @@
+export declare const PREVIEW_PROXY_NONCE_HEADER = "x-lightdash-preview-nonce";
+export type PreviewProxyHandle = {
+    port: number;
+    close: () => Promise<void>;
+};
+/**
+ * Loopback proxy that owns the preview credential. The vite dev server
+ * forwards /api traffic here; only routes a deployed app could reach through
+ * the SDK bridge — pinned to the previewed project — are forwarded upstream,
+ * with the credential attached server-side. Preview does not write it into the
+ * app folder or pass it to the vite process/browser.
+ */
+export declare const startPreviewProxy: (args: {
+    upstreamUrl: string;
+    authorization: string;
+    proxyAuthorization?: string;
+    projectUuid: string;
+    nonce: string;
+}) => Promise<PreviewProxyHandle>;
+//# sourceMappingURL=previewProxy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"previewProxy.d.ts","sourceRoot":"","sources":["../../../src/handlers/apps/previewProxy.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,0BAA0B,8BAA8B,CAAC;AA6CtE,MAAM,MAAM,kBAAkB,GAAG;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B,CAAC;AAyBF;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,SAAU;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;CACjB,KAAG,OAAO,CAAC,kBAAkB,CA+G7B,CAAC"}

package/dist/handlers/apps/previewProxy.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startPreviewProxy = exports.PREVIEW_PROXY_NONCE_HEADER = void 0;
+const tslib_1 = require("tslib");
+const common_1 = require("@lightdash/common");
+const crypto_1 = require("crypto");
+const http = tslib_1.__importStar(require("http"));
+const https = tslib_1.__importStar(require("https"));
+// Per-run shared secret between the browser, Vite, and the CLI proxy. Vite
+// forwards the browser's scoped Authorization value and adds this header;
+// both must match before the durable credential is attached upstream.
+exports.PREVIEW_PROXY_NONCE_HEADER = 'x-lightdash-preview-nonce';
+// Hop-by-hop headers are connection-scoped and must not be forwarded.
+const HOP_BY_HOP_HEADERS = new Set([
+    'connection',
+    'keep-alive',
+    'proxy-authenticate',
+    'proxy-authorization',
+    'te',
+    'trailer',
+    'transfer-encoding',
+    'upgrade',
+]);
+// Client → upstream: host is derived from the upstream URL; the browser-side
+// scoped preview capability and the nonce must not travel upstream, and
+// localhost cookies are not the instance's business.
+const DROPPED_REQUEST_HEADERS = new Set([
+    'host',
+    'authorization',
+    'cookie',
+    exports.PREVIEW_PROXY_NONCE_HEADER,
+]);
+// Upstream → client: the instance must not plant cookies on the dev origin.
+const DROPPED_RESPONSE_HEADERS = new Set(['set-cookie']);
+const filterHeaders = (source, dropped) => {
+    const out = {};
+    for (const [name, value] of Object.entries(source)) {
+        const lower = name.toLowerCase();
+        if (value !== undefined &&
+            !HOP_BY_HOP_HEADERS.has(lower) &&
+            !dropped.has(lower)) {
+            out[lower] = value;
+        }
+    }
+    return out;
+};
+const sendJsonError = (res, status, message) => {
+    res.writeHead(status, { 'content-type': 'application/json' });
+    res.end(JSON.stringify({ status: 'error', results: null, message }));
+};
+const secretsMatch = (actual, expected) => {
+    if (typeof actual !== 'string')
+        return false;
+    const actualBuffer = Buffer.from(actual);
+    const expectedBuffer = Buffer.from(expected);
+    return (actualBuffer.length === expectedBuffer.length &&
+        (0, crypto_1.timingSafeEqual)(actualBuffer, expectedBuffer));
+};
+/**
+ * Loopback proxy that owns the preview credential. The vite dev server
+ * forwards /api traffic here; only routes a deployed app could reach through
+ * the SDK bridge — pinned to the previewed project — are forwarded upstream,
+ * with the credential attached server-side. Preview does not write it into the
+ * app folder or pass it to the vite process/browser.
+ */
+const startPreviewProxy = (args) => {
+    const upstream = new URL(args.upstreamUrl);
+    const requestFn = upstream.protocol === 'https:' ? https.request : http.request;
+    const server = http.createServer((req, res) => {
+        const method = req.method ?? 'GET';
+        const nonceHeader = req.headers[exports.PREVIEW_PROXY_NONCE_HEADER];
+        const browserAuthorization = req.headers.authorization;
+        if (!secretsMatch(nonceHeader, args.nonce) ||
+            !secretsMatch(browserAuthorization, `ApiKey ${args.nonce}`)) {
+            sendJsonError(res, 401, 'Preview proxy: missing or invalid nonce');
+            return;
+        }
+        let pathname;
+        try {
+            pathname = new URL(req.url ?? '/', 'http://localhost').pathname;
+        }
+        catch {
+            sendJsonError(res, 400, 'Preview proxy: malformed request URL');
+            return;
+        }
+        // Same authority as the deployed app's postMessage bridge: anything
+        // the bridge would reject, preview rejects too.
+        if (!(0, common_1.isAllowedAppSdkRoute)(method, pathname)) {
+            sendJsonError(res, 403, `Preview proxy: ${method} ${pathname} is not a data-app SDK route. Preview only allows the routes a deployed app can reach.`);
+            return;
+        }
+        const routeProjectUuid = (0, common_1.extractAppSdkRouteProjectUuid)(pathname);
+        if (routeProjectUuid !== null &&
+            routeProjectUuid !== args.projectUuid) {
+            sendJsonError(res, 403, `Preview proxy: request targets project ${routeProjectUuid}, but this preview is pinned to ${args.projectUuid}.`);
+            return;
+        }
+        const headers = filterHeaders(req.headers, DROPPED_REQUEST_HEADERS);
+        headers.authorization = args.authorization;
+        if (args.proxyAuthorization) {
+            headers['proxy-authorization'] = args.proxyAuthorization;
+        }
+        const upstreamReq = requestFn({
+            protocol: upstream.protocol,
+            hostname: upstream.hostname,
+            port: upstream.port || undefined,
+            path: req.url,
+            method,
+            headers,
+        }, (upstreamRes) => {
+            res.writeHead(upstreamRes.statusCode ?? 502, filterHeaders(upstreamRes.headers, DROPPED_RESPONSE_HEADERS));
+            upstreamRes.pipe(res);
+        });
+        upstreamReq.on('error', (err) => {
+            if (!res.headersSent) {
+                sendJsonError(res, 502, `Preview proxy: upstream request failed (${err.message})`);
+            }
+            else {
+                res.destroy();
+            }
+        });
+        req.pipe(upstreamReq);
+    });
+    return new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            if (address === null || typeof address === 'string') {
+                reject(new Error('Preview proxy failed to bind a loopback port'));
+                return;
+            }
+            resolve({
+                port: address.port,
+                close: () => new Promise((resolveClose) => {
+                    server.close(() => resolveClose());
+                    // Pending keep-alive sockets would otherwise delay
+                    // shutdown after vite exits.
+                    server.closeAllConnections();
+                }),
+            });
+        });
+    });
+};
+exports.startPreviewProxy = startPreviewProxy;

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

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

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

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

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

@@ -0,0 +1,163 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const http = tslib_1.__importStar(require("http"));
+const previewProxy_1 = require("./previewProxy");
+const PROJECT_UUID = 'proj-uuid-1';
+const NONCE = 'test-nonce';
+const API_KEY = 'ldpat_secret';
+const AUTHORIZATION = `ApiKey ${API_KEY}`;
+/** Records every request and replies 200 with a JSON echo. */
+const startFakeUpstream = () => {
+    const seen = [];
+    const server = http.createServer((req, res) => {
+        const chunks = [];
+        req.on('data', (chunk) => chunks.push(chunk));
+        req.on('end', () => {
+            seen.push({
+                method: req.method ?? '',
+                url: req.url ?? '',
+                headers: req.headers,
+                body: Buffer.concat(chunks).toString('utf-8'),
+            });
+            res.writeHead(200, {
+                'content-type': 'application/json',
+                'set-cookie': 'upstream=1',
+            });
+            res.end(JSON.stringify({ status: 'ok' }));
+        });
+    });
+    return new Promise((resolve) => {
+        server.listen(0, '127.0.0.1', () => {
+            const { port } = server.address();
+            resolve({
+                url: `http://127.0.0.1:${port}`,
+                seen,
+                close: () => new Promise((r) => {
+                    server.close(() => r());
+                    server.closeAllConnections();
+                }),
+            });
+        });
+    });
+};
+describe('startPreviewProxy', () => {
+    let upstream;
+    let proxy;
+    const proxyFetch = (path, init = {}) => {
+        const { nonce = NONCE, authorization = `ApiKey ${NONCE}`, ...rest } = init;
+        const headers = new Headers(rest.headers);
+        if (nonce !== null)
+            headers.set(previewProxy_1.PREVIEW_PROXY_NONCE_HEADER, nonce);
+        if (authorization !== null) {
+            headers.set('authorization', authorization);
+        }
+        return fetch(`http://127.0.0.1:${proxy.port}${path}`, {
+            ...rest,
+            headers,
+        });
+    };
+    beforeEach(async () => {
+        upstream = await startFakeUpstream();
+        proxy = await (0, previewProxy_1.startPreviewProxy)({
+            upstreamUrl: upstream.url,
+            authorization: AUTHORIZATION,
+            projectUuid: PROJECT_UUID,
+            nonce: NONCE,
+        });
+    });
+    afterEach(async () => {
+        await proxy.close();
+        await upstream.close();
+    });
+    it('forwards an allowlisted route with the credential attached', async () => {
+        const res = await proxyFetch(`/api/v2/projects/${PROJECT_UUID}/query/metric-query`, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                authorization: `ApiKey ${NONCE}`,
+            },
+            body: JSON.stringify({ exploreName: 'orders' }),
+        });
+        expect(res.status).toBe(200);
+        expect(upstream.seen).toHaveLength(1);
+        const forwarded = upstream.seen[0];
+        expect(forwarded.method).toBe('POST');
+        expect(forwarded.body).toBe('{"exploreName":"orders"}');
+        // The browser-side scoped capability is replaced by the real credential…
+        expect(forwarded.headers.authorization).toBe(AUTHORIZATION);
+        // …and the run-scoped nonce never travels upstream.
+        expect(forwarded.headers[previewProxy_1.PREVIEW_PROXY_NONCE_HEADER]).toBeUndefined();
+    });
+    it('preserves the query string on result polling', async () => {
+        const res = await proxyFetch(`/api/v2/projects/${PROJECT_UUID}/query/some-query-uuid?page=2&pageSize=500`);
+        expect(res.status).toBe(200);
+        expect(upstream.seen[0].url).toBe(`/api/v2/projects/${PROJECT_UUID}/query/some-query-uuid?page=2&pageSize=500`);
+    });
+    it('rejects non-SDK routes without contacting upstream', async () => {
+        const res = await proxyFetch('/api/v1/org/projects');
+        expect(res.status).toBe(403);
+        const body = (await res.json());
+        expect(body.message).toMatch(/not a data-app SDK route/);
+        expect(upstream.seen).toHaveLength(0);
+    });
+    it('rejects allowlisted routes aimed at a different project', async () => {
+        const res = await proxyFetch('/api/v2/projects/other-project/query/metric-query', { method: 'POST' });
+        expect(res.status).toBe(403);
+        const body = (await res.json());
+        expect(body.message).toMatch(/pinned to proj-uuid-1/);
+        expect(upstream.seen).toHaveLength(0);
+    });
+    it('rejects allowlisted paths with the wrong method', async () => {
+        const res = await proxyFetch('/api/v1/user', { method: 'POST' });
+        expect(res.status).toBe(403);
+        expect(upstream.seen).toHaveLength(0);
+    });
+    it('rejects requests without the per-run nonce', async () => {
+        const missing = await proxyFetch('/api/v1/user', { nonce: null });
+        expect(missing.status).toBe(401);
+        const wrong = await proxyFetch('/api/v1/user', { nonce: 'guessed' });
+        expect(wrong.status).toBe(401);
+        expect(upstream.seen).toHaveLength(0);
+    });
+    it('rejects requests without the browser-side scoped capability', async () => {
+        const missing = await proxyFetch('/api/v1/user', {
+            authorization: null,
+        });
+        expect(missing.status).toBe(401);
+        const wrong = await proxyFetch('/api/v1/user', {
+            authorization: 'ApiKey guessed',
+        });
+        expect(wrong.status).toBe(401);
+        expect(upstream.seen).toHaveLength(0);
+    });
+    it('does not pass upstream cookies back to the page', async () => {
+        const res = await proxyFetch('/api/v1/user');
+        expect(res.status).toBe(200);
+        expect(res.headers.get('set-cookie')).toBeNull();
+    });
+    it('forwards service-account and reverse-proxy authorization', async () => {
+        const serviceProxy = await (0, previewProxy_1.startPreviewProxy)({
+            upstreamUrl: upstream.url,
+            authorization: 'Bearer ldsvc_secret',
+            proxyAuthorization: 'Basic reverse-proxy-secret',
+            projectUuid: PROJECT_UUID,
+            nonce: 'service-nonce',
+        });
+        try {
+            const res = await fetch(`http://127.0.0.1:${serviceProxy.port}/api/v1/user`, {
+                headers: {
+                    [previewProxy_1.PREVIEW_PROXY_NONCE_HEADER]: 'service-nonce',
+                    authorization: 'ApiKey service-nonce',
+                },
+            });
+            expect(res.status).toBe(200);
+            const forwarded = upstream.seen.at(-1);
+            expect(forwarded?.headers.authorization).toBe('Bearer ldsvc_secret');
+            expect(forwarded?.headers['proxy-authorization']).toBe('Basic reverse-proxy-secret');
+        }
+        finally {
+            await serviceProxy.close();
+        }
+    });
+});

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

@@ -67,6 +67,13 @@ describe('buildStaticAuthoringFiles', () => {
         expect(text('README.md')).toContain('Revenue');
         expect(text('.gitignore')).toContain('node_modules');
     });
+    it('uses npm for the standard local workflow', () => {
+        expect(text('README.md')).toContain('npm install && npm run build');
+        expect(text('AGENTS.md')).toContain('npm install && npm run build');
+        expect(text('.claude/skills/developing-data-apps-locally/SKILL.md')).toContain('`npm install` then `npm run build`');
+        expect(text('.npmrc')).toContain('ignore-scripts=true');
+        expect(text('.npmrc')).not.toContain('shamefully-hoist');
+    });
     it('never writes app source (no src/ files)', () => {
         expect(files.every((f) => !f.path.startsWith('src/'))).toBe(true);
     });

package/dist/handlers/utils.d.ts

@@ -7,6 +7,14 @@ type RequestHeader = {
     [LightdashRequestMethodHeader]: RequestMethod;
     [LightdashCliVersionHeader]: string;
 };
+/**
+ * We initially used personal access tokens (PATs) for CLI authentication without any prefix.
+ * Service account tokens are launching with a prefix, so we'll check them first.
+ * We assume a missing prefix is a personal access token, although new PATs will be created with a prefix.
+ *
+ * See {@link AuthTokenPrefix} for the available token prefixes
+ */
+export declare function getAuthHeader(token: string): string;
 export declare function buildRequestHeaders(token: string): RequestHeader;
 export {};
 //# sourceMappingURL=utils.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/handlers/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAEH,yBAAyB,EACzB,4BAA4B,EAC5B,aAAa,EAChB,MAAM,mBAAmB,CAAC;AAQ3B,KAAK,aAAa,GAAG;IACjB,cAAc,EAAE,kBAAkB,CAAC;IACnC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,CAAC,4BAA4B,CAAC,EAAE,aAAa,CAAC;IAC9C,CAAC,yBAAyB,CAAC,EAAE,MAAM,CAAC;CACvC,CAAC;AAgBF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,iBAiBhD"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/handlers/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAEH,yBAAyB,EACzB,4BAA4B,EAC5B,aAAa,EAChB,MAAM,mBAAmB,CAAC;AAQ3B,KAAK,aAAa,GAAG;IACjB,cAAc,EAAE,kBAAkB,CAAC;IACnC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,aAAa,EAAE,MAAM,CAAC;IACtB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,CAAC,4BAA4B,CAAC,EAAE,aAAa,CAAC;IAC9C,CAAC,yBAAyB,CAAC,EAAE,MAAM,CAAC;CACvC,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,UAK1C;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,iBAiBhD"}

package/dist/handlers/utils.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAuthHeader = getAuthHeader;
 exports.buildRequestHeaders = buildRequestHeaders;
 const common_1 = require("@lightdash/common");
 const env_1 = require("../env");

package/dist/index.js

@@ -8,6 +8,7 @@ const uuid_1 = require("uuid");
 const env_1 = require("./env");
 const error_1 = require("./error");
 const globalState_1 = tslib_1.__importDefault(require("./globalState"));
+const preview_1 = require("./handlers/apps/preview");
 const compile_1 = require("./handlers/compile");
 const connectSnowflake_1 = require("./handlers/connectSnowflake");
 const refresh_1 = require("./handlers/dbt/refresh");
@@ -24,7 +25,7 @@ const lint_1 = require("./handlers/lint");
 const listProjects_1 = require("./handlers/listProjects");
 const login_1 = require("./handlers/login");
 const preAggregateAudit_1 = require("./handlers/preAggregateAudit");
-const preview_1 = require("./handlers/preview");
+const preview_2 = require("./handlers/preview");
 const renameHandler_1 = require("./handlers/renameHandler");
 const renameProject_1 = require("./handlers/renameProject");
 const runChart_1 = require("./handlers/runChart");
@@ -274,7 +275,7 @@ commander_1.program
     .option('--expires-in <hours>', 'Number of hours until the preview project auto-expires (default: 720, i.e. 30 days)')
     .option('--validate-warehouse-columns', validateWarehouseColumnsDescription, false)
     .option('--no-partial-compilation', 'Fail when a field or join cannot be compiled instead of returning a partial explore')
-    .action(preview_1.previewHandler);
+    .action(preview_2.previewHandler);
 commander_1.program
     .command('start-preview')
     .description('Creates a new preview project')
@@ -314,13 +315,13 @@ commander_1.program
     .option('--expires-in <hours>', 'Number of hours until the preview project auto-expires (default: 720, i.e. 30 days)')
     .option('--validate-warehouse-columns', validateWarehouseColumnsDescription, false)
     .option('--no-partial-compilation', 'Fail when a field or join cannot be compiled instead of returning a partial explore')
-    .action(preview_1.startPreviewHandler);
+    .action(preview_2.startPreviewHandler);
 commander_1.program
     .command('stop-preview')
     .description('Deletes preview project')
     .option('--name [preview name]', '[required] Name for the preview project to be deleted')
     .option('--verbose', undefined, false)
-    .action(preview_1.stopPreviewHandler);
+    .action(preview_2.stopPreviewHandler);
 const ORGANIZATION_MODE_OPTIONS = new Set([
     'organization',
     'path',
@@ -416,6 +417,17 @@ const uploadCommand = commander_1.program
     .option('--organization', 'upload all organization-scoped resources without selecting a project', false)
     .option('--send-invites', 'send invitations to eligible pending users during organization upload', false);
 uploadCommand.action(withOrganizationMode(download_1.uploadHandler));
+const appsProgram = commander_1.program
+    .command('apps')
+    .description('Work with data apps (enterprise)');
+appsProgram
+    .command('preview [path]')
+    .description('Preview a downloaded data app locally against a real Lightdash instance, authenticated as you. Your credential stays in the CLI, behind a local proxy limited to data-app SDK routes.')
+    .option('--project <project uuid>', 'preview against a specific project (default: the projectUuid in lightdash-app.yml)')
+    .option('--url <url>', 'Lightdash server URL (default: your login config)')
+    .option('--token <token>', 'API key / personal access token (default: your login config)')
+    .option('--verbose', undefined, false)
+    .action(preview_1.appsPreviewHandler);
 commander_1.program
     .command('deploy')
     .description('Compiles and deploys a Lightdash project')

package/dist/vendor/authoring/AGENTS.md.tmpl

@@ -2,12 +2,12 @@
 
 Two skills in `.claude/skills/` describe how to edit this app:
 - `lightdash-data-app` — the Lightdash SDK surface (querying data, filters, downloads).
-- `developing-data-apps-locally` — the local workflow: edit `src/`, `pnpm build`, `lightdash upload --apps <appUuid>` (uuid in `lightdash-app.yml`); the SDK is the only data access; `.lightdash/context/` holds the project's semantic layer and theme.
+- `developing-data-apps-locally` — the local workflow: edit `src/`, `npm run build`, `lightdash upload --apps <appUuid>` (uuid in `lightdash-app.yml`); the SDK is the only data access; `.lightdash/context/` holds the project's semantic layer and theme.
 
 Edit only `src/`. Root config files are read-only reference — the server rebuilds against a trusted template.
 
-The local `pnpm install && pnpm build` is an optional pre-check. If install fails, skip it and upload — never modify machine config, npmrc, or dependency files to force it; the server rebuild is authoritative.
+The local `npm install && npm run build` is an optional pre-check. If install fails, skip it and upload — never modify machine config, npmrc, or dependency files to force it; the server rebuild is authoritative.
 
-Build with the template's preinstalled dependency set (see `package.json`). Adding new npm packages only works when the instance has custom dependencies enabled — assume it does not; ask the user before considering a new library, and never vendor library source into `src/` as a workaround. Where enabled, adding a dependency requires a matching `pnpm-lock.yaml`, so `pnpm add <pkg>` (or `pnpm install --lockfile-only`) must succeed locally. If it fails, stop and report the error — hand-editing `package.json` without the lockfile makes the upload fail.
+Build with the template's preinstalled dependency set (see `package.json`). Adding new npm packages only works when the instance has custom dependencies enabled — assume it does not; ask the user before considering a new library, and never vendor library source into `src/` as a workaround. Where enabled, adding a dependency is the one workflow that still requires pnpm: upload requires a matching `pnpm-lock.yaml`, so `pnpm add <pkg>` (or `pnpm install --lockfile-only`) must succeed locally. If it fails, stop and report the error — hand-editing `package.json` without the lockfile makes the upload fail.
 
 `.npmrc` sets `ignore-scripts=true` — never remove it or run installs with scripts enabled; this app may be authored by someone else and their dependencies' lifecycle scripts must not run here.