@stnd/launcher 1.0.0

package/launcher.ts

@@ -0,0 +1,577 @@
+/**
+ * @stnd/launcher - The Universal Command Palette Engine
+ *
+ * Aggregates actions and views from the @stnd module system.
+ * Uses virtual:stnd/components to discover extensions.
+ * Reads app-specific services (user store, search) from the
+ * Standard OS runtime store via provide/inject.
+ */
+import { writable, derived, get } from "svelte/store";
+import { inject, provide } from "@stnd/store";
+import Log from "@stnd/log";
+
+// @ts-ignore - virtual module system
+import { modules } from "virtual:stnd/modules-metadata";
+// @ts-ignore
+import { extensions as componentExtensions } from "virtual:stnd/components";
+// @ts-ignore
+import { runHook } from "virtual:stnd/hooks";
+
+const log = Log({ scope: "Launcher" }) as any;
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+export type ViewTrigger = string;
+export type PromptText = string;
+
+export interface CommandMeta {
+  title: string;
+  desc?: string;
+  type?: "action" | "view";
+  icon?: string;
+  context?: string | string[];
+  requireRole?: string | string[];
+  requireAuth?: boolean;
+  requireGuest?: boolean;
+  size?: { width: string; height: string };
+  hidden?: boolean;
+  override?: boolean;
+}
+
+export interface Command {
+  trigger: string;
+  title: string;
+  desc?: string;
+  type: "action" | "view";
+  icon?: string;
+  context?: string | string[];
+  requireRole?: string | string[];
+  requireAuth?: boolean;
+  requireGuest?: boolean;
+  action?: () => void;
+  component?: any;
+  size?: { width: string; height: string };
+  moduleId?: string;
+  hidden?: boolean;
+}
+
+export interface RegistryState {
+  commands: Command[];
+  views: Record<string, any>;
+}
+
+export interface LauncherResult {
+  title: string;
+  desc?: string;
+  icon?: string;
+  type: "action" | "view" | "search-result" | "command";
+  action?: () => void;
+  url?: string;
+  trigger?: string;
+  id?: string;
+  username?: string;
+  owner_id?: number | null;
+}
+
+export interface PaletteState {
+  open: boolean;
+  view: string;
+  returnTo: string | null;
+  query: string;
+  contexts: string[];
+  props?: any;
+  dynamicSize?: { width: string; height: string } | null;
+}
+
+// =============================================================================
+// STORES
+// =============================================================================
+
+export const registry = writable<RegistryState>({
+  commands: [],
+  views: {},
+});
+
+export const palette = writable<PaletteState>({
+  open: false,
+  view: "search",
+  returnTo: null,
+  query: "",
+  contexts: ["global"],
+});
+
+// App-specific filter (still module-scoped — not worth a store key)
+let appFilter: ((trigger: string, meta: CommandMeta) => boolean) | null = null;
+
+/**
+ * Configure app-specific launcher options without booting.
+ *
+ * Prefer the Standard OS runtime store (provide/inject) for userStore
+ * and searchNotes. This function remains for the filter option and
+ * backward compatibility.
+ */
+export function configureLauncher(
+  options: {
+    searchNotes?: (query: string) => Promise<LauncherResult[]>;
+    userStore?: any;
+    filter?: (trigger: string, meta: CommandMeta) => boolean;
+  } = {},
+) {
+  // Legacy compat: if callers still pass these, push them into the runtime store
+  if (options.searchNotes) provide("search", options.searchNotes);
+  if (options.userStore) provide("user", options.userStore);
+  if (options.filter) appFilter = options.filter;
+}
+
+/**
+ * Initialize the Launcher with app-specific logic and boot immediately.
+ *
+ * Shorthand for `configureLauncher(options)` + `bootLauncher()`.
+ */
+export function initLauncher(
+  options: {
+    searchNotes?: (query: string) => Promise<LauncherResult[]>;
+    userStore?: any;
+    filter?: (trigger: string, meta: CommandMeta) => boolean;
+  } = {},
+) {
+  configureLauncher(options);
+
+  // Initial registry boot
+  bootLauncher();
+}
+
+// =============================================================================
+// CORE ENGINE
+// =============================================================================
+
+/**
+ * Register a command or view in the launcher
+ */
+export function register(
+  trigger: string,
+  meta: CommandMeta & { moduleId?: string },
+  handler: (() => void) | any,
+) {
+  // Apply global filter if set
+  if (appFilter && !appFilter(trigger, meta)) {
+    return;
+  }
+
+  registry.update((r) => {
+    // Check for collisions in existing commands
+    const existingIndex = r.commands.findIndex((c) => c.trigger === trigger);
+    if (existingIndex !== -1 && !meta.override) {
+      const errorMsg =
+        `[Launcher] Fatal Collision: Trigger "${trigger}" already registered by "${r.commands[existingIndex].moduleId || "core"}". ` +
+        `Attempting to register again from "${meta.moduleId || "unknown"}". ` +
+        `See: https://stnd.build/manual/5-reference/launcher-trigger-collision`;
+      log.error(errorMsg);
+      throw new Error(errorMsg);
+    }
+
+    const m = meta as any;
+    let updates: any = { ...r };
+
+    // Register as view if type is "view"
+    if (m.type === "view") {
+      updates.views = { ...r.views, [trigger]: handler };
+    }
+
+    // Create a command (either for actions or for views as launcher shortcuts)
+    const cmd: Command = {
+      trigger,
+      title: m.title,
+      desc: m.desc,
+      type: m.type === "view" ? "view" : "action",
+      icon: m.icon,
+      context: m.context,
+      requireRole: m.requireRole,
+      requireAuth: m.requireAuth,
+      requireGuest: m.requireGuest,
+      size: m.size,
+      action: m.type === "view" ? () => launcherView(trigger) : handler,
+      component: m.type === "view" ? handler : undefined,
+      moduleId: meta.moduleId || "core",
+      hidden: m.hidden,
+    };
+
+    if (existingIndex !== -1 && meta.override) {
+      updates.commands = [...r.commands];
+      updates.commands[existingIndex] = cmd;
+    } else {
+      updates.commands = [...r.commands, cmd];
+    }
+
+    return updates;
+  });
+}
+
+/**
+ * Boot the Launcher system by collecting extensions from the module system
+ */
+export async function bootLauncher() {
+  // 1. Clear registry
+  registry.set({ commands: [], views: {} });
+
+  // 2. Load Actions from extensions
+  const actions = componentExtensions?.["launcher:action"] || [];
+  actions.forEach((entry: any) => {
+    if (!entry) return;
+
+    // Support both single action and bundled actions
+    let actionSource = entry.actions || entry.action?.actions || entry.action;
+
+    // Handle Module Namespace (default export)
+    if (
+      actionSource &&
+      typeof actionSource === "object" &&
+      "default" in actionSource
+    ) {
+      actionSource = actionSource.default;
+    }
+
+    const bundledActions = Array.isArray(actionSource) ? actionSource : null;
+
+    if (Array.isArray(bundledActions)) {
+      bundledActions.forEach((item: any) => {
+        if (!item?.trigger || typeof item.action !== "function") return;
+        register(
+          item.trigger,
+          {
+            ...(entry.meta || {}),
+            ...(item.meta || {}),
+            type: "action",
+            moduleId: entry.moduleId,
+          },
+          item.action,
+        );
+      });
+    } else if (entry.trigger && typeof entry.action === "function") {
+      register(
+        entry.trigger,
+        { ...(entry.meta || {}), type: "action", moduleId: entry.moduleId },
+        entry.action,
+      );
+    }
+  });
+
+  // 3. Load Views from extensions
+  const views = componentExtensions?.["launcher:view"] || [];
+  views.forEach((entry: any) => {
+    if (entry.trigger && entry.component) {
+      register(
+        entry.trigger,
+        { ...entry.meta, type: "view", moduleId: entry.moduleId },
+        entry.component,
+      );
+    }
+  });
+
+  // 4. Load Themes from modules metadata
+  const themeModules = (modules || []).filter(
+    (m: any) => m?.meta?.type === "theme",
+  );
+  themeModules.forEach((m: any) => {
+    const themeId = m.meta.themeId || m.id.replace("theme-", "");
+    register(
+      `::theme ${themeId}`,
+      {
+        title: m.meta.label || m.name || themeId,
+        type: "action",
+        icon: "palette",
+        desc: m.description || "A custom theme.",
+        moduleId: m.id,
+      },
+      async () => {
+        document.documentElement.setAttribute("data-theme", themeId);
+        if (typeof localStorage !== "undefined")
+          localStorage.setItem("std_theme", themeId);
+
+        // Persistence Tier: Save to preferences (Session/DB)
+        try {
+          const save = inject("savePreference");
+          if (typeof save === "function") {
+            await save({ theme: themeId });
+          }
+        } catch (e) {
+          log.debug("No preference saver available, theme saved locally only");
+        }
+      },
+    );
+  });
+
+  // 5. Load Content entries (via hook)
+  try {
+    const contentResults = await runHook("stnd:launcher:content:register");
+    const allEntries = contentResults?.flat().filter(Boolean) || [];
+    // Deduplicate by id (runHook may call the same handler multiple times)
+    const seen = new Set();
+    const entries = allEntries.filter((entry: any) => {
+      if (!entry.id || seen.has(entry.id)) return false;
+      seen.add(entry.id);
+      return true;
+    });
+    entries.forEach((entry: any) => {
+      if (!entry.url) return;
+      const contentType = entry.type || "page";
+      register(
+        `::go ${contentType} ${entry.id}`,
+        {
+          title: entry.title,
+          type: "action",
+          icon: entry.icon || "note",
+          desc: entry.desc || "",
+          moduleId: entry.moduleId || "core:content",
+        },
+        () => {
+          import("astro:transitions/client").then((m) => m.navigate(entry.url));
+        },
+      );
+    });
+    if (entries.length)
+      log.debug(`Registered ${entries.length} content entries`);
+  } catch (e) {
+    log.debug("No content entries discovered via hook");
+  }
+
+  log.debug("Initialized");
+}
+
+// =============================================================================
+// SEARCH & MATCHING
+// =============================================================================
+
+export async function search(query: string): Promise<LauncherResult[]> {
+  const searchFn = inject("search", async () => []);
+  return searchFn(query);
+}
+
+export function computeMatches(
+  query: string,
+  registryCommands: Command[],
+  searchResults: LauncherResult[],
+  currentUser: any,
+): LauncherResult[] {
+  const isCommand = query.startsWith("::");
+  const contextualCommands = registryCommands.filter((cmd) => {
+    // 0. Filtrage de l'état d'authentification (l'utilisateur anonyme n'est pas authentifié)
+    const isAuthenticated =
+      currentUser?.isAuthenticated === true ||
+      (!!currentUser?.id &&
+        currentUser?.id !== "anonymous-system-user" &&
+        !currentUser?.isAnonymous);
+    if (cmd.requireAuth && !isAuthenticated) return false;
+    if (cmd.requireGuest && isAuthenticated) return false;
+
+    // 1. Role filtering
+    if (cmd.requireRole) {
+      if (!isAuthenticated) return false;
+      const roles = Array.isArray(cmd.requireRole)
+        ? cmd.requireRole
+        : [cmd.requireRole];
+      if (!roles.includes(currentUser.role)) return false;
+    }
+
+    // 2. Context filtering
+    // If command defines a context, the palette must have it.
+    // context: "note" means palette.contexts must contain "note"
+    // context: ["note", "owner"] means palette.contexts must contain BOTH "note" and "owner"
+    if (cmd.context) {
+      const activeContexts = get(palette).contexts || [];
+      const requiredContexts = Array.isArray(cmd.context)
+        ? cmd.context
+        : [cmd.context];
+
+      // Every required context must be present in active contexts
+      const hasRequiredContexts = requiredContexts.every((c) =>
+        activeContexts.includes(c),
+      );
+      if (!hasRequiredContexts) return false;
+    }
+
+    return true;
+  });
+
+  if (isCommand) {
+    const searchTerm = query.replace(/^::/, "").toLowerCase();
+    return contextualCommands
+      .filter((c) => {
+        if (c.hidden && !searchTerm) return false;
+        return c.trigger.replace(/^::/, "").toLowerCase().includes(searchTerm);
+      })
+      .map((c) => ({ ...c }));
+  }
+
+  // Regular search
+  const matches = contextualCommands
+    .filter((c) => {
+      if (c.hidden) return false;
+      return c.title.toLowerCase().includes(query.toLowerCase());
+    })
+    .map((c) => ({ ...c }));
+
+  const finalMatches = [...matches, ...searchResults];
+
+  // Si une requête de recherche textuelle est saisie, injecter l'option de poser une question à l'IA du jardin
+  if (query.trim() && !isCommand) {
+    const aiPromptItem: LauncherResult = {
+      title: "Demander à l'IA du Jardin",
+      desc: `Obtenir une réponse basée sur vos notes pour : "${query}"`,
+      icon: "ph:sparkle",
+      type: "view",
+      trigger: "::ask",
+      action: () => launcherView("::ask", { question: query }),
+    };
+    // Placer l'option IA en premier
+    finalMatches.unshift(aiPromptItem);
+  }
+
+  return finalMatches;
+}
+
+export const activeView = derived(
+  [registry, palette],
+  ([$registry, $palette]) => {
+    return $registry.views[$palette.view] || null;
+  },
+);
+
+export const windowSize = derived(
+  [registry, palette, activeView],
+  ([$registry, $palette, $activeView]) => {
+    // 1. Dynamic Override
+    if ($palette.dynamicSize) return $palette.dynamicSize;
+
+    // 2. Registry Size
+    if ($activeView) {
+      const cmd = $registry.commands.find(
+        (c) => c.action === $activeView || c.trigger === $palette.view,
+      );
+      // Note: The registry commands might store the view component in a different property depending on how it was registered
+      // In register(): if type=view, it goes to r.views. We don't necessarily keep a ref in r.commands to the component function easily?
+      // Let's check register()...
+      // It creates a command with 'action: handler'. handler IS the component for view types.
+      // So checking c.action === $activeView should work.
+      if (cmd) {
+        return (
+          cmd.size ||
+          (cmd as any).meta?.size || { width: "standard", height: "standard" }
+        );
+      }
+    }
+
+    // 3. Default
+    return { width: "standard", height: "standard" };
+  },
+);
+
+// =============================================================================
+// API
+// =============================================================================
+
+export function launcherToggle(query: string = "") {
+  palette.update((p) => {
+    const willBeOpen = !p.open;
+    return {
+      ...p,
+      open: willBeOpen,
+      query,
+      view: willBeOpen ? "search" : p.view,
+    };
+  });
+}
+
+export function launcherView(view: string, props: any = {}) {
+  palette.update((p) => ({
+    ...p,
+    open: true,
+    view,
+    query: "",
+    props,
+    dynamicSize: null,
+  }));
+}
+
+export function setSize(size: { width: string; height: string } | null) {
+  palette.update((p) => ({ ...p, dynamicSize: size }));
+}
+
+export function setContexts(contexts: string[]) {
+  palette.update((p) => ({ ...p, contexts }));
+}
+
+export function launcherClose() {
+  palette.update((p) => ({ ...p, open: false }));
+}
+
+export function execute(item: LauncherResult) {
+  if (item.action) {
+    item.action();
+    // Don't close launcher for view commands - they handle their own state
+    if (item.type !== "view") {
+      launcherClose();
+    }
+  } else if (item.url) {
+    import("astro:transitions/client").then((m) =>
+      m.navigate(item.url as string),
+    );
+    launcherClose();
+  } else if (item.trigger) {
+    if (item.trigger.startsWith("::")) {
+      launcherView(item.trigger);
+    }
+  }
+}
+export function getPageState(user: any = null): any {
+  if (typeof window === "undefined") {
+    return { contexts: ["global"] };
+  }
+
+  const path = window.location.pathname;
+  const state: any = {
+    contexts: ["global"],
+    noteSlug: null,
+  };
+
+  if (path.startsWith("/writer") || path.startsWith("/editor")) {
+    state.contexts.push("editor");
+    return state;
+  }
+
+  // Common pattern for notes
+  const noteMatch = path.match(/^\/([^/]+)$/);
+  if (noteMatch) {
+    state.contexts.push("note");
+    state.noteSlug = noteMatch[1];
+  }
+
+  if (path === "/") {
+    state.contexts.push("home");
+  }
+  return state;
+}
+
+/**
+ * Svelte Action: openLauncher
+ * usage: <button use:openLauncher={"::trigger"}>Open</button>
+ */
+export function openLauncher(node: HTMLElement, trigger: string = "") {
+  function handleClick(e: MouseEvent) {
+    e.preventDefault();
+    if (trigger.startsWith("::")) {
+      launcherView(trigger);
+    } else {
+      launcherToggle(trigger);
+    }
+  }
+
+  node.addEventListener("click", handleClick);
+  return {
+    destroy() {
+      node.removeEventListener("click", handleClick);
+    },
+  };
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@stnd/launcher",
+  "version": "1.0.0",
+  "type": "module",
+  "svelte": "./Launcher.svelte",
+  "main": "launcher.ts",
+  "exports": {
+    ".": {
+      "svelte": "./Launcher.svelte",
+      "default": "./launcher.ts"
+    },
+    "./launcher": "./launcher.ts",
+    "./Launcher.svelte": "./Launcher.svelte",
+    "./transitions": "./transitions.js",
+    "./*": "./*"
+  },
+  "dependencies": {
+    "svelte": "5.56.4",
+    "wrangler": "^4.105.0",
+    "@stnd/icon": "0.2.0",
+    "@stnd/log": "0.5.0",
+    "@stnd/store": "0.5.0"
+  },
+  "peerDependencies": {
+    "astro": ">=5.0.0"
+  }
+}