@malloy-publisher/sdk 0.0.227 → 0.0.229

package/src/components/Materializations/Materializations.tsx

@@ -9,7 +9,11 @@ import {
 } from "@mui/material";
 import { useQueryClient } from "@tanstack/react-query";
 import React, { useState } from "react";
-import { Materialization, MaterializationActionActionEnum } from "../../client";
+import {
+   Materialization,
+   MaterializationActionActionEnum,
+   PackageScopeEnum,
+} from "../../client";
 import {
    useMutationWithApiError,
    useQueryWithApiError,
@@ -21,6 +25,7 @@ import { useServer } from "../ServerProvider";
 import CreateMaterializationDialog from "./CreateMaterializationDialog";
 import MaterializationDetailDialog from "./MaterializationDetailDialog";
 import MaterializationRunsList from "./MaterializationRunsList";
+import ScheduleCard from "./ScheduleCard";
 import { isActiveStatus } from "./utils";
 
 const MATERIALIZATION_POLL_MS = 3000;
@@ -144,6 +149,60 @@ export default function Materializations({
       },
    });
 
+   const currentPackage = packageQuery.data?.data;
+
+   // Edit the package's materialization.schedule (persisted to publisher.json).
+   // A schedule is legal only on a version-scoped package, so enabling one also
+   // sets scope: version; clearing (null) leaves scope untouched — scope is an
+   // explicit control (updateScope below), so clearing a schedule no longer
+   // strands scope: version with no way back. The running scheduler re-arms from
+   // the new cron on its next tick — no reload needed.
+   const updateSchedule = useMutationWithApiError({
+      mutationFn: (schedule: string | null) =>
+         apiClients.packages.updatePackage(environmentName, packageName, {
+            name: packageName,
+            // updatePackage overwrites description from the body — carry the
+            // current value through so a schedule edit doesn't drop it.
+            description: currentPackage?.description,
+            ...(schedule ? { scope: PackageScopeEnum.Version } : {}),
+            materialization: { schedule },
+         }),
+      onSuccess(_data, schedule) {
+         setNotificationMessage(
+            schedule ? "Schedule updated" : "Schedule cleared",
+         );
+         queryClient.invalidateQueries({
+            queryKey: ["package", environmentName, packageName],
+         });
+      },
+      onError(error) {
+         setNotificationMessage(error.message);
+      },
+   });
+
+   // Set the persist scope explicitly (package | version). Independent of the
+   // schedule so the version flip a schedule requires can be undone after the
+   // schedule is cleared. The server rejects scope: package while a schedule is
+   // still set (publish-gate Rule 2), so the UI only offers this when no
+   // schedule is active.
+   const updateScope = useMutationWithApiError({
+      mutationFn: (scope: PackageScopeEnum) =>
+         apiClients.packages.updatePackage(environmentName, packageName, {
+            name: packageName,
+            description: currentPackage?.description,
+            scope,
+         }),
+      onSuccess() {
+         setNotificationMessage("Scope updated");
+         queryClient.invalidateQueries({
+            queryKey: ["package", environmentName, packageName],
+         });
+      },
+      onError(error) {
+         setNotificationMessage(error.message);
+      },
+   });
+
    const materializations = (listQuery.data?.data ?? []) as Materialization[];
    const selected =
       materializations.find((row) => row.id === selectedId) ?? null;
@@ -213,6 +272,32 @@ export default function Materializations({
             </Stack>
          </Box>
 
+         {packageQuery.isSuccess && (
+            <ScheduleCard
+               schedule={currentPackage?.materialization?.schedule ?? null}
+               scope={
+                  currentPackage?.scope === PackageScopeEnum.Version
+                     ? "version"
+                     : "package"
+               }
+               manifestLocation={currentPackage?.manifestLocation ?? null}
+               hasFreshness={Boolean(
+                  currentPackage?.materialization?.freshness,
+               )}
+               mutable={mutable}
+               isSubmitting={updateSchedule.isPending}
+               isScopeMutating={updateScope.isPending}
+               onSubmit={(schedule) => updateSchedule.mutateAsync(schedule)}
+               onScopeChange={(scope) =>
+                  updateScope.mutateAsync(
+                     scope === "version"
+                        ? PackageScopeEnum.Version
+                        : PackageScopeEnum.Package,
+                  )
+               }
+            />
+         )}
+
          <Box sx={{ mb: 6 }}>
             <Typography
                variant="h6"

package/src/components/Materializations/ScheduleCard.tsx

@@ -0,0 +1,228 @@
+import ScheduleIcon from "@mui/icons-material/Schedule";
+import {
+   Box,
+   Card,
+   CardContent,
+   Chip,
+   Stack,
+   ToggleButton,
+   ToggleButtonGroup,
+   Tooltip,
+   Typography,
+} from "@mui/material";
+import { MONO_FONT_FAMILY } from "../styles";
+import { describeCron, formatNextRun } from "./cron";
+import SetScheduleDialog from "./SetScheduleDialog";
+
+type Scope = "package" | "version";
+
+type ScheduleCardProps = {
+   /** The package's cron, or null when no schedule is declared. */
+   schedule: string | null;
+   /** The package's persist scope. */
+   scope: Scope;
+   /** When set, the package is control-plane-driven (orchestrated). */
+   manifestLocation: string | null;
+   /** True when the package declares a freshness policy (schedule N/A). */
+   hasFreshness: boolean;
+   mutable: boolean;
+   isSubmitting: boolean;
+   /** True while a scope change is in flight. */
+   isScopeMutating?: boolean;
+   onSubmit: (schedule: string | null) => Promise<unknown>;
+   /** Persist a new scope (package | version). */
+   onScopeChange?: (scope: Scope) => Promise<unknown>;
+};
+
+export default function ScheduleCard({
+   schedule,
+   scope,
+   manifestLocation,
+   hasFreshness,
+   mutable,
+   isSubmitting,
+   isScopeMutating,
+   onSubmit,
+   onScopeChange,
+}: ScheduleCardProps) {
+   const orchestrated = Boolean(manifestLocation);
+   const info = schedule ? describeCron(schedule) : null;
+   // A schedule requires version scope, so scope is locked while one is set —
+   // the server would reject scope: package (publish-gate Rule 2). Clearing the
+   // schedule unlocks it, giving an explicit way back to package scope.
+   const scopeLocked = Boolean(schedule);
+
+   return (
+      <Card variant="outlined" sx={{ borderRadius: 2, mb: 6 }}>
+         <CardContent>
+            <Stack
+               direction="row"
+               justifyContent="space-between"
+               alignItems="flex-start"
+               spacing={2}
+            >
+               <Box sx={{ minWidth: 0 }}>
+                  <Stack
+                     direction="row"
+                     alignItems="center"
+                     spacing={1}
+                     sx={{ mb: 1 }}
+                  >
+                     <ScheduleIcon fontSize="small" color="action" />
+                     <Typography
+                        variant="h6"
+                        sx={{ fontWeight: 600, letterSpacing: "-0.025em" }}
+                     >
+                        Schedule
+                     </Typography>
+                  </Stack>
+
+                  {orchestrated ? (
+                     <Box>
+                        <Chip
+                           size="small"
+                           color="default"
+                           variant="outlined"
+                           label="Control-plane managed"
+                           sx={{ mb: 1 }}
+                        />
+                        <Typography variant="body2" color="text.secondary">
+                           Refresh is driven by the control plane; the built-in
+                           scheduler does not fire this package.
+                        </Typography>
+                     </Box>
+                  ) : info ? (
+                     <Box>
+                        <Stack
+                           direction="row"
+                           alignItems="center"
+                           spacing={1}
+                           sx={{ mb: 0.5, flexWrap: "wrap" }}
+                        >
+                           <Chip
+                              size="small"
+                              color="success"
+                              variant="outlined"
+                              icon={<ScheduleIcon fontSize="small" />}
+                              label="Active"
+                           />
+                           <Box
+                              component="code"
+                              sx={{
+                                 fontFamily: MONO_FONT_FAMILY,
+                                 fontSize: "0.8125rem",
+                                 px: 0.75,
+                                 py: 0.25,
+                                 borderRadius: 1,
+                                 bgcolor: "action.hover",
+                              }}
+                           >
+                              {schedule}
+                           </Box>
+                        </Stack>
+                        <Typography variant="body2">
+                           {info.valid
+                              ? info.description
+                              : "Unrecognized cron expression."}
+                        </Typography>
+                        {info.valid && (
+                           <Typography variant="body2" color="text.secondary">
+                              Next run: {formatNextRun(info.nextRun)}
+                           </Typography>
+                        )}
+                     </Box>
+                  ) : hasFreshness ? (
+                     <Typography variant="body2" color="text.secondary">
+                        This package uses a freshness policy; a cron schedule is
+                        not applicable.
+                     </Typography>
+                  ) : (
+                     <Typography variant="body2" color="text.secondary">
+                        On-demand only — no schedule set.
+                     </Typography>
+                  )}
+
+                  {!orchestrated && (
+                     <Box sx={{ mt: 2 }}>
+                        <Typography
+                           variant="caption"
+                           color="text.secondary"
+                           sx={{ display: "block", mb: 0.5 }}
+                        >
+                           Scope
+                        </Typography>
+                        <Tooltip
+                           title={
+                              scopeLocked
+                                 ? "A schedule requires version scope. Clear the schedule to change it."
+                                 : ""
+                           }
+                        >
+                           <span>
+                              <ToggleButtonGroup
+                                 size="small"
+                                 exclusive
+                                 value={scope}
+                                 disabled={
+                                    !mutable ||
+                                    !onScopeChange ||
+                                    scopeLocked ||
+                                    Boolean(isScopeMutating)
+                                 }
+                                 onChange={(_e, next: Scope | null) => {
+                                    if (next && next !== scope) {
+                                       onScopeChange?.(next);
+                                    }
+                                 }}
+                              >
+                                 <ToggleButton value="package">
+                                    package
+                                 </ToggleButton>
+                                 <ToggleButton value="version">
+                                    version
+                                 </ToggleButton>
+                              </ToggleButtonGroup>
+                           </span>
+                        </Tooltip>
+                        <Typography
+                           variant="caption"
+                           color="text.secondary"
+                           sx={{ display: "block", mt: 0.5 }}
+                        >
+                           {scope === "version"
+                              ? "Materialized artifacts are per version (required for a schedule)."
+                              : "Materialized artifacts are shared across versions."}
+                        </Typography>
+                     </Box>
+                  )}
+
+                  <Typography
+                     variant="caption"
+                     color="text.secondary"
+                     sx={{ display: "block", mt: 1.5 }}
+                  >
+                     Declared in <code>publisher.json</code>.
+                     {!orchestrated && (
+                        <>
+                           {" "}
+                           In a hosted deployment, a change takes effect on your
+                           next publish.
+                        </>
+                     )}
+                  </Typography>
+               </Box>
+
+               {mutable && !orchestrated && (
+                  <SetScheduleDialog
+                     currentSchedule={schedule}
+                     isSubmitting={isSubmitting}
+                     disabled={hasFreshness}
+                     disabledReason="This package declares a freshness policy; a schedule and freshness are mutually exclusive."
+                     onSubmit={onSubmit}
+                  />
+               )}
+            </Stack>
+         </CardContent>
+      </Card>
+   );
+}

package/src/components/Materializations/SectionLabel.tsx

@@ -0,0 +1,27 @@
+import { Typography } from "@mui/material";
+import { ReactNode } from "react";
+
+/**
+ * Small uppercase section heading for consistent hierarchy across the
+ * materialization views (detail dialog, manifest view). One source of truth for
+ * the style so the headings can't drift. Renders as an <h6> so it is a real
+ * heading (role="heading") — the caption styling is purely visual.
+ */
+export default function SectionLabel({ children }: { children: ReactNode }) {
+   return (
+      <Typography
+         variant="caption"
+         component="h6"
+         sx={{
+            display: "block",
+            textTransform: "uppercase",
+            letterSpacing: "0.06em",
+            fontWeight: 600,
+            color: "text.secondary",
+            mb: 1,
+         }}
+      >
+         {children}
+      </Typography>
+   );
+}

package/src/components/Materializations/SetScheduleDialog.tsx

@@ -0,0 +1,159 @@
+import ScheduleIcon from "@mui/icons-material/Schedule";
+import {
+   Alert,
+   Box,
+   Button,
+   Dialog,
+   DialogActions,
+   DialogContent,
+   DialogContentText,
+   DialogTitle,
+   TextField,
+   Tooltip,
+   Typography,
+} from "@mui/material";
+import { useState } from "react";
+import { MONO_FONT_FAMILY } from "../styles";
+import { describeCron, formatNextRun } from "./cron";
+
+type SetScheduleDialogProps = {
+   /** The current cron, or null when no schedule is set. */
+   currentSchedule: string | null;
+   isSubmitting: boolean;
+   disabled?: boolean;
+   disabledReason?: string;
+   /** Persist a new cron, or null to clear the schedule. */
+   onSubmit: (schedule: string | null) => Promise<unknown>;
+};
+
+const DEFAULT_CRON = "0 6 * * *";
+
+export default function SetScheduleDialog({
+   currentSchedule,
+   isSubmitting,
+   disabled,
+   disabledReason,
+   onSubmit,
+}: SetScheduleDialogProps) {
+   const [open, setOpen] = useState(false);
+   const [expr, setExpr] = useState(currentSchedule ?? DEFAULT_CRON);
+
+   const handleOpen = () => {
+      setExpr(currentSchedule ?? DEFAULT_CRON);
+      setOpen(true);
+   };
+   const handleClose = () => setOpen(false);
+
+   const info = describeCron(expr);
+
+   const submit = async (schedule: string | null) => {
+      try {
+         await onSubmit(schedule);
+         setOpen(false);
+      } catch {
+         // The caller surfaces the error via its Snackbar; keep the dialog
+         // open so the user can correct the cron and retry.
+      }
+   };
+
+   const button = (
+      <span>
+         <Button
+            variant="outlined"
+            size="small"
+            startIcon={<ScheduleIcon />}
+            onClick={handleOpen}
+            disabled={disabled}
+            aria-label={currentSchedule ? "Edit schedule" : "Set schedule"}
+         >
+            {currentSchedule ? "Edit schedule" : "Set schedule"}
+         </Button>
+      </span>
+   );
+
+   return (
+      <>
+         {disabled && disabledReason ? (
+            <Tooltip title={disabledReason}>{button}</Tooltip>
+         ) : (
+            button
+         )}
+
+         <Dialog
+            open={open}
+            onClose={handleClose}
+            maxWidth="xs"
+            fullWidth
+            aria-labelledby="set-schedule-title"
+         >
+            <DialogTitle id="set-schedule-title">
+               {currentSchedule ? "Edit schedule" : "Set schedule"}
+            </DialogTitle>
+            <DialogContent>
+               <DialogContentText sx={{ mb: 2 }}>
+                  The publisher rebuilds the materializations in this package on
+                  this cadence. Enter a 5-field UNIX cron, evaluated in UTC. In
+                  a hosted deployment, the change takes effect on your next
+                  publish.
+               </DialogContentText>
+               <TextField
+                  autoFocus
+                  fullWidth
+                  label="Cron expression"
+                  value={expr}
+                  onChange={(event) => setExpr(event.target.value)}
+                  error={expr.trim() !== "" && !info.valid}
+                  slotProps={{
+                     htmlInput: { style: { fontFamily: MONO_FONT_FAMILY } },
+                  }}
+               />
+               <Box sx={{ mt: 1.5, minHeight: 48 }}>
+                  {info.valid ? (
+                     <>
+                        <Typography variant="body2">
+                           {info.description}
+                        </Typography>
+                        <Typography variant="body2" color="text.secondary">
+                           Next run: {formatNextRun(info.nextRun)}
+                        </Typography>
+                     </>
+                  ) : (
+                     <Typography variant="body2" color="error">
+                        {info.error}
+                     </Typography>
+                  )}
+               </Box>
+               <Alert severity="info" sx={{ mt: 2 }}>
+                  A schedule runs only on version-scoped packages, so saving one
+                  sets <code>scope: version</code> for this package.
+               </Alert>
+            </DialogContent>
+            <DialogActions sx={{ justifyContent: "space-between", px: 3 }}>
+               <Box>
+                  {currentSchedule && (
+                     <Button
+                        color="error"
+                        loading={isSubmitting}
+                        onClick={() => submit(null)}
+                     >
+                        Clear schedule
+                     </Button>
+                  )}
+               </Box>
+               <Box>
+                  <Button onClick={handleClose}>Cancel</Button>
+                  <Button
+                     variant="contained"
+                     loading={isSubmitting}
+                     disabled={!info.valid}
+                     onClick={() => submit(expr.trim())}
+                     sx={{ ml: 1 }}
+                  >
+                     Save
+                  </Button>
+               </Box>
+            </DialogActions>
+         </Dialog>
+      </>
+   );
+}

package/src/components/Materializations/TriggerChip.tsx

@@ -0,0 +1,41 @@
+import ScheduleIcon from "@mui/icons-material/Schedule";
+import TouchAppIcon from "@mui/icons-material/TouchApp";
+import { Chip, Tooltip } from "@mui/material";
+import { MaterializationMetadata, triggerLabel } from "./utils";
+
+/**
+ * Chip showing how a run was initiated — Scheduled (the standalone scheduler
+ * fired the package's cron) vs Manual (an API/UI create) — with a tooltip. One
+ * source of truth for the color/icon/label so the runs list and the detail
+ * dialog can never drift.
+ */
+export default function TriggerChip({
+   meta,
+}: {
+   meta: MaterializationMetadata;
+}) {
+   const scheduled = meta.trigger === "SCHEDULER";
+   return (
+      <Tooltip
+         title={
+            scheduled
+               ? "Fired by the materialization schedule"
+               : "Triggered manually"
+         }
+      >
+         <Chip
+            size="small"
+            variant="outlined"
+            color={scheduled ? "info" : "default"}
+            icon={
+               scheduled ? (
+                  <ScheduleIcon fontSize="small" />
+               ) : (
+                  <TouchAppIcon fontSize="small" />
+               )
+            }
+            label={triggerLabel(meta)}
+         />
+      </Tooltip>
+   );
+}

package/src/components/Materializations/cron.ts

@@ -0,0 +1,121 @@
+import { CronExpressionParser } from "cron-parser";
+import cronstrue from "cronstrue";
+
+export interface CronInfo {
+   valid: boolean;
+   /** Human-readable summary, e.g. "Every minute" (empty when invalid). */
+   description: string;
+   /** Next fire instant in UTC (null when invalid). */
+   nextRun: Date | null;
+   /** Reason the expression was rejected (set only when `valid` is false). */
+   error?: string;
+}
+
+/** Valid 3-letter month and day-of-week names in UNIX cron. */
+const UNIX_CRON_NAMES = new Set([
+   "JAN",
+   "FEB",
+   "MAR",
+   "APR",
+   "MAY",
+   "JUN",
+   "JUL",
+   "AUG",
+   "SEP",
+   "OCT",
+   "NOV",
+   "DEC",
+   "SUN",
+   "MON",
+   "TUE",
+   "WED",
+   "THU",
+   "FRI",
+   "SAT",
+]);
+
+/**
+ * Reject cron-parser / Quartz extensions absent from plain UNIX cron (`L`, `W`,
+ * `#`, `?`). Mirrors the server's `CronEvaluator.isPlainUnixGrammar` so the UI
+ * preview flags the same expressions the server (and the control plane) reject,
+ * rather than describing a cron that would silently never arm after publish.
+ */
+function isPlainUnixGrammar(expr: string): boolean {
+   for (const field of expr.trim().split(/\s+/)) {
+      if (/[#?]/.test(field)) return false;
+      for (const token of field.split(/[,\-/]/)) {
+         if (token === "" || token === "*") continue;
+         if (
+            /[A-Za-z]/.test(token) &&
+            !UNIX_CRON_NAMES.has(token.toUpperCase())
+         ) {
+            return false;
+         }
+      }
+   }
+   return true;
+}
+
+/**
+ * Describe a 5-field UNIX cron for display: a human-readable summary (cronstrue)
+ * and the next fire instant (cron-parser, in UTC — matching the publisher's
+ * server-side scheduler so the UI shows the same instants it will fire at).
+ *
+ * The expression is required to be exactly 5 fields and plain UNIX grammar,
+ * mirroring the server's `CronEvaluator`: cron-parser also accepts an optional
+ * leading seconds field (6 fields) and extensions (L/W/#/?), but the manifest
+ * contract is plain 5-field UNIX cron, so those are reported invalid rather
+ * than silently reinterpreted (or accepted here yet rejected after publish).
+ */
+export function describeCron(expr: string): CronInfo {
+   const trimmed = (expr ?? "").trim();
+   if (trimmed.split(/\s+/).filter(Boolean).length !== 5) {
+      return {
+         valid: false,
+         description: "",
+         nextRun: null,
+         error: "Expected a 5-field UNIX cron: minute hour day-of-month month day-of-week.",
+      };
+   }
+   if (!isPlainUnixGrammar(trimmed)) {
+      return {
+         valid: false,
+         description: "",
+         nextRun: null,
+         error: "Unsupported cron syntax: L, W, #, and ? extensions are not allowed (plain 5-field UNIX cron only).",
+      };
+   }
+   try {
+      const description = cronstrue.toString(trimmed, {
+         use24HourTimeFormat: true,
+         verbose: false,
+      });
+      const nextRun = CronExpressionParser.parse(trimmed, { tz: "UTC" })
+         .next()
+         .toDate();
+      return { valid: true, description, nextRun };
+   } catch (e) {
+      return {
+         valid: false,
+         description: "",
+         nextRun: null,
+         error: e instanceof Error ? e.message : "Invalid cron expression.",
+      };
+   }
+}
+
+/** Absolute UTC label for a next-run instant, e.g. "Jul 14, 2026, 06:00 UTC". */
+export function formatNextRun(d: Date | null): string {
+   if (!d) return "—";
+   return (
+      d.toLocaleString(undefined, {
+         year: "numeric",
+         month: "short",
+         day: "numeric",
+         hour: "2-digit",
+         minute: "2-digit",
+         timeZone: "UTC",
+         hour12: false,
+      }) + " UTC"
+   );
+}

package/src/components/Materializations/index.ts

@@ -1 +1,2 @@
 export { default as Materializations } from "./Materializations";
+export { default as EnvironmentMaterializations } from "./EnvironmentMaterializations";