@lightdash/cli 1.45.0 → 1.46.0

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

@@ -4,14 +4,17 @@ Downloaded with the Lightdash CLI (`lightdash download`).
 
 ## Edit → build → upload
 1. Edit files under `src/`.
-2. Optionally, `pnpm install && pnpm build` to check it compiles locally. If install fails in your environment, skip it — the server build on upload is authoritative and surfaces errors on the app page. Don't change machine or registry config to force it.
-3. `lightdash upload --apps <appUuid>` (the `appUuid` from `lightdash-app.yml`) — Lightdash rebuilds and serves the app.
+2. Optionally, `npm install && npm run build` to check it compiles locally. If install fails in your environment, skip it — the server build on upload is authoritative and surfaces errors on the app page. Don't change machine or registry config to force it.
+3. Optionally, preview against real data: `lightdash apps preview` (needs a successful `npm install`).
+4. `lightdash upload --apps` — Lightdash rebuilds and serves the app.
+
+Local preview uses your existing CLI login through a project- and route-restricted loopback proxy; the credential is not written into this folder or exposed to browser code. It runs local tooling as your OS user (with access to that user's files, including the existing CLI config) and shows data under your own permissions, so preview only source/dependencies you trust. Host-mediated features such as external connections and data-app-viz context still need testing after upload.
 
 ## What's read-only
 Most root config is read-only: `vite.config.js`, `tailwind.config.js`, `tsconfig.json`, etc. The server rebuilds against a trusted template, so local edits to those files don't change the deployed app.
 
-The app builds against the template's fixed dependency set (see `package.json`) — design within it. Only when custom dependencies are enabled on your Lightdash instance (most instances: not enabled), `package.json` becomes partially editable: run `pnpm add <pkg>` to declare extra npm dependencies (registry packages, plain semver versions only, up to 60 direct deps). `pnpm-lock.yaml` must be updated to match — `pnpm add` does this; if you edit `package.json` by hand, run `pnpm install --lockfile-only`. Upload rejects new dependencies without a matching lockfile. On upload the CLI warns which packages will be installed in the build sandbox; install scripts never run, and the server replaces `scripts` with the trusted template's (the sandbox build command is not uploader-controlled). The AI builder and in-app UI cannot change the dependency set — dependencies are declared by editing `package.json` and re-uploading.
+The app builds against the template's fixed dependency set (see `package.json`) — design within it. Only when custom dependencies are enabled on your Lightdash instance (most instances: not enabled), `package.json` becomes partially editable. This is the one workflow that still requires pnpm: run `pnpm add <pkg>` to declare extra npm dependencies (registry packages, plain semver versions only, up to 60 direct deps). `pnpm-lock.yaml` must be updated to match — `pnpm add` does this; if you edit `package.json` by hand, run `pnpm install --lockfile-only`. Upload rejects new dependencies without a matching lockfile. On upload the CLI warns which packages will be installed in the build sandbox; install scripts never run, and the server replaces `scripts` with the trusted template's (the sandbox build command is not uploader-controlled). The AI builder and in-app UI cannot change the dependency set — dependencies are declared by editing `package.json` and re-uploading.
 
-`.npmrc` sets `ignore-scripts=true` so dependencies' lifecycle scripts never run on your machine either — downloaded apps may be authored by someone else. Keep it; explicit `pnpm build`/`pnpm dev` still work.
+`.npmrc` sets `ignore-scripts=true` so dependencies' lifecycle scripts never run on your machine either — downloaded apps may be authored by someone else. Keep it; explicit commands such as `npm run build` still work.
 
 `.lightdash/context/` is a point-in-time snapshot of the source project; re-download to refresh it.

package/dist/vendor/authoring/developing-data-apps-locally/SKILL.md

@@ -9,7 +9,7 @@ You are editing a Lightdash **data app** that was downloaded with the Lightdash
 
 ## The only way to reach data is the SDK
 
-- All data access goes through `@lightdash/query-sdk` (a postMessage bridge to Lightdash). There is **no** `fetch`, no REST calls, no other network access at runtime — anything else is blocked.
+- All app data access goes through `@lightdash/query-sdk`. Deployed apps use Lightdash's postMessage bridge; `lightdash apps preview` uses a loopback proxy restricted to the same SDK routes and project. Do not add direct `fetch` or REST calls.
 - For the SDK surface (query builder, `useLightdash`, filters, downloads), read the `lightdash-data-app` skill in this folder.
 
 ## External HTTP APIs go through linked connections
@@ -28,16 +28,29 @@ You are editing a Lightdash **data app** that was downloaded with the Lightdash
 ## The edit → build → upload loop
 
 1. Edit files under `src/` only.
-2. Optionally, `pnpm install` then `pnpm build` to check it compiles. This is an **optional local pre-check** — see below.
+2. Optionally, `npm install` then `npm run build` to check it compiles. This is an **optional local pre-check** — see below.
 3. `lightdash upload --apps <appUuid>` (the `appUuid` from this folder's `lightdash-app.yml`) — the **server** rebuilds and serves the app. The server rebuild, not your local build, is what ships.
 
 ## The local build is optional — never fight a failing install
 
-- If `pnpm install` fails (registry policy, an unavailable pinned SDK version, no network access), **skip the local build entirely and go straight to upload**. The server rebuild is authoritative and surfaces build errors on the app page.
+- If `npm install` fails (registry policy, an unavailable pinned SDK version, no network access), **skip the local build entirely and go straight to upload**. The server rebuild is authoritative and surfaces build errors on the app page.
 - Do **not** modify machine configuration, `.npmrc` files, registry settings, or the project's dependency files to force an install to work.
 - A missing `node_modules` is a normal state, not a problem to fix. Never run installs just because it is absent.
-- **Exception — adding a dependency** (only on instances with custom dependencies enabled — see "Library boundaries" above). Upload rejects new dependencies unless `pnpm-lock.yaml` was regenerated to match `package.json`, so dependency resolution MUST succeed locally. Use `pnpm add <pkg>`, or after editing `package.json` run `pnpm install --lockfile-only` (updates the lockfile without installing). If resolution fails, **stop and report the exact pnpm error to the user** — never hand-edit `package.json` and proceed without the lockfile; the upload will fail.
-- **Never run dependency lifecycle scripts.** The app's `.npmrc` sets `ignore-scripts=true` — leave it. A downloaded app can be authored by someone else, and their dependencies' install scripts must not execute on this machine. Explicit `pnpm build`/`pnpm dev` still work.
+- **Exception — adding a dependency** (only on instances with custom dependencies enabled — see "Library boundaries" above). This is the one workflow that still requires pnpm: upload rejects new dependencies unless `pnpm-lock.yaml` was regenerated to match `package.json`, so dependency resolution MUST succeed locally. Use `pnpm add <pkg>` — prefixed with Socket Firewall when available (`sfw pnpm add <pkg>`; check with `command -v sfw`) to block known-malicious packages — or after editing `package.json` run `pnpm install --lockfile-only` (updates the lockfile without installing). If resolution fails, **stop and report the exact pnpm error to the user** — never hand-edit `package.json` and proceed without the lockfile; the upload will fail.
+- **Never run dependency lifecycle scripts.** The app's `.npmrc` sets `ignore-scripts=true` — leave it. A downloaded app can be authored by someone else, and their dependencies' install scripts must not execute on this machine. Explicit commands such as `npm run build` still work.
+
+## Preview locally against real data
+
+`lightdash apps preview` (run in this folder) starts a local dev server that renders the app against the Lightdash instance you are logged into, using your CLI credential. Requires `npm install` to have succeeded; if it hasn't, skip preview and rely on the server rebuild.
+
+- Preview does not pass your API key to vite or browser code: the CLI holds it behind a loopback proxy that only forwards the SDK route allowlist (query execution, result polling, downloads, current user), pinned to this app's project. No credential is written to the app folder. Never put a real key in `.env.local` or any `VITE_`-prefixed var — anything `VITE_*` is inlined into the page and readable by any code running there.
+- There is no manual `npm run dev` equivalent with data access — bare `npm run dev` starts the page but API calls fail with 401. Always use `lightdash apps preview`.
+- An endpoint that works in preview but not when deployed means it is outside the data-app SDK surface — use the SDK, don't work around the proxy.
+- Declared custom dependencies work in preview too — the dev server bundles whatever the dependency install put in `node_modules`, the same set the server installs on upload.
+- Preview shows **your** data under **your** permissions and user attributes — viewers of the deployed app may see different data. Do not treat preview as verification of viewer-specific behavior.
+- Local preview keeps the credential out of the app environment/browser but is **not a sandbox**: vite and the downloaded tooling execute as your OS user, can read that user's files (including the existing CLI config), and the app can read the query results it requests. Only preview source and dependencies you trust.
+- The dev server applies a CSP that forces API traffic through its same-origin proxy, but `script-src` stays permissive (vite needs it), so preview is **not** a full stand-in for the deployed Content-Security-Policy. A library that works in preview may still be blocked when deployed; the app page after upload is the final check.
+- Host-mediated features are not emulated locally. External connections (`externalFetch`), data-app-viz row/field context, Google Sheets export, the product inspector, and product URL-state integration must be tested after upload.
 
 ## Project context (read-only reference)
 
@@ -52,4 +65,4 @@ You are editing a Lightdash **data app** that was downloaded with the Lightdash
 
 Most root config is reference only — editing it has **no effect** because the server rebuilds against its trusted template. This applies to `vite.config.js`, `tailwind.config.js`, `tsconfig.json`, and other build/tooling files.
 
-`package.json` is **partially editable** only when custom dependencies are enabled on the Lightdash instance — see "Library boundaries" above; treat it as read-only otherwise. When enabled, you may add npm dependencies with `pnpm add <pkg>` — registry packages with plain semver versions only (no git/file/url specs), up to 60 direct dependencies, and `pnpm-lock.yaml` must be updated alongside (see the exception above — this is the one step that must succeed locally). On upload the CLI warns which packages will be installed in the build sandbox; install scripts never run. Other root config (vite/tailwind/tsconfig) remains read-only.
+`package.json` is **partially editable** only when custom dependencies are enabled on the Lightdash instance — see "Library boundaries" above; treat it as read-only otherwise. When enabled, you may add npm dependencies with `pnpm add <pkg>` — registry packages with plain semver versions only (no git/file/url specs), up to 60 direct dependencies, and `pnpm-lock.yaml` must be updated alongside (see the exception above — this is the one step that still requires pnpm and must succeed locally). On upload the CLI warns which packages will be installed in the build sandbox; install scripts never run. Other root config (vite/tailwind/tsconfig) remains read-only.

package/dist/vendor/authoring/gitignore

@@ -1,2 +1,3 @@
 node_modules
 dist
+.env*

package/dist/vendor/template/vite.config.js

@@ -142,7 +142,38 @@ function jsxSourceLocVitePlugin() {
 }
 
 export default defineConfig(({ mode }) => {
-    const env = loadEnv(mode, process.cwd(), 'VITE_');
+    // Load VITE_* (inlined into the browser bundle) AND the preview-only
+    // LIGHTDASH_PREVIEW_PROXY_* vars (stay server-side — never inlined, since
+    // envPrefix defaults to 'VITE_'). `lightdash apps preview` starts a
+    // loopback proxy that holds the real credential and enforces the data-app
+    // SDK route allowlist; this dev server only ever learns the proxy's
+    // address and a run-scoped nonce. The browser receives that nonce as a
+    // project- and route-limited capability, never the durable credential.
+    const env = loadEnv(mode, process.cwd(), ['VITE_', 'LIGHTDASH_PREVIEW_']);
+    const previewProxyTarget = env.LIGHTDASH_PREVIEW_PROXY_TARGET;
+    const previewProxyNonce = env.LIGHTDASH_PREVIEW_PROXY_NONCE;
+    const lightdashUrl =
+        env.VITE_LIGHTDASH_URL || 'https://app.lightdash.cloud';
+
+    // Dev-server CSP that emulates the deployed app policy for the vectors that
+    // matter for credential/data theft: network egress is locked to same-origin
+    // so all API traffic must pass through the allowlisted /api proxy.
+    // script-src/style-src stay permissive because Vite's dev runtime needs
+    // inline + eval, so this is NOT a full stand-in for the deployed sandbox.
+    const previewCsp = [
+        `default-src 'none'`,
+        `script-src 'self' 'unsafe-inline' 'unsafe-eval' blob:`,
+        `style-src 'self' 'unsafe-inline'`,
+        `connect-src 'self'`,
+        `img-src 'self' data: blob:`,
+        `font-src 'self' data:`,
+        `worker-src 'self' blob:`,
+        `child-src 'self' blob:`,
+        `object-src 'none'`,
+        `base-uri 'self'`,
+        `form-action 'self'`,
+        `frame-ancestors 'self'`,
+    ].join('; ');
 
     return {
         plugins: [jsxSourceLocVitePlugin(), react()],
@@ -153,12 +184,41 @@ export default defineConfig(({ mode }) => {
             },
         },
         server: {
+            host: '127.0.0.1',
+            // Vite otherwise permits every localhost origin. Preview is a
+            // credentialed endpoint, so only the page's own origin may read it.
+            cors: false,
+            headers: { 'Content-Security-Policy': previewCsp },
             proxy: {
                 '/api': {
-                    target:
-                        env.VITE_LIGHTDASH_URL || 'https://app.lightdash.cloud',
+                    // Under `lightdash apps preview`, /api goes to the CLI's
+                    // loopback proxy, which checks the route against the
+                    // data-app SDK allowlist and attaches the credential
+                    // before forwarding to Lightdash. Without the CLI (bare
+                    // `npm run dev`) requests go to the instance uncredentialed
+                    // and fail with 401 — preview requires the CLI command.
+                    target: previewProxyTarget || lightdashUrl,
                     changeOrigin: true,
                     secure: true,
+                    configure: (proxy) => {
+                        if (!previewProxyNonce) return;
+                        proxy.on('proxyReq', (proxyReq, req) => {
+                            // Do not turn Vite into an unauthenticated front
+                            // door to the nonce-protected CLI proxy. The SDK
+                            // presents the run-scoped nonce as its local API
+                            // key; only matching requests receive the inner
+                            // proxy header.
+                            if (
+                                req.headers.authorization ===
+                                `ApiKey ${previewProxyNonce}`
+                            ) {
+                                proxyReq.setHeader(
+                                    'x-lightdash-preview-nonce',
+                                    previewProxyNonce,
+                                );
+                            }
+                        });
+                    },
                 },
             },
         },

package/package.json

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