@lightdash/cli 3.96.1 → 3.98.0

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

@@ -1 +1 @@
-{"version":3,"file":"previewProxy.d.ts","sourceRoot":"","sources":["../../../src/handlers/apps/previewProxy.ts"],"names":[],"mappings":"AAmBA,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;AAEF,4EAA4E;AAC5E,MAAM,MAAM,qBAAqB,GAAG;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAG5B,0BAA0B,EAAE,MAAM,EAAE,CAAC;CACxC,CAAC;AAyCF;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,SAAU;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,oBAAoB,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7C,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IAGd,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,qBAAqB,KAAK,IAAI,CAAC;CAC5D,KAAG,OAAO,CAAC,kBAAkB,CAyW7B,CAAC"}
+{"version":3,"file":"previewProxy.d.ts","sourceRoot":"","sources":["../../../src/handlers/apps/previewProxy.ts"],"names":[],"mappings":"AAyBA,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;AAEF,4EAA4E;AAC5E,MAAM,MAAM,qBAAqB,GAAG;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAG5B,0BAA0B,EAAE,MAAM,EAAE,CAAC;CACxC,CAAC;AAyCF;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,SAAU;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,oBAAoB,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7C,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IAGd,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,qBAAqB,KAAK,IAAI,CAAC;CAC5D,KAAG,OAAO,CAAC,kBAAkB,CA4Z7B,CAAC"}

package/dist/handlers/apps/previewProxy.js

@@ -221,6 +221,31 @@ const startPreviewProxy = (args) => {
         res.writeHead(200, { 'content-type': 'application/json' });
         res.end(JSON.stringify({ status: 'ok', results }));
     };
+    // Host-answered virtual route: resolves a slug-or-uuid space reference
+    // to its trimmed chart list with the developer's credentials. Unknown
+    // space, no access, and upstream failure all answer uniformly empty —
+    // same face as the deployed app's bridge.
+    const answerSpaceCharts = async (req, res) => {
+        const request = (0, common_1.parseAppSdkSpaceChartsRequest)(parseJson(await readBody(req)));
+        if (request === null) {
+            sendJsonError(res, 400, 'Preview proxy: invalid space-charts request');
+            return;
+        }
+        let results = (0, common_1.emptyAppSdkSpaceCharts)();
+        try {
+            const spaces = await getUpstreamJson(`/api/v1/projects/${encodeURIComponent(args.projectUuid)}/spaces`);
+            const spaceUuid = (0, common_1.resolveAppSdkSpaceUuid)(spaces, request.space);
+            if (spaceUuid !== null) {
+                const space = await getUpstreamJson(`/api/v1/projects/${encodeURIComponent(args.projectUuid)}/spaces/${encodeURIComponent(spaceUuid)}`);
+                results = (0, common_1.extractAppSdkSpaceCharts)(space) ?? results;
+            }
+        }
+        catch {
+            // Keep the uniform empty answer.
+        }
+        res.writeHead(200, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ status: 'ok', results }));
+    };
     const handleRequest = async (req, res) => {
         const method = req.method ?? 'GET';
         const nonceHeader = req.headers[exports.PREVIEW_PROXY_NONCE_HEADER];
@@ -238,6 +263,14 @@ const startPreviewProxy = (args) => {
             sendJsonError(res, 400, 'Preview proxy: malformed request URL');
             return;
         }
+        if (pathname === common_1.APP_SDK_SPACE_CHARTS_PATH) {
+            answerSpaceCharts(req, res).catch(() => {
+                if (!res.headersSent) {
+                    sendJsonError(res, 400, 'Preview proxy: invalid space-charts request');
+                }
+            });
+            return;
+        }
         if (pathname === common_1.APP_SDK_EXPLORE_BASE_TABLE_PATH) {
             answerExploreBaseTable(req, res).catch(() => {
                 if (!res.headersSent) {

package/dist/vendor/template/.claude/skills/sdk-features/SKILL.md

@@ -34,6 +34,7 @@ Users describe features by what they see in the Lightdash editor. Translate:
 | Lightdash-owned "View underlying data" dialog (viz only) | `viz-host-underlying-data` | app code opt-in |
 | light/dark mode, "matches my Lightdash theme" | `follow-host-theme` | CSS tokens — see below |
 | "executive summary", "what changed", anomaly callouts, "AI insight", "Analyse this view" | `ai-insights` | app code opt-in |
+| chart gallery, "my charts", "show the charts in this space", list that updates as charts are saved | `space-charts` | app code opt-in |
 | "Adapts to small tiles", responsive, works on a phone, readable in a narrow or short tile (viz only) | `viz-responsive-layout` | layout — see below |
 
 ## Automatic (zero wiring — active on any current-SDK bundle)
@@ -197,12 +198,26 @@ order, `sortBy` describes result ordering, `totalColumnCount` exposes truncation
   `instructions` prop on `InsightsSummary` (or `useInsights({ instructions })`
   in a custom block). One string per app, max 2000 characters. See "Author
   instructions" in `/app/references/ai-analysis.md`.
+- `analysis-on-load`: only when the user asks for the analysis to run on its
+  own ("analyse as soon as it loads"): set the `analyseOnLoad` prop on
+  `InsightsSummary` (or `useInsights({ analyseOnLoad: true })` in a custom
+  block). See "Analyse on load" in `/app/references/ai-analysis.md`.
 - `ai-prompt`: `useAiPrompt()` returns `{ available, ask, loading, text, error }`;
   `ask({ prompt, sources: [{ result, label }], focus?: { row } })` sends an
   author-written question over loaded `useLightdash` results and resolves to
   plain text. `result` is the object `useLightdash` returns (keep a reference
   to it even when destructuring), never a rebuilt `{ data, columns }`. Hide the control when `available` is false; trigger from a user
   action. Full contract in `/app/references/ai-analysis.md`.
+- `space-charts`: `useSpaceCharts('<space slug or uuid>')` returns
+  `{ available, space, charts, loading, error, refresh }` — the saved charts
+  the viewer can see in that space, resolved at runtime with the viewer's own
+  permissions (an inaccessible space answers like a missing one: `space: null`,
+  no charts). Each entry carries `{ uuid, name, description, chartKind, slug,
+  updatedAt }`; pass `chart.uuid` to `savedChart(...)` to render one. Use it
+  for galleries that must pick up newly saved charts without a rebuild; keep
+  explicit `savedChart('<uuid>')` references for charts the app lays out by
+  hand. Render a friendly empty state for `charts.length === 0` and hide the
+  section when `available` is false (older host).
 - `delivery-render`: `useDeliveryRender()` is `true` during scheduled-delivery
   and delivery-preview capture renders. Gate tab/slide DATA mounting on it so
   every tab's queries execute during capture while only the active tab stays

package/dist/vendor/template/references/ai-analysis.md

@@ -49,7 +49,7 @@ const view = useInsights();
 // view.analyse()    ask Lightdash to (re)run the analysis
 ```
 
-Render `<InsightsSummary />` near the top of the page. It handles every status (idle, analysing, ready, error, stale) and renders nothing when unavailable. Props: `title`, `idleText`, `instructions`, `className`. Write your own block only when the user asks for a layout the component cannot give, and then keep every status branch.
+Render `<InsightsSummary />` near the top of the page. It handles every status (idle, analysing, ready, error, stale) and renders nothing when unavailable. Props: `title`, `idleText`, `instructions`, `analyseOnLoad`, `className`. Write your own block only when the user asks for a layout the component cannot give, and then keep every status branch.
 
 ### Author instructions for the analysis
 
@@ -63,6 +63,16 @@ Or equivalently `useInsights({ instructions })` in a custom block. One string pe
 
 The organization may also set default instructions in its settings; those apply first and the app's instructions are added after them, so keep app instructions to app-specific guidance (domain vocabulary) and leave org-wide style (language, currency) to the org default when the user says it should apply everywhere.
 
+### Analyse on load
+
+By default the analysis runs when the viewer clicks **Analyse**. When the user wants it to run on its own ("analyse as soon as it loads", "show the summary when the page opens"), set `analyseOnLoad`:
+
+```tsx
+<InsightsSummary analyseOnLoad />
+```
+
+Or equivalently `useInsights({ analyseOnLoad: true })` in a custom block. One value per app (the last value set wins). The host runs the analysis once the page's queries settle and again when the view changes; a stored analysis of the same rows is reused instead of re-run. Do not set it unless the user asked for it.
+
 Rules for the block:
 
 - Say "AI-generated" in the footer. Never name a model or provider.

package/dist/vendor/template/references/chart-references.md

@@ -87,6 +87,19 @@ A linked chart stays in sync with Lightdash and appears in the Queries panel
 like any other query. If it can't be run (deleted / no access), the app should
 show its normal error state — don't fabricate data.
 
+### Discovering charts at runtime (`useSpaceCharts`)
+
+When the user wants a gallery or "my charts" page that picks up charts saved
+to a space **after** the app is built, don't hardcode a UUID list — list the
+space at runtime: `useSpaceCharts('<space slug or uuid>')` returns
+`{ available, space, charts, loading, error, refresh }`, scoped to what the
+viewer can access (an inaccessible space answers `space: null` with no
+charts). Pass an entry's `uuid` to `savedChart(...)` to render it, and treat
+every such chart as LINKED: data-driven and crash-proof per the rules below,
+since its shape is unknown at build time. Render an empty state for zero
+charts and hide the section when `available` is false. The recipe lives in
+the `sdk-features` skill under `space-charts`.
+
 ### Linked charts must be DATA-DRIVEN and crash-proof
 
 A linked chart's query can change in Lightdash *after* the app is generated (the

package/dist/vendor/template/skill.md

@@ -220,6 +220,8 @@ These metrics are **not additive over time**. A balance on Monday plus the balan
 
 If the prompt lists referenced charts (files under `/tmp/metric-queries/*.json`), read `/app/references/chart-references.md` before writing any query code — it defines the JSON shape, linked-vs-copied chart semantics (`savedChart`), and the field-id mapping rules.
 
+If the user asks for a page that lists or renders **whatever charts a Lightdash space contains** (a gallery, "my charts", "charts from the Sales space") — i.e. the set should grow as charts are saved, without rebuilding the app — use `useSpaceCharts('<space slug or uuid>')` and read "Discovering charts at runtime" in `/app/references/chart-references.md`. Never hardcode a UUID list for that ask.
+
 ## Attached dashboard blueprint
 
 If the prompt announces an attached dashboard (blueprint at `/tmp/dashboard/blueprint.json`), read `/app/references/dashboard-blueprint.md` before designing any layout — the blueprint defines the dashboard's tabs, tile grid, and filters, and it is the layout spec to recreate unless the user asks for a different design.
@@ -779,7 +781,7 @@ For any external HTTP API call, read `/app/references/external-apis.md` and use
 
 ### AI analysis — executive summary and anomalies
 
-When the user asks for AI analysis, an executive summary, "what changed and why", anomaly callouts, or any AI-generated insight about the data on the page, read `/app/references/ai-analysis.md` and build its **Default build** with the shipped components in `src/components/insights/` (`InsightsSummary`, `InsightMarker` / `insightCellProps`, `InvestigateMenuItem`, `InvestigationCard`): summary block at the top, markers on every query-bound chart, Investigate in every point menu, the investigation card under the chart. A short ask gets the whole set; only a narrower ask ("just a summary") gets a subset. Never rewrite those components. Lightdash runs the analysis over the queries the app already loaded and pushes the result in; the app renders it and never sends rows or keys. The components render nothing when the host has no analysis to offer. For an author-written question over loaded results (a takeaway under a chart, "explain this row"), use `useAiPrompt` from the same reference. When the user wants the summaries written a certain way (language, currency, domain vocabulary), pass it via the `instructions` prop on `InsightsSummary` — see "Author instructions" in the same reference.
+When the user asks for AI analysis, an executive summary, "what changed and why", anomaly callouts, or any AI-generated insight about the data on the page, read `/app/references/ai-analysis.md` and build its **Default build** with the shipped components in `src/components/insights/` (`InsightsSummary`, `InsightMarker` / `insightCellProps`, `InvestigateMenuItem`, `InvestigationCard`): summary block at the top, markers on every query-bound chart, Investigate in every point menu, the investigation card under the chart. A short ask gets the whole set; only a narrower ask ("just a summary") gets a subset. Never rewrite those components. Lightdash runs the analysis over the queries the app already loaded and pushes the result in; the app renders it and never sends rows or keys. The components render nothing when the host has no analysis to offer. For an author-written question over loaded results (a takeaway under a chart, "explain this row"), use `useAiPrompt` from the same reference. When the user wants the summaries written a certain way (language, currency, domain vocabulary), pass it via the `instructions` prop on `InsightsSummary` — see "Author instructions" in the same reference. When the user wants the analysis to run as soon as the app loads, set the `analyseOnLoad` prop on `InsightsSummary` — see "Analyse on load" in the same reference; never set it unasked.
 
 ## Visual Design
 

package/dist/vendor/template/src/components/insights/InsightsSummary.tsx

@@ -6,7 +6,7 @@ import { useInsights } from '@lightdash/query-sdk';
 import { Button } from '@/components/ui/button';
 import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
 import { Loader2, RefreshCw, Sparkles } from 'lucide-react';
-import type { ReactNode } from 'react';
+import { useEffect, useState, type ReactNode } from 'react';
 
 type Props = {
     title?: ReactNode;
@@ -15,6 +15,8 @@ type Props = {
     /** Guidance for the analysis model: language/format rules and a line or
      *  two of domain vocabulary. One string per app. */
     instructions?: string;
+    /** Run the analysis when the view loads, without a click. */
+    analyseOnLoad?: boolean;
     className?: string;
 };
 
@@ -22,13 +24,30 @@ export function InsightsSummary({
     title = 'Executive summary',
     idleText = 'Click Analyse for an AI-generated read of everything on this page.',
     instructions,
+    analyseOnLoad,
     className,
 }: Props) {
     // Always pass the options object so clearing the prop clears the
     // guidance instead of leaving the previous value in force.
-    const view = useInsights({ instructions });
+    const view = useInsights({ instructions, analyseOnLoad });
+    // The host only starts once the app reports analyseOnLoad, so show the
+    // run as pending meanwhile; a short cap keeps an older host from
+    // leaving it stuck.
+    const [pendingAutoRun, setPendingAutoRun] = useState(!!analyseOnLoad);
+    useEffect(() => {
+        if (!pendingAutoRun) return undefined;
+        // `unavailable` is also the SDK's state before the host's first push.
+        if (view.status !== 'idle' && view.status !== 'unavailable') {
+            setPendingAutoRun(false);
+            return undefined;
+        }
+        const timer = setTimeout(() => setPendingAutoRun(false), 5000);
+        return () => clearTimeout(timer);
+    }, [pendingAutoRun, view.status]);
     if (view.status === 'unavailable') return null;
-    const busy = view.status === 'analysing';
+    const busy =
+        view.status === 'analysing' ||
+        (pendingAutoRun && view.status === 'idle');
 
     return (
         <Card className={className}>
@@ -52,7 +71,7 @@ export function InsightsSummary({
                 </Button>
             </CardHeader>
             <CardContent className="space-y-3">
-                {view.status === 'idle' && (
+                {view.status === 'idle' && !busy && (
                     <p className="text-sm text-muted-foreground">{idleText}</p>
                 )}
                 {busy && (

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightdash/cli",
-  "version": "3.96.1",
+  "version": "3.98.0",
   "description": "Lightdash CLI tool",
   "license": "MIT",
   "repository": {
@@ -22,8 +22,8 @@
     "@actions/core": "1.11.1",
     "@aws-sdk/credential-providers": "3.995.0",
     "@casl/ability": "6.8.0",
-    "@lightdash/common": "3.96.1",
-    "@lightdash/warehouses": "3.96.1",
+    "@lightdash/common": "3.98.0",
+    "@lightdash/warehouses": "3.98.0",
     "@sidvind/better-ajv-errors": "7.0.0",
     "@types/columnify": "1.5.1",
     "ajv": "8.18.0",