@antelopejs/dms 0.9.0 → 0.9.2

package/frontend-vue/layers/dms-layout/app/build/utils/module-store-catalog.ts

@@ -1,137 +1,203 @@
+import type { Tone } from "#dms-ui/app/types/tone";
+import type { StatusPillDot } from "#dms-ui/app/components/status-pill/StatusPill.vue";
+import type {
+  StoreListingEntry,
+  StoreModuleState,
+  StoreOperationKind,
+} from "../../types/module-store";
 import type { DisplayResolver } from "./modules-catalog";
 
-/**
- * One official module offered by the module store preview. The list below is
- * static for now: it stands in for the AntelopeJS module registry the store
- * will read once installing from the dashboard is possible.
- */
-export interface ModuleStoreEntry {
+/** A store module as the Modules page filters and draws it. */
+export type ModuleStoreEntry = StoreListingEntry & {
+  /** Store category, a `$i18n.key` (what the category chips read). */
+  catalogCategory: string;
+};
+
+/** Which store modules the store section shows. */
+export type StoreScope = "all" | "available" | "installed";
+
+/** What a store tile's pill says. */
+export interface StoreTileStatus {
+  tone: Tone;
+  /** i18n key under `modules.store.state`. */
+  labelKey: string;
+  dot?: StatusPillDot;
+}
+
+/** One action a store tile offers. */
+export interface StoreAction {
+  kind: StoreOperationKind;
+  /** i18n key under `modules.store.actions`. */
+  labelKey: string;
+  icon: string;
+  /** The action runs only once the owner confirms it. */
+  confirm?: boolean;
   /**
-   * Id the module registers in the catalog (`RegisterModule({ id })`): a
-   * store entry whose id is installed is hidden.
+   * Offered in the tile's menu only, never as its button: pausing or
+   * removing a running module is not what its tile should invite.
    */
-  id: string;
-  /** npm package the AntelopeJS CLI adds to the project. */
-  packageName: string;
-  /** Display name, a `$i18n.key`. */
-  title: string;
-  /** One-line summary, a `$i18n.key`. */
-  description: string;
-  /** Iconify name, the icon the module registers once installed. */
-  icon: string;
-  /** Store category, a `$i18n.key`. */
-  catalogCategory: string;
+  isMenuOnly?: boolean;
 }
 
-const CATEGORY = {
-  ai: "$modules.store.category.ai",
-  business: "$modules.store.category.business",
-  content: "$modules.store.category.content",
-  data: "$modules.store.category.data",
-  developer: "$modules.store.category.developer",
-  growth: "$modules.store.category.growth",
-  operations: "$modules.store.category.operations",
-} as const;
-
-function storeEntry(
-  id: string,
-  packageName: string,
-  icon: string,
-  catalogCategory: string,
-): ModuleStoreEntry {
+const CATEGORY_PREFIX = "$modules.store.category";
+
+/** The command that turns a production frontend into one serving new layers. */
+export const FRONTEND_BUILD_COMMAND = "ajs dms build";
+
+const STATUSES: Record<StoreModuleState, StoreTileStatus> = {
+  available: { tone: "neutral", labelKey: "available", dot: "none" },
+  busy: { tone: "info", labelKey: "busy", dot: "live" },
+  active: { tone: "success", labelKey: "active" },
+  disabled: { tone: "neutral", labelKey: "disabled" },
+  error: { tone: "error", labelKey: "error" },
+  pending: { tone: "warning", labelKey: "pending" },
+};
+
+const ACTIONS: Record<StoreOperationKind, StoreAction> = {
+  install: {
+    kind: "install",
+    labelKey: "install",
+    icon: "i-ph-download-simple",
+  },
+  update: { kind: "update", labelKey: "update", icon: "i-ph-arrow-circle-up" },
+  enable: { kind: "enable", labelKey: "enable", icon: "i-ph-play" },
+  disable: {
+    kind: "disable",
+    labelKey: "disable",
+    icon: "i-ph-pause",
+    isMenuOnly: true,
+  },
+  uninstall: {
+    kind: "uninstall",
+    labelKey: "uninstall",
+    icon: "i-ph-trash",
+    confirm: true,
+    isMenuOnly: true,
+  },
+  apply: { kind: "apply", labelKey: "apply", icon: "i-ph-arrows-clockwise" },
+};
+
+/** States of a module that antelope.config.ts declares. */
+const INSTALLED_STATES = new Set<StoreModuleState>([
+  "active",
+  "disabled",
+  "pending",
+]);
+
+export function toModuleStoreEntry(entry: StoreListingEntry): ModuleStoreEntry {
   return {
-    id,
-    packageName,
-    title: `$modules.store.catalog.${id}.title`,
-    description: `$modules.store.catalog.${id}.description`,
-    icon,
-    catalogCategory,
+    ...entry,
+    catalogCategory: `${CATEGORY_PREFIX}.${entry.category}`,
+  };
+}
+
+/** Whether the module is installed, from the store or by the config. */
+export function isInstalled(entry: StoreListingEntry): boolean {
+  if (INSTALLED_STATES.has(entry.state)) return true;
+  return entry.installedVersion !== undefined;
+}
+
+export function filterByScope<T extends StoreListingEntry>(
+  entries: readonly T[],
+  scope: StoreScope,
+): T[] {
+  if (scope === "all") return [...entries];
+  const wantsInstalled = scope === "installed";
+  return entries.filter((entry) => isInstalled(entry) === wantsInstalled);
+}
+
+/** The store modules, alphabetical by their shown name. */
+export function sortStoreModules<T extends StoreListingEntry>(
+  entries: readonly T[],
+  resolve: DisplayResolver,
+): T[] {
+  return [...entries].sort((a, b) =>
+    resolve(a.title).localeCompare(resolve(b.title)),
+  );
+}
+
+export function storeTileStatus(entry: StoreListingEntry): StoreTileStatus {
+  if (entry.state === "active" && entry.updateAvailable) {
+    return { tone: "warning", labelKey: "update_available" };
+  }
+  return STATUSES[entry.state];
+}
+
+/**
+ * What the tile offers, the main action first. A module in error offers to
+ * try its last step again: installing it when the file does not hold it,
+ * applying the file otherwise.
+ */
+export function storeActions(entry: StoreListingEntry): StoreAction[] {
+  const installed = entry.installedVersion !== undefined;
+  const byState: Record<StoreModuleState, StoreOperationKind[]> = {
+    available: ["install"],
+    busy: [],
+    active: entry.updateAvailable
+      ? ["update", "disable", "uninstall"]
+      : ["disable", "uninstall"],
+    disabled: ["enable", "uninstall"],
+    error: installed ? ["apply", "uninstall"] : ["install"],
+    pending: ["apply", "uninstall"],
   };
+  return byState[entry.state].map((kind) => ACTIONS[kind]);
 }
 
 /**
- * The official AntelopeJS DMS modules (one repository each under the
- * AntelopeJS organisation). Ids and icons are the ones each module registers;
- * Media and Builder register no catalog module, so theirs come from their
- * settings page and the v2 design.
+ * Whether the page waits on the frontend for this module: its backend side
+ * changed and the frontend server has not reported serving it yet.
  */
-export const MODULE_STORE_CATALOG: readonly ModuleStoreEntry[] = [
-  storeEntry("ai", "@antelopejs/dms-ai", "i-ph-robot", CATEGORY.ai),
-  storeEntry(
-    "api",
-    "@antelopejs/dms-api",
-    "i-ph-brackets-curly",
-    CATEGORY.developer,
-  ),
-  storeEntry(
-    "automation",
-    "@antelopejs/dms-automation",
-    "i-ph-flow-arrow",
-    CATEGORY.operations,
-  ),
-  storeEntry(
-    "builder",
-    "@antelopejs/dms-builder",
-    "i-ph-hammer",
-    CATEGORY.developer,
-  ),
-  storeEntry(
-    "cicd",
-    "@antelopejs-private/dms-cicd",
-    "i-ph-rocket-launch",
-    CATEGORY.operations,
-  ),
-  storeEntry(
-    "database",
-    "@antelopejs/dms-database",
-    "i-ph-database",
-    CATEGORY.data,
-  ),
-  storeEntry(
-    "lang",
-    "@antelopejs/dms-lang",
-    "i-ph-translate",
-    CATEGORY.content,
-  ),
-  storeEntry(
-    "mailing",
-    "@antelopejs/dms-mailing",
-    "i-ph-envelope-simple",
-    CATEGORY.growth,
-  ),
-  storeEntry(
-    "marketing",
-    "@antelopejs/dms-marketing",
-    "i-ph-chart-line-up",
-    CATEGORY.growth,
-  ),
-  storeEntry("media", "@antelopejs/dms-media", "i-ph-images", CATEGORY.content),
-  storeEntry(
-    "saas",
-    "@antelopejs/dms-saas",
-    "i-ph-buildings",
-    CATEGORY.business,
-  ),
-];
-
-/** The AntelopeJS CLI command that adds a package module to a project. */
-export const MODULE_INSTALL_COMMAND = "ajs project modules add";
-
-/** The full CLI command that adds the module to a project. */
-export function moduleInstallCommand(entry: ModuleStoreEntry): string {
-  return `${MODULE_INSTALL_COMMAND} ${entry.packageName}`;
+export function isAwaitingFrontend(entry: StoreListingEntry): boolean {
+  return entry.state !== "busy" && entry.frontend === "pending";
 }
 
+/** Why an action the tile offers cannot run, as the tile explains it. */
+export type StoreActionBlock =
+  | "no_release"
+  | "incompatible"
+  | "frontend"
+  | "interfaces"
+  | "dependents";
+
+/** Actions that load a new release of the module. */
+const RELEASE_ACTIONS = new Set<StoreOperationKind>(["install", "update"]);
 /**
- * The store entries not installed on this platform, alphabetical by their
- * shown name.
+ * Actions that pick the missing interfaces' modules in a dialog; the others
+ * refuse a release that misses one.
  */
-export function availableStoreModules(
-  catalog: readonly ModuleStoreEntry[],
-  installedIds: ReadonlySet<string>,
-  resolve: DisplayResolver,
-): ModuleStoreEntry[] {
-  return catalog
-    .filter((entry) => !installedIds.has(entry.id))
-    .sort((a, b) => resolve(a.title).localeCompare(resolve(b.title)));
+const PICKS_DEPENDENCIES = new Set<StoreOperationKind>(["install"]);
+/** Actions that take a running module down. */
+const TAKE_DOWN_ACTIONS = new Set<StoreOperationKind>(["disable", "uninstall"]);
+
+function releaseBlock(
+  entry: StoreListingEntry,
+  kind: StoreOperationKind,
+): StoreActionBlock | undefined {
+  if (!entry.latestVersion) return "no_release";
+  if (!entry.compatible) return "incompatible";
+  if (entry.frontendRequirement) return "frontend";
+  if (!PICKS_DEPENDENCIES.has(kind) && entry.missingInterfaces.length > 0) {
+    return "interfaces";
+  }
+  return undefined;
+}
+
+/** Why `kind` cannot run on the module, or undefined when it can. */
+export function storeActionBlock(
+  entry: StoreListingEntry,
+  kind: StoreOperationKind,
+): StoreActionBlock | undefined {
+  if (RELEASE_ACTIONS.has(kind)) return releaseBlock(entry, kind);
+  if (TAKE_DOWN_ACTIONS.has(kind) && entry.dependents.length > 0) {
+    return "dependents";
+  }
+  return undefined;
+}
+
+/** Whether `kind` first asks which modules implement the missing interfaces. */
+export function needsDependencyChoice(
+  entry: StoreListingEntry,
+  kind: StoreOperationKind,
+): boolean {
+  return PICKS_DEPENDENCIES.has(kind) && entry.missingInterfaces.length > 0;
 }

package/frontend-vue/layers/dms-layout/app/build/utils/module-store-install.ts

@@ -0,0 +1,146 @@
+import type {
+  MissingInterface,
+  StoreActionBody,
+  StoreDependencyChoice,
+} from "../../types/module-store";
+
+/**
+ * The radio value of the "Other npm package" choice: not an npm package
+ * name, so no candidate can take it.
+ */
+export const OTHER_PACKAGE_CHOICE = ":other";
+
+/**
+ * An npm package name, scoped or not: never a path, a URL or a git source,
+ * as the store only installs from the registry.
+ */
+const NPM_PACKAGE_PATTERN =
+  /^(?:@[a-z0-9][a-z0-9._~-]*\/)?[a-z0-9][a-z0-9._~-]*$/;
+const NPM_PACKAGE_MAX_LENGTH = 214;
+
+/** What the install dialog holds for one missing interface. */
+export interface DependencyDraft {
+  interfacePackage: string;
+  /** A candidate's package, or {@link OTHER_PACKAGE_CHOICE}. */
+  choice: string;
+  /** The package typed for the "Other npm package" choice. */
+  otherPackage: string;
+  /** The config as typed, JSON; empty means none. */
+  config: string;
+}
+
+/** Why a draft cannot be sent, by field: i18n keys under the dialog's errors. */
+export type DependencyDraftError =
+  | "package_required"
+  | "package_invalid"
+  | "config_invalid";
+
+export interface DependencyDraftErrors {
+  package?: DependencyDraftError;
+  config?: DependencyDraftError;
+}
+
+/** A config as the dialog reads it: absent when left empty. */
+export interface ParsedDependencyConfig {
+  isValid: boolean;
+  config?: Record<string, unknown>;
+}
+
+export function isNpmPackageName(value: string): boolean {
+  return (
+    value.length <= NPM_PACKAGE_MAX_LENGTH && NPM_PACKAGE_PATTERN.test(value)
+  );
+}
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+/** Reads a typed config: empty is no config, anything else a JSON object. */
+export function parseDependencyConfig(text: string): ParsedDependencyConfig {
+  if (!text.trim()) return { isValid: true };
+  try {
+    const value: unknown = JSON.parse(text);
+    return isPlainObject(value)
+      ? { isValid: true, config: value }
+      : { isValid: false };
+  } catch {
+    return { isValid: false };
+  }
+}
+
+/**
+ * One draft per missing interface, the first candidate picked. A draft of
+ * an earlier attempt at the same interface is kept, so a retry starts from
+ * what the owner typed.
+ */
+export function createDependencyDrafts(
+  missing: readonly MissingInterface[],
+  previous: readonly DependencyDraft[] = [],
+): DependencyDraft[] {
+  return missing.map(({ interfacePackage, candidates }) => {
+    const earlier = previous.find(
+      (draft) => draft.interfacePackage === interfacePackage,
+    );
+    if (earlier) return { ...earlier };
+    return {
+      interfacePackage,
+      choice: candidates[0]?.package ?? OTHER_PACKAGE_CHOICE,
+      otherPackage: "",
+      config: "",
+    };
+  });
+}
+
+/** The package a draft installs, as the owner picked or typed it. */
+export function draftPackage(draft: DependencyDraft): string {
+  return draft.choice === OTHER_PACKAGE_CHOICE
+    ? draft.otherPackage.trim()
+    : draft.choice;
+}
+
+function packageError(
+  draft: DependencyDraft,
+): DependencyDraftError | undefined {
+  const packageName = draftPackage(draft);
+  if (!packageName) return "package_required";
+  return isNpmPackageName(packageName) ? undefined : "package_invalid";
+}
+
+export function validateDependencyDraft(
+  draft: DependencyDraft,
+): DependencyDraftErrors {
+  const errors: DependencyDraftErrors = {};
+  const packageProblem = packageError(draft);
+  if (packageProblem) errors.package = packageProblem;
+  if (!parseDependencyConfig(draft.config).isValid) {
+    errors.config = "config_invalid";
+  }
+  return errors;
+}
+
+export function areDependencyDraftsValid(
+  drafts: readonly DependencyDraft[],
+): boolean {
+  return drafts.every(
+    (draft) => Object.keys(validateDependencyDraft(draft)).length === 0,
+  );
+}
+
+function toDependencyChoice(draft: DependencyDraft): StoreDependencyChoice {
+  const { config } = parseDependencyConfig(draft.config);
+  const choice: StoreDependencyChoice = {
+    interfacePackage: draft.interfacePackage,
+    package: draftPackage(draft),
+  };
+  if (config) choice.config = config;
+  return choice;
+}
+
+/** The install request for module `id`, from drafts already validated. */
+export function buildInstallBody(
+  id: string,
+  drafts: readonly DependencyDraft[],
+): StoreActionBody {
+  if (drafts.length === 0) return { id };
+  return { id, dependencies: drafts.map(toDependencyChoice) };
+}

package/frontend-vue/layers/dms-layout/app/composables/page/useModuleStore.ts

@@ -0,0 +1,109 @@
+import type {
+  StoreActionBody,
+  StoreListing,
+  StoreListingEntry,
+  StoreOperationKind,
+} from "../../types/module-store";
+import { isAwaitingFrontend } from "../../build/utils/module-store-catalog";
+
+export const ENDPOINT_STORE_LISTING = "/dms/store/listing";
+const ENDPOINT_STORE_ACTION = "/dms/store";
+/** How often the listing is read while an operation or the frontend runs. */
+const FOLLOW_INTERVAL_MS = 1000;
+
+/**
+ * The module store of the Modules page: the listing, the operations, and the
+ * follow-up that reads the listing again while something moves. An operation
+ * the owner started here reloads the page once the frontend serves its
+ * result, so a new module's pages appear without a manual refresh.
+ */
+export const useModuleStore = () => {
+  // Taken once, in setup: the follow-up reads the listing from a timer,
+  // outside any component context.
+  const { $authFetch } = useAuthFetch();
+  const listing = ref<StoreListing | undefined>(undefined);
+  const loadingError = ref<unknown>(null);
+  /** Modules an operation from this page changed, until the frontend follows. */
+  const awaitingReload = ref(new Set<string>());
+  let followTimer: ReturnType<typeof setTimeout> | undefined;
+
+  const isFollowing = computed(() => {
+    const modules = listing.value?.modules ?? [];
+    return (
+      listing.value?.busy === true ||
+      modules.some((entry) => isAwaitingFrontend(entry))
+    );
+  });
+
+  async function load(): Promise<void> {
+    try {
+      listing.value = await $authFetch<StoreListing>(ENDPOINT_STORE_LISTING);
+      loadingError.value = null;
+    } catch (error) {
+      loadingError.value = error;
+    }
+    reloadWhenServed();
+    scheduleFollow();
+  }
+
+  /**
+   * Reloads the page once every module an operation from here changed is
+   * served by the frontend (or has no interface at all). A frontend that
+   * never reported stays put: the page says what to run instead.
+   */
+  function reloadWhenServed(): void {
+    if (import.meta.env.SSR || awaitingReload.value.size === 0) return;
+    const changed = (listing.value?.modules ?? []).filter((entry) =>
+      awaitingReload.value.has(entry.id),
+    );
+    const isSettled = changed.every(
+      (entry) =>
+        entry.state !== "busy" &&
+        (entry.frontend === "synced" || entry.frontend === "none"),
+    );
+    const needsReload = changed.some((entry) => entry.frontend === "synced");
+    if (!isSettled) return;
+    awaitingReload.value = new Set();
+    if (needsReload) window.location.reload();
+  }
+
+  function scheduleFollow(): void {
+    if (import.meta.env.SSR) return;
+    if (followTimer) clearTimeout(followTimer);
+    followTimer = undefined;
+    if (!isFollowing.value) return;
+    followTimer = setTimeout(() => void load(), FOLLOW_INTERVAL_MS);
+  }
+
+  /**
+   * Starts `kind` on `entry`, with `body` when it carries more than the id;
+   * rejects with the server's answer when refused.
+   */
+  async function run(
+    kind: StoreOperationKind,
+    entry: StoreListingEntry,
+    body: StoreActionBody = { id: entry.id },
+  ): Promise<void> {
+    listing.value = await $authFetch<StoreListing>(
+      `${ENDPOINT_STORE_ACTION}/${kind}`,
+      { method: "POST", body },
+    );
+    awaitingReload.value = new Set([...awaitingReload.value, entry.id]);
+    scheduleFollow();
+  }
+
+  function stop(): void {
+    if (followTimer) clearTimeout(followTimer);
+    followTimer = undefined;
+  }
+
+  return {
+    listing,
+    loadingError,
+    isFollowing,
+    awaitingReload,
+    load,
+    run,
+    stop,
+  };
+};