@lightdash/cli 3.163.1 → 3.165.0

package/dist/handlers/slugUpdate.d.ts

@@ -1,10 +1,11 @@
 import { ContentType, type ContentSlugRenameRequest } from '@lightdash/common';
+type SlugUpdateResourceType = ContentType.CHART | ContentType.DASHBOARD | ContentType.DATA_APP;
 type SlugUpdateOptions = {
     verbose: boolean;
     project?: string;
     path?: string;
     dryRun: boolean;
-    type: ContentType.CHART | ContentType.DASHBOARD;
+    type: ContentType.CHART | ContentType.DASHBOARD | 'app';
     from: string;
     to: string;
 };
@@ -17,6 +18,10 @@ type LocalSlugUpdatePlan = {
         source: string;
         target: string;
     }>;
+    directoryMoves: Array<{
+        source: string;
+        target: string;
+    }>;
     metadata: {
         root: string;
         resourceType: ContentType.CHART | ContentType.DASHBOARD;
@@ -28,11 +33,11 @@ export type LocalSlugUpdateFileChange = {
     source: string;
     target?: string;
 };
-export declare const planLocalSlugUpdate: (customPath: string | undefined, from: string, to: string, resourceType?: ContentType.CHART | ContentType.DASHBOARD) => Promise<LocalSlugUpdatePlan>;
+export declare const planLocalSlugUpdate: (customPath: string | undefined, from: string, to: string, resourceType?: SlugUpdateResourceType) => Promise<LocalSlugUpdatePlan>;
 export declare const getLocalSlugUpdateFileChanges: (plan: LocalSlugUpdatePlan, customPath: string | undefined) => LocalSlugUpdateFileChange[];
 export declare const applyLocalSlugUpdate: (plan: LocalSlugUpdatePlan) => Promise<() => Promise<void>>;
 export declare const requestSlugUpdate: (projectUuid: string, request: ContentSlugRenameRequest) => Promise<void>;
-export declare const executeSlugUpdate: (projectUuid: string, customPath: string | undefined, from: string, to: string, resourceType?: ContentType.CHART | ContentType.DASHBOARD) => Promise<LocalSlugUpdatePlan>;
+export declare const executeSlugUpdate: (projectUuid: string, customPath: string | undefined, from: string, to: string, resourceType?: SlugUpdateResourceType) => Promise<LocalSlugUpdatePlan>;
 export declare const slugUpdateHandler: (options: SlugUpdateOptions) => Promise<void>;
 export {};
 //# sourceMappingURL=slugUpdate.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"slugUpdate.d.ts","sourceRoot":"","sources":["../../src/handlers/slugUpdate.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,WAAW,EAKX,KAAK,wBAAwB,EAChC,MAAM,mBAAmB,CAAC;AAa3B,KAAK,iBAAiB,GAAG;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,WAAW,CAAC,KAAK,GAAG,WAAW,CAAC,SAAS,CAAC;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,KAAK,mBAAmB,GAAG;IACvB,WAAW,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC1D,SAAS,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrD,QAAQ,EACF;QACI,IAAI,EAAE,MAAM,CAAC;QACb,YAAY,EAAE,WAAW,CAAC,KAAK,GAAG,WAAW,CAAC,SAAS,CAAC;QACxD,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACjC,GACD,SAAS,CAAC;IAChB,iBAAiB,EAAE,MAAM,CAAC;CAC7B,CAAC;AAIF,MAAM,MAAM,yBAAyB,GAAG;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAyFF,eAAO,MAAM,mBAAmB,eAChB,MAAM,GAAG,SAAS,QACxB,MAAM,MACR,MAAM,iBACI,WAAW,CAAC,KAAK,GAAG,WAAW,CAAC,SAAS,KACxD,OAAO,CAAC,mBAAmB,CA2L7B,CAAC;AAEF,eAAO,MAAM,6BAA6B,SAChC,mBAAmB,cACb,MAAM,GAAG,SAAS,KAC/B,yBAAyB,EAuB3B,CAAC;AAuDF,eAAO,MAAM,oBAAoB,SACvB,mBAAmB,KAC1B,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAuD7B,CAAC;AAEF,eAAO,MAAM,iBAAiB,gBACb,MAAM,WACV,wBAAwB,KAClC,OAAO,CAAC,IAAI,CAmBd,CAAC;AAEF,eAAO,MAAM,iBAAiB,gBACb,MAAM,cACP,MAAM,GAAG,SAAS,QACxB,MAAM,MACR,MAAM,iBACI,WAAW,CAAC,KAAK,GAAG,WAAW,CAAC,SAAS,KACxD,OAAO,CAAC,mBAAmB,CAuB7B,CAAC;AAEF,eAAO,MAAM,iBAAiB,YACjB,iBAAiB,KAC3B,OAAO,CAAC,IAAI,CAuDd,CAAC"}
+{"version":3,"file":"slugUpdate.d.ts","sourceRoot":"","sources":["../../src/handlers/slugUpdate.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,WAAW,EAMX,KAAK,wBAAwB,EAChC,MAAM,mBAAmB,CAAC;AAa3B,KAAK,sBAAsB,GACrB,WAAW,CAAC,KAAK,GACjB,WAAW,CAAC,SAAS,GACrB,WAAW,CAAC,QAAQ,CAAC;AAE3B,KAAK,iBAAiB,GAAG;IACrB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAEhB,IAAI,EAAE,WAAW,CAAC,KAAK,GAAG,WAAW,CAAC,SAAS,GAAG,KAAK,CAAC;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,KAAK,mBAAmB,GAAG;IACvB,WAAW,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC1D,SAAS,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAGrD,cAAc,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC1D,QAAQ,EACF;QACI,IAAI,EAAE,MAAM,CAAC;QACb,YAAY,EAAE,WAAW,CAAC,KAAK,GAAG,WAAW,CAAC,SAAS,CAAC;QACxD,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACjC,GACD,SAAS,CAAC;IAChB,iBAAiB,EAAE,MAAM,CAAC;CAC7B,CAAC;AAIF,MAAM,MAAM,yBAAyB,GAAG;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AA+FF,eAAO,MAAM,mBAAmB,eAChB,MAAM,GAAG,SAAS,QACxB,MAAM,MACR,MAAM,iBACI,sBAAsB,KACrC,OAAO,CAAC,mBAAmB,CAwP7B,CAAC;AAEF,eAAO,MAAM,6BAA6B,SAChC,mBAAmB,cACb,MAAM,GAAG,SAAS,KAC/B,yBAAyB,EA2B3B,CAAC;AAuDF,eAAO,MAAM,oBAAoB,SACvB,mBAAmB,KAC1B,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CA8E7B,CAAC;AAEF,eAAO,MAAM,iBAAiB,gBACb,MAAM,WACV,wBAAwB,KAClC,OAAO,CAAC,IAAI,CAmBd,CAAC;AAEF,eAAO,MAAM,iBAAiB,gBACb,MAAM,cACP,MAAM,GAAG,SAAS,QACxB,MAAM,MACR,MAAM,iBACI,sBAAsB,KACrC,OAAO,CAAC,mBAAmB,CAuB7B,CAAC;AAEF,eAAO,MAAM,iBAAiB,YACjB,iBAAiB,KAC3B,OAAO,CAAC,IAAI,CA2Dd,CAAC"}

package/dist/handlers/slugUpdate.js

@@ -25,7 +25,11 @@ const getYamlFiles = async (root) => {
             (entry.name.endsWith('.yml') ||
                 entry.name.endsWith('.yaml')) &&
             !entry.name.endsWith('.language.map.yml') &&
-            !entry.name.endsWith('.language.map.yaml'))
+            !entry.name.endsWith('.language.map.yaml') &&
+            // App bundles can hold installed deps and lockfiles;
+            // neither carries renameable content references.
+            entry.name !== 'pnpm-lock.yaml' &&
+            !entry.parentPath.split(path.sep).includes('node_modules'))
             .map((entry) => path.join(entry.parentPath, entry.name));
     }
     catch (error) {
@@ -57,6 +61,7 @@ const assertMovesAreSafe = async (moves) => {
         }
     }
 };
+const APP_MANIFEST_FILENAME = 'lightdash-app.yml';
 // Comment-only or scalar YAML (e.g. chart-type context files) parses to null or a primitive
 const isYamlMapping = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
 const readYamlDocuments = async (root) => {
@@ -78,18 +83,29 @@ const planLocalSlugUpdate = async (customPath, from, to, resourceType = common_1
     const root = (0, contentAsCodePaths_1.getDownloadFolder)(customPath);
     const fileUpdates = [];
     const fileMoves = [];
+    const directoryMoves = [];
     let referencesUpdated = 0;
     const languageMapKey = resourceType === common_1.ContentType.CHART ? 'chart' : 'dashboard';
     if (!from) {
         throw new common_1.ParameterError('The source slug must not be empty');
     }
-    if (!to || to.length > common_1.MAX_CONTENT_SLUG_LENGTH || (0, common_1.generateSlug)(to) !== to) {
+    if (resourceType === common_1.ContentType.DATA_APP) {
+        // App slugs follow the server's own shape check, which allows more
+        // than generateSlug emits (e.g. consecutive hyphens).
+        if (!(0, common_1.isValidDataAppSlug)(to)) {
+            throw new common_1.ParameterError(`Invalid data app slug "${to}". Slugs must start with a lowercase letter or digit and contain only lowercase letters, digits, and hyphens, up to 255 characters.`);
+        }
+    }
+    else if (!to ||
+        to.length > common_1.MAX_CONTENT_SLUG_LENGTH ||
+        (0, common_1.generateSlug)(to) !== to) {
         throw new common_1.ParameterError(`The target slug must contain between 1 and ${common_1.MAX_CONTENT_SLUG_LENGTH} lowercase letters, numbers, or hyphen-separated words`);
     }
     if (from === to) {
         return {
             fileUpdates,
             fileMoves,
+            directoryMoves,
             metadata: undefined,
             referencesUpdated,
         };
@@ -102,6 +118,38 @@ const planLocalSlugUpdate = async (customPath, from, to, resourceType = common_1
     });
     for (const { filePath, document, parsed } of contentDocuments) {
         let changed = false;
+        if (resourceType === common_1.ContentType.DATA_APP) {
+            if (path.basename(filePath) === APP_MANIFEST_FILENAME &&
+                parsed.slug === from) {
+                document.set('slug', to);
+                referencesUpdated += 1;
+                changed = true;
+                // Bundles download to a folder named after the slug; keep the
+                // folder in step so the next download matches it.
+                const bundleDir = path.dirname(filePath);
+                if (path.basename(bundleDir) === from) {
+                    directoryMoves.push({
+                        source: bundleDir,
+                        target: path.join(path.dirname(bundleDir), to),
+                    });
+                }
+            }
+            if (Array.isArray(parsed.tiles)) {
+                for (const [index, tile] of parsed.tiles.entries()) {
+                    if (tile.type === 'data_app' &&
+                        tile.properties?.appSlug === from) {
+                        document.setIn(['tiles', index, 'properties', 'appSlug'], to);
+                        referencesUpdated += 1;
+                        changed = true;
+                    }
+                }
+            }
+            if (changed) {
+                fileUpdates.push({ filePath, content: document.toString() });
+            }
+            // eslint-disable-next-line no-continue
+            continue;
+        }
         const isChart = parsed.contentType === common_1.ContentType.CHART ||
             parsed.metricQuery !== undefined;
         const isDashboard = parsed.contentType === common_1.ContentType.DASHBOARD ||
@@ -185,24 +233,28 @@ const planLocalSlugUpdate = async (customPath, from, to, resourceType = common_1
             fileUpdates.push({ filePath, content: document.toString() });
         }
     }
-    const metadata = await (0, metadataFile_1.readMetadataFile)(root);
     let updatedMetadata;
-    const metadataSlugs = resourceType === common_1.ContentType.CHART
-        ? metadata.charts
-        : metadata.dashboards;
-    if (from in metadataSlugs) {
-        if (to !== from && to in metadataSlugs) {
-            throw new common_1.ParameterError(`Cannot update local metadata because ${resourceType} slug "${to}" already exists`);
+    // The local metadata file only tracks charts and dashboards.
+    if (resourceType !== common_1.ContentType.DATA_APP) {
+        const metadata = await (0, metadataFile_1.readMetadataFile)(root);
+        const metadataSlugs = resourceType === common_1.ContentType.CHART
+            ? metadata.charts
+            : metadata.dashboards;
+        if (from in metadataSlugs) {
+            if (to !== from && to in metadataSlugs) {
+                throw new common_1.ParameterError(`Cannot update local metadata because ${resourceType} slug "${to}" already exists`);
+            }
+            const slugs = { ...metadataSlugs };
+            slugs[to] = slugs[from];
+            delete slugs[from];
+            updatedMetadata = { root, resourceType, slugs };
         }
-        const slugs = { ...metadataSlugs };
-        slugs[to] = slugs[from];
-        delete slugs[from];
-        updatedMetadata = { root, resourceType, slugs };
     }
-    await assertMovesAreSafe(fileMoves);
+    await assertMovesAreSafe([...fileMoves, ...directoryMoves]);
     return {
         fileUpdates,
         fileMoves,
+        directoryMoves,
         metadata: updatedMetadata,
         referencesUpdated,
     };
@@ -217,6 +269,10 @@ const getLocalSlugUpdateFileChanges = (plan, customPath) => {
             source: relative(source),
             target: relative(target),
         })),
+        ...plan.directoryMoves.map(({ source, target }) => ({
+            source: `${relative(source)}${path.sep}`,
+            target: `${relative(target)}${path.sep}`,
+        })),
         ...plan.fileUpdates
             .filter(({ filePath }) => !movedSources.has(filePath))
             .map(({ filePath }) => ({ source: relative(filePath) })),
@@ -273,6 +329,14 @@ const applyLocalSlugUpdate = async (plan) => {
     ]);
     const snapshots = await captureFiles(affectedPaths);
     const stagedMoves = [];
+    const appliedDirectoryMoves = [];
+    const undoDirectoryMoves = async () => {
+        for (const move of [...appliedDirectoryMoves].reverse()) {
+            // eslint-disable-next-line no-await-in-loop
+            await fs_1.promises.rename(move.target, move.source);
+        }
+        appliedDirectoryMoves.length = 0;
+    };
     try {
         await Promise.all(plan.fileUpdates.map(({ filePath, content }) => fs_1.promises.writeFile(filePath, content)));
         for (const [index, move] of plan.fileMoves.entries()) {
@@ -285,6 +349,13 @@ const applyLocalSlugUpdate = async (plan) => {
             // eslint-disable-next-line no-await-in-loop
             await fs_1.promises.rename(stagedMoves[index], move.target);
         }
+        // Directory renames (data-app bundle folders) go last so every file
+        // write above targets the original paths.
+        for (const move of plan.directoryMoves) {
+            // eslint-disable-next-line no-await-in-loop
+            await fs_1.promises.rename(move.source, move.target);
+            appliedDirectoryMoves.push(move);
+        }
         if (plan.metadata && metadataPath) {
             const existing = await (0, metadataFile_1.readMetadataFile)(plan.metadata.root);
             await fs_1.promises.writeFile(metadataPath, JSON.stringify({
@@ -296,11 +367,17 @@ const applyLocalSlugUpdate = async (plan) => {
         }
     }
     catch (error) {
+        // Directory moves roll back first so restored files land inside
+        // folders at their original paths.
+        await undoDirectoryMoves();
         await Promise.all(stagedMoves.map((temporary) => fs_1.promises.rm(temporary, { force: true })));
         await restoreFiles(snapshots);
         throw error;
     }
-    return () => restoreFiles(snapshots);
+    return async () => {
+        await undoDirectoryMoves();
+        await restoreFiles(snapshots);
+    };
 };
 exports.applyLocalSlugUpdate = applyLocalSlugUpdate;
 const requestSlugUpdate = async (projectUuid, request) => {
@@ -341,6 +418,8 @@ const slugUpdateHandler = async (options) => {
     (0, credentials_1.refuseAgentConnection)();
     globalState_1.default.setVerbose(options.verbose);
     await (0, apiClient_1.checkLightdashVersion)();
+    const resourceType = options.type === 'app' ? common_1.ContentType.DATA_APP : options.type;
+    const resourceLabel = options.type === 'app' ? 'data app' : options.type;
     const config = await (0, config_1.getConfig)();
     await (0, credentials_1.resolveCredential)(config);
     if (!config.context?.serverUrl)
@@ -350,17 +429,17 @@ const slugUpdateHandler = async (options) => {
         throw new common_1.ParameterError('No project selected. Run lightdash config set-project');
     }
     (0, selectProject_1.logSelectedProject)(selection, config, options.dryRun
-        ? `Previewing ${options.type} slug update in`
-        : `Updating ${options.type} slug in`);
+        ? `Previewing ${resourceLabel} slug update in`
+        : `Updating ${resourceLabel} slug in`);
     if (options.dryRun) {
-        const localPlan = await (0, exports.planLocalSlugUpdate)(options.path, options.from, options.to, options.type);
-        console.info(styles.success(`Would update ${options.type} slug "${options.from}" -> "${options.to}".`));
+        const localPlan = await (0, exports.planLocalSlugUpdate)(options.path, options.from, options.to, resourceType);
+        console.info(styles.success(`Would update ${resourceLabel} slug "${options.from}" -> "${options.to}".`));
         logLocalSlugUpdateFileChanges(localPlan, options.path, true);
         console.info(styles.secondary('No changes were made.'));
         return;
     }
-    const localPlan = await (0, exports.executeSlugUpdate)(selection.projectUuid, options.path, options.from, options.to, options.type);
-    console.info(styles.success(`Updated ${options.type} slug "${options.from}" -> "${options.to}".`));
+    const localPlan = await (0, exports.executeSlugUpdate)(selection.projectUuid, options.path, options.from, options.to, resourceType);
+    console.info(styles.success(`Updated ${resourceLabel} slug "${options.from}" -> "${options.to}".`));
     logLocalSlugUpdateFileChanges(localPlan, options.path, false);
 };
 exports.slugUpdateHandler = slugUpdateHandler;

package/dist/index.js

@@ -711,9 +711,9 @@ commander_1.program
     .action(renameHandler_1.renameHandler);
 commander_1.program
     .command('slug-update')
-    .description('Rename a chart or dashboard slug and update its local references')
+    .description('Rename a chart, dashboard, or data app slug and update its local references')
     .addOption(new commander_1.Option('--type <resource-type>', 'content type to rename')
-    .choices(['chart', 'dashboard'])
+    .choices(['chart', 'dashboard', 'app'])
     .default('chart'))
     .option('--verbose', 'show verbose output', false)
     .option('--project <project uuid or slug>', 'specify a project by UUID or slug', parseProjectArgument, undefined)

package/dist/vendor/template/skill.md

@@ -608,6 +608,8 @@ function RevenueTable() {
 
 ### Formatting
 
+**Trust Lightdash's values for date/time display — never re-convert them.** Date and timestamp values arrive as the correct wall-clock reading with a `Z` suffix (e.g. a March 1st date is `'2025-03-01T00:00:00Z'`). Rendering them through anything timezone-aware — `new Date(value).toLocaleDateString()`, `Intl.DateTimeFormat`, `date-fns-tz`, or manual offset math — shifts them into the viewer's local timezone, so a viewer behind UTC sees Feb 28 where Lightdash shows Mar 1. Always display dates via `format(row, fieldName)` or the `@/lib/format` helpers below (they render the server's wall-clock components as-is); when formatting manually, format the date's own Y/M/D components, never a locale/timezone conversion of them.
+
 Every Lightdash row carries two views of each value:
 
 - `row[fieldName]` — the **raw** value. Numbers are real numbers; **dates and timestamps are full ISO strings** (e.g. `'2025-03-01T00:00:00Z'`) regardless of the truncation grain. Pass these to charts as data, not as axis labels.
@@ -636,17 +638,15 @@ import { formatField, formatDate, formatNumber, getColumn } from '@/lib/format';
 - number — server-formatted (currency / % / suffix preserved via the SDK `format()` you pass in)
 - timestamp without grain — `Jun 16, 2025 14:00`
 
-**Override** by passing `opts.pattern` to `formatDate`, or by formatting yourself with `date-fns`/`Intl.NumberFormat`:
+**Override** by passing `opts.pattern` to `formatDate` — this keeps the server's wall-clock reading while changing the pattern:
 
 ```tsx
-import { format as formatDateFns, parseISO } from 'date-fns';
-
 formatDate(row.order_date_month, getColumn(columns, 'order_date_month'), 'axis', { pattern: 'MMM yyyy' });
-
-// Or fully manual:
-formatDateFns(parseISO(row.order_date as string), 'EEEE, MMM d');
+formatDate(row.order_date, undefined, 'cell', { pattern: 'EEEE, MMM d' });
 ```
 
+Avoid `parseISO`/`new Date` + `format` from `date-fns` for display: the `Z` suffix makes them shift the value into the viewer's timezone, moving midnight dates to the previous day for viewers behind UTC.
+
 #### Chart axes
 
 **Every `<XAxis>` and `<YAxis>` in the app must have a `tickFormatter`.** No exceptions — including year axes that "look like they'd be fine" (`order_date_year` is still a full ISO timestamp at the data layer; Recharts will render `2025-01-01T00:00:00Z`, not `2025`).
@@ -1379,6 +1379,7 @@ The action-menu example above shows typical `drillDown()` usage. For the full AP
 | Skipping `tickFormatter` on a year axis because "year is just a number" | Year dimensions (`*_year`) are still full ISO timestamps at the data layer, so the axis renders `2025-01-01T00:00:00Z` | Apply the same `formatDate(...)` `tickFormatter` to year axes — `formatDate` will collapse to `2025` for year-grain columns |
 | Using `format(row, 'order_date')` for a date column in a table cell | Renders `2025-03-17` (zero-padded tabular) — readable but ugly in dashboards | `formatField(row, col, format, 'cell')` from `@/lib/format` — renders `Mar 17, 2025` while still routing currency/% metrics through the server format |
 | Treating `row.order_date_month` as a `Date` or short string | It's a full ISO timestamp string (`2025-03-01T00:00:00Z`) for every grain | Pass through `formatDate` / `formatField`, or `parseISO` it before doing date math |
+| Displaying dates via `toLocaleDateString()`, `Intl.DateTimeFormat`, or `parseISO` + `format` | The `Z` suffix makes these convert to the viewer's timezone — viewers behind UTC see the previous day (e.g. Feb 28 instead of Mar 1) | Render through `format(row, field)` or `@/lib/format` helpers; they display the server's wall-clock value as-is |
 | Wrong `.parameters()` key scope | Value silently ignored — query returns the default | Project-level → bare name (`{ region }`); model-level → `model.param` (`{ 'orders.region' }`), matching the `${lightdash.parameters.…}` reference |
 | Inventing a parameter not declared in the YAML | Backend ignores unknown params; nothing changes | Only pass parameters that exist in a model's `meta.parameters` or `lightdash.config.yml`. Use `.filters()` for row restriction instead |
 | Applying `.parameters()` at module scope for a UI-driven value | Value never updates when the control changes | Apply `.parameters()` in a `useMemo` keyed on the state value; keep the base query at module scope |

package/dist/vendor/template/src/lib/format.ts

@@ -1,5 +1,5 @@
-import { format as formatDateFns, parseISO } from 'date-fns';
 import type { Column, FormatFunction, Row } from '@lightdash/query-sdk';
+import { format as formatDateFns, parseISO } from 'date-fns';
 
 export type FormatVariant = 'cell' | 'axis';
 
@@ -21,6 +21,93 @@ function inferGranularity(name: string): DateGranularity | undefined {
     return undefined;
 }
 
+// Lightdash returns dates/timestamps as the project's wall-clock reading with
+// a `Z` suffix (e.g. a March 1st date arrives as '2025-03-01T00:00:00Z').
+// Parsing that with `parseISO`/`new Date` and formatting locally shifts it
+// into the viewer's timezone — a UTC-7 viewer would see "Feb 28". Render the
+// wall-clock components exactly as the server sent them instead.
+const ISO_WALL_CLOCK_RE =
+    /^(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,3}))?)?)?/;
+
+/**
+ * A Date whose local-time getters return UTC components, so date-fns `format`
+ * renders the stored wall-clock reading in every viewer timezone. A plain
+ * `new Date(y, m, d, h, …)` is not enough: the constructor interprets the
+ * components in the viewer's timezone and normalizes local times that don't
+ * exist there (a DST spring-forward gap turns 02:30 into 03:30). date-fns
+ * clones inputs via their own constructor, so the subclass survives `format`.
+ * Same mechanism as @date-fns/utc's UTCDate, without the dependency.
+ */
+class WallClockDate extends Date {
+    getFullYear() {
+        return this.getUTCFullYear();
+    }
+
+    getMonth() {
+        return this.getUTCMonth();
+    }
+
+    getDate() {
+        return this.getUTCDate();
+    }
+
+    getDay() {
+        return this.getUTCDay();
+    }
+
+    getHours() {
+        return this.getUTCHours();
+    }
+
+    getMinutes() {
+        return this.getUTCMinutes();
+    }
+
+    getSeconds() {
+        return this.getUTCSeconds();
+    }
+
+    getMilliseconds() {
+        return this.getUTCMilliseconds();
+    }
+
+    getTimezoneOffset() {
+        return 0;
+    }
+
+    // Setters must match the getters: date-fns week tokens (II, ww, RRRR)
+    // compute via startOfWeek, which mutates clones with setDate/setHours.
+    // Inheriting the local setters would mix UTC reads with local writes and
+    // land on the wrong ISO week in non-UTC viewer timezones.
+    setFullYear(...args: Parameters<Date['setFullYear']>) {
+        return this.setUTCFullYear(...args);
+    }
+
+    setMonth(...args: Parameters<Date['setMonth']>) {
+        return this.setUTCMonth(...args);
+    }
+
+    setDate(day: number) {
+        return this.setUTCDate(day);
+    }
+
+    setHours(...args: Parameters<Date['setHours']>) {
+        return this.setUTCHours(...args);
+    }
+
+    setMinutes(...args: Parameters<Date['setMinutes']>) {
+        return this.setUTCMinutes(...args);
+    }
+
+    setSeconds(...args: Parameters<Date['setSeconds']>) {
+        return this.setUTCSeconds(...args);
+    }
+
+    setMilliseconds(ms: number) {
+        return this.setUTCMilliseconds(ms);
+    }
+}
+
 function toDate(value: unknown): Date | null {
     if (value === null || value === undefined || value === '') return null;
     if (value instanceof Date)
@@ -30,6 +117,23 @@ function toDate(value: unknown): Date | null {
         return Number.isNaN(d.getTime()) ? null : d;
     }
     if (typeof value === 'string') {
+        const wallClock = ISO_WALL_CLOCK_RE.exec(value);
+        if (wallClock) {
+            const [, year, month, day, hours, minutes, seconds, millis] =
+                wallClock;
+            const d = new WallClockDate(
+                Date.UTC(
+                    Number(year),
+                    Number(month) - 1,
+                    Number(day),
+                    Number(hours ?? 0),
+                    Number(minutes ?? 0),
+                    Number(seconds ?? 0),
+                    Number(millis?.padEnd(3, '0') ?? 0),
+                ),
+            );
+            return Number.isNaN(d.getTime()) ? null : d;
+        }
         const d = parseISO(value);
         return Number.isNaN(d.getTime()) ? null : d;
     }
@@ -135,9 +239,6 @@ export function formatField(
     }
 }
 
-export function getColumn(
-    columns: Column[],
-    name: string,
-): Column | undefined {
+export function getColumn(columns: Column[], name: string): Column | undefined {
     return columns.find((c) => c.name === name);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightdash/cli",
-  "version": "3.163.1",
+  "version": "3.165.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.163.1",
-    "@lightdash/warehouses": "3.163.1",
+    "@lightdash/common": "3.165.0",
+    "@lightdash/warehouses": "3.165.0",
     "@sidvind/better-ajv-errors": "7.0.0",
     "@types/columnify": "1.5.1",
     "ajv": "8.18.0",
@@ -61,6 +61,7 @@
     "@vercel/ncc": "0.38.4",
     "@yao-pkg/pkg": "6.24.0",
     "copyfiles": "2.4.1",
+    "date-fns": "3.6.0",
     "oxlint": "1.75.0",
     "oxlint-tsgolint": "7.0.2001",
     "tsx": "4.19.4",