@sirenodeck/sirenodeck 0.1.1-alpha.0

package/src/deck/methods.ts

@@ -0,0 +1,348 @@
+import type pino from "pino"
+
+import type { PubSub } from "@/core/pub-sub"
+import type { Store } from "@/core/store"
+import type { KeyMacroProvider } from "@/system/providers/key-macro"
+import type {
+  NotificationArgs,
+  NotificationProvider,
+} from "@/system/providers/notification"
+import {
+  type RequirementsCheckResult,
+  type SystemCapability,
+} from "@/system/requirements"
+import {
+  isValidKey,
+  knownKeys,
+  parseCombo,
+  type ParsedCombo,
+} from "@/system/providers/key-macro/parser"
+import { NotImplementedError } from "@/util/errors"
+
+import type { ActionExecutor, ActionExecutorOptions } from "@/action/executor"
+import type { Runtime, RuntimeDeck } from "./runtime"
+import { dispatchMacro, resolvePlatformMacro } from "./macro-parse"
+
+const DEFAULT_BUTTON_ERROR_DURATION_MS = 5000
+
+export interface KeyMacroAction {
+  kind: "key" | "combo" | "text"
+  value: string
+  modifiers?: ReadonlyArray<"shift" | "ctrl" | "alt" | "meta" | "cmd">
+}
+
+export interface MethodsContext {
+  runtime: Runtime
+  pubSub: PubSub
+  store: Store
+  executor: ActionExecutor
+  logger: pino.Logger
+  keyMacroProvider?: KeyMacroProvider
+  notificationProvider?: NotificationProvider
+}
+
+export interface Methods {
+  runCommand(
+    command: string,
+    options?: ActionExecutorOptions,
+  ): Promise<{
+    stdout: string
+    stderr: string
+    exitCode: number
+    durationMs: number
+  }>
+  /**
+   * Send a key or combo via the key-macro provider. Equivalent to the OS-level
+   * keystroke — Linux uses `wtype`, macOS uses `osascript keystroke`, Windows
+   * uses Win32 `SendInput`. Accepts both combos (`ctrl+shift+t`) and plain
+   * UTF-8 text (including emoji).
+   */
+  keyMacro(action: KeyMacroAction): Promise<void>
+  /**
+   * Convenience wrapper for addons that want to type literal text without
+   * constructing a `KeyMacroAction`. Passes straight through to the
+   * key-macro provider; the provider is responsible for the actual keystroke
+   * injection, so UTF-8 / emoji work everywhere a key-macro tool is
+   * available.
+   */
+  typeText(text: string): Promise<void>
+  navigateToDeck(args: { id: string; addToHistory?: boolean }): void
+  goBack(): void
+  getActiveDeckId(): string
+  invalidate(): void
+  publish<T>(channel: string, payload: T): void
+  subscribe<T>(channel: string, cb: (payload: T) => void): () => void
+  setKeyMacroProvider(provider: KeyMacroProvider): void
+  /**
+   * Fire an OS notification. Falls back to a no-op (logged at warn) when no
+   * notification provider is configured for this platform. Used by addons
+   * via `coreMethods.notify`.
+   */
+  notify(args: NotificationArgs): Promise<void>
+  setNotificationProvider(provider: NotificationProvider): void
+  setRequirements(requirements: RequirementsCheckResult): void
+  checkRequirement(capability: SystemCapability): boolean
+  showTemporaryError(
+    deckId: string,
+    position: number,
+    durationMs?: number,
+    buttonId?: string,
+    details?: string,
+  ): void
+  adjustBrightness(args: { direction: "up" | "down" }): void
+  dispatch(value: string): Promise<void>
+  /**
+   * Ask the host to re-materialize the addon decks (used when a dynamic deck's
+   * shape depends on live state, e.g. session counts). The host replaces the
+   * runtime deck set and rebroadcasts deck-config. Set via `setDeckRebuilder`.
+   */
+  requestDeckRebuild(): void
+  setDeckRebuilder(rebuild: () => void): void
+}
+
+export const createMethods = (ctx: MethodsContext): Methods => {
+  let keyMacroProvider: KeyMacroProvider | undefined = ctx.keyMacroProvider
+  let notificationProvider: NotificationProvider | undefined =
+    ctx.notificationProvider
+  const logger = ctx.logger.child({ component: "methods" })
+  const setKeyMacroProvider: Methods["setKeyMacroProvider"] = (provider) => {
+    keyMacroProvider = provider
+  }
+  const setNotificationProvider: Methods["setNotificationProvider"] = (
+    provider,
+  ) => {
+    notificationProvider = provider
+  }
+  const notify: Methods["notify"] = async (args) => {
+    if (notificationProvider === undefined) {
+      logger.warn(
+        { title: args.title },
+        "methods.notify: no notification provider configured; skipping",
+      )
+      return
+    }
+    await notificationProvider.notify(args)
+  }
+
+  let requirements: RequirementsCheckResult | undefined = undefined
+  let deckRebuilder: (() => void) | undefined
+  const setDeckRebuilder: Methods["setDeckRebuilder"] = (rebuild) => {
+    deckRebuilder = rebuild
+  }
+  const requestDeckRebuild: Methods["requestDeckRebuild"] = () => {
+    if (deckRebuilder === undefined) {
+      logger.warn(
+        "methods.requestDeckRebuild: no deck rebuilder wired; skipping",
+      )
+      return
+    }
+    deckRebuilder()
+  }
+  const setRequirements: Methods["setRequirements"] = (value) => {
+    requirements = value
+  }
+  const checkRequirement: Methods["checkRequirement"] = (capability) => {
+    if (requirements === undefined) return true
+    return requirements[capability]?.available ?? true
+  }
+  const showTemporaryError: Methods["showTemporaryError"] = (
+    deckId,
+    position,
+    durationMs = DEFAULT_BUTTON_ERROR_DURATION_MS,
+    buttonId,
+    details,
+  ) => {
+    ctx.pubSub.publish("runtime:buttonError", {
+      deckId,
+      position,
+      durationMs,
+      ...(buttonId !== undefined ? { buttonId } : {}),
+      ...(details !== undefined ? { details } : {}),
+    })
+  }
+
+  const adjustBrightness: Methods["adjustBrightness"] = ({ direction }) => {
+    const step = 10
+    const current = ctx.runtime.getBrightness()
+    const raw = direction === "up" ? current + step : current - step
+    const next = Math.max(10, Math.min(100, Math.round(raw)))
+    if (next === current) return
+    ctx.runtime.setBrightness(next)
+    ctx.pubSub.publish("methods:adjustBrightness", { direction, value: next })
+  }
+
+  const navigateToDeck: Methods["navigateToDeck"] = (args) => {
+    ctx.runtime.navigateToDeck(args.id, { addToHistory: args.addToHistory })
+  }
+
+  const goBack: Methods["goBack"] = () => {
+    ctx.runtime.goBack()
+  }
+
+  const getActiveDeckId: Methods["getActiveDeckId"] = () => {
+    return ctx.runtime.getActiveDeckId()
+  }
+
+  const invalidate: Methods["invalidate"] = () => {
+    ctx.runtime.invalidate()
+  }
+
+  const publish: Methods["publish"] = <T>(channel: string, payload: T) => {
+    ctx.pubSub.publish<T>(channel, payload)
+  }
+
+  const subscribe: Methods["subscribe"] = <T>(
+    channel: string,
+    cb: (payload: T) => void,
+  ) => {
+    return ctx.pubSub.subscribe<T>(channel, cb)
+  }
+
+  const runCommand: Methods["runCommand"] = async (command, options) => {
+    return await ctx.executor.run(command, options)
+  }
+
+  const keyMacro: Methods["keyMacro"] = async (action) => {
+    if (keyMacroProvider === undefined) {
+      throw new NotImplementedError(
+        "methods.keyMacro requires a keyMacroProvider (set via methods.setKeyMacroProvider)",
+      )
+    }
+    if (action.kind === "text") {
+      await keyMacroProvider.sendKey(action.value)
+      return
+    }
+    if (action.kind === "key") {
+      if (!isValidKey(action.value)) {
+        throw new NotImplementedError(
+          `methods.keyMacro: unknown key '${action.value}'. Valid keys: ${[...knownKeys].join(", ")}`,
+        )
+      }
+      await keyMacroProvider.sendKey(action.value)
+      return
+    }
+    const parsed: ParsedCombo | null = parseCombo(action.value)
+    if (parsed === null) {
+      throw new NotImplementedError(
+        `methods.keyMacro: invalid combo '${action.value}'`,
+      )
+    }
+    const combo =
+      parsed.mods.length > 0
+        ? `${parsed.mods.join("+")}+${parsed.key}`
+        : parsed.key
+    await keyMacroProvider.sendKey(combo)
+  }
+
+  const typeText: Methods["typeText"] = async (text) => {
+    if (keyMacroProvider === undefined) {
+      throw new NotImplementedError(
+        "methods.typeText requires a keyMacroProvider (set via methods.setKeyMacroProvider)",
+      )
+    }
+    await keyMacroProvider.sendKey(text)
+  }
+
+  const dispatch: Methods["dispatch"] = async (value) => {
+    if (value.startsWith("type://")) {
+      const text = value.slice("type://".length)
+      if (text.length === 0) {
+        throw new NotImplementedError(
+          "dispatch: type:// requires a value, e.g. type://hello",
+        )
+      }
+      await keyMacro({ kind: "text", value: text })
+      return
+    }
+    if (value.startsWith("macro://")) {
+      const inner = value.slice("macro://".length)
+      if (inner.length === 0) {
+        throw new NotImplementedError(
+          "dispatch: macro:// requires a value, e.g. macro://ctrl+c",
+        )
+      }
+      let macro: string
+      if (inner.startsWith("{")) {
+        let parsed: unknown
+        try {
+          parsed = JSON.parse(inner)
+        } catch {
+          throw new NotImplementedError(
+            "dispatch: macro://{...} payload is not valid JSON",
+          )
+        }
+        if (typeof parsed !== "object" || parsed === null) {
+          throw new NotImplementedError(
+            "dispatch: macro://{...} payload must be a JSON object",
+          )
+        }
+        const variants = parsed as Record<string, unknown>
+        const platKey =
+          process.platform === "darwin"
+            ? "osx"
+            : process.platform === "win32"
+              ? "windows"
+              : "linux"
+        const pick =
+          typeof variants[platKey] === "string"
+            ? (variants[platKey] as string)
+            : typeof variants.all === "string"
+              ? (variants.all as string)
+              : undefined
+        if (pick === undefined || pick.length === 0) {
+          throw new NotImplementedError(
+            `dispatch: macro://{...} has no value for platform '${process.platform}' and no 'all' fallback`,
+          )
+        }
+        macro = pick
+      } else {
+        // `[macos:cmd+c]ctrl+c` — per-OS overrides with a mandatory default.
+        // Plain macros contain no leading bracket and fall straight through.
+        try {
+          macro = resolvePlatformMacro(inner)
+        } catch (error) {
+          throw new NotImplementedError(
+            `dispatch: ${error instanceof Error ? error.message : String(error)}`,
+          )
+        }
+      }
+      await dispatchMacro(macro, { runCommand, keyMacro })
+      return
+    }
+    if (value.startsWith("brightness://")) {
+      const inner = value.slice("brightness://".length)
+      if (inner === "up" || inner === "down") {
+        adjustBrightness({ direction: inner })
+        return
+      }
+      throw new NotImplementedError(
+        `dispatch: brightness:// requires up/down, got '${inner}'`,
+      )
+    }
+    await runCommand(value)
+  }
+
+  return {
+    runCommand,
+    keyMacro,
+    typeText,
+    dispatch,
+    navigateToDeck,
+    goBack,
+    getActiveDeckId,
+    invalidate,
+    publish,
+    subscribe,
+    setKeyMacroProvider,
+    setNotificationProvider,
+    notify,
+    setRequirements,
+    checkRequirement,
+    showTemporaryError,
+    adjustBrightness,
+    requestDeckRebuild,
+    setDeckRebuilder,
+  }
+}
+
+export const deckFromRuntimeDeck = (deck: RuntimeDeck) => deck

package/src/deck/paginate-deck.ts

@@ -0,0 +1,98 @@
+import type { AddonGeneratedDeck } from "@/addon/api"
+import {
+  NEXT_PAGE_MARKER,
+  type NextPageMarker,
+  paginate,
+} from "@/core/pagination"
+
+export interface PageDeckResult {
+  readonly deckId: string
+  readonly pageIndex: number
+  readonly totalPages: number
+  readonly deck: AddonGeneratedDeck
+}
+
+export interface PaginateDeckOptions {
+  readonly baseDeckId: string
+  readonly buttons: readonly unknown[]
+  readonly keyCount: number
+}
+
+const PAGE_NAV_BUTTON_TYPE = "core:page-nav"
+
+const isNextPageMarker = (
+  item: { id: string; value: unknown } | null,
+): item is { id: NextPageMarker; value: unknown } =>
+  item !== null && item.value === NEXT_PAGE_MARKER
+
+export const paginateDeck = (opts: PaginateDeckOptions): PageDeckResult[] => {
+  const { baseDeckId, buttons, keyCount } = opts
+
+  const result = paginate(buttons, { keyCount })
+  if (result.pages.length === 0) {
+    return []
+  }
+
+  const pageNavPosition = keyCount - 2
+
+  return result.pages.map((page, pageIndex) => {
+    const isFirstPage = pageIndex === 0
+    const isLastPage = pageIndex === result.pages.length - 1
+    const totalPages = result.pages.length
+    const deckId =
+      totalPages === 1 ? baseDeckId : `${baseDeckId}-p${pageIndex + 1}`
+
+    const deckButtons: unknown[] = []
+
+    for (const item of page.items) {
+      if (isNextPageMarker(item)) {
+        // ponytail: keep page-nav targets inside the page set. The base deck
+        // id (e.g. chrome-overlay:shortcuts) is NOT a runtime deck (the pages
+        // are -p1, -p2, -p3); navigating to it would no-op. First page's
+        // prev and last page's next target the current page (no-op), so the
+        // entry/exit to the overlay is via core:overlay-toggle only.
+        const prevDeckId = isFirstPage ? deckId : `${baseDeckId}-p${pageIndex}`
+        const nextDeckId = isLastPage
+          ? deckId
+          : `${baseDeckId}-p${pageIndex + 2}`
+
+        for (let i = deckButtons.length - 1; i >= 0; i--) {
+          const existing = deckButtons[i] as Record<string, unknown>
+          if (existing?.position === pageNavPosition) {
+            deckButtons.splice(i, 1)
+          }
+        }
+        deckButtons.push({
+          id: `${pageNavPosition}-${baseDeckId}-${pageIndex}`,
+          type: PAGE_NAV_BUTTON_TYPE,
+          position: pageNavPosition,
+          config: {
+            currentPage: pageIndex + 1,
+            totalPages,
+            prevDeckId,
+            nextDeckId,
+          },
+        })
+      } else if (item !== null) {
+        // ponytail: emit each page-deck with LOCAL slot positions 0..N-1,
+        // not the global page * (K-2) + slot encoding. The frontend renders
+        // a fixed K-key grid per page; n-1 (sysBack) and n-2 (pageNav) are
+        // reserved on every page independently.
+        const slot = Number(item.id.split("-").pop() ?? "0")
+        deckButtons.push({
+          ...(item.value as Record<string, unknown>),
+          position: slot,
+        })
+      }
+    }
+
+    return {
+      deckId,
+      pageIndex,
+      totalPages,
+      deck: {
+        buttons: deckButtons,
+      },
+    }
+  })
+}

package/src/deck/position-buttons.ts

@@ -0,0 +1,57 @@
+import type pino from "pino"
+
+/**
+ * Assigns a position to every button — no drops.
+ *
+ * - Buttons with a valid explicit `position` keep it (first-come wins
+ *   for duplicates).
+ * - Duplicate positions and buttons without a position fall through to
+ *   a "gap" queue, filled sequentially starting at 0 in array order.
+ * - Positions ≥ keyCount are preserved: the caller is responsible for
+ *   pagination (group by `floor(pos / (K-2))`). The deck-config and
+ *   addon-deck pipelines both go through `paginateDeck` for that.
+ * - The internal contract: every emitted button has `position` set.
+ *
+ * ponytail: O(n²) scan is fine for deck sizes (<30).
+ */
+export const positionButtons = <T extends { position?: number }>(
+  buttons: readonly T[],
+  keyCount: number,
+  logger?: pino.Logger,
+): T[] => {
+  const occupied = new Set<number>()
+  const result: T[] = []
+  const unfixed: T[] = []
+
+  for (const btn of buttons) {
+    const pos = btn.position
+    if (pos === undefined || !Number.isFinite(pos) || pos < 0) {
+      unfixed.push(btn)
+      continue
+    }
+    // ponytail: positions ≥ keyCount are preserved as deck-global ordering
+    // hints. Pagination groups them via floor(pos / (K-2)); the deck-config
+    // pipeline runs paginateDeck before the frontend serializes per-page
+    // slot positions.
+    if (occupied.has(pos)) {
+      logger?.debug(
+        { position: pos, reason: "duplicate" },
+        "duplicate position, treating as unfixed",
+      )
+      unfixed.push(btn)
+      continue
+    }
+    occupied.add(pos)
+    result.push(btn)
+  }
+
+  let gap = 0
+  for (const btn of unfixed) {
+    while (occupied.has(gap)) gap++
+    occupied.add(gap)
+    result.push({ ...btn, position: gap } as T)
+    gap++
+  }
+
+  return result
+}

package/src/deck/runtime/index.ts

@@ -0,0 +1,5 @@
+// ponytail: re-export so `import ... from "./runtime"` resolves to
+// this directory via the standard `./runtime/index.{ts,tsx}` lookup.
+// Without this, `moduleResolution: bundler` falls back to
+// `./runtime/index.json` and crashes the daemon with ERR_MODULE_NOT_FOUND.
+export * from "./runtime"