@sirenodeck/sirenodeck 0.1.1-alpha.0

package/src/addon/loader.ts

@@ -0,0 +1,441 @@
+import { existsSync, readFileSync } from "node:fs"
+import { resolve as resolvePath, join } from "node:path"
+import { pathToFileURL } from "node:url"
+
+import { addonNpmRoot } from "@/util/cache-paths"
+
+import type {
+  AddonJsonManifest,
+  AddonLoadIssue,
+  AddonManifestV1,
+  LoadedTheme,
+} from "./api"
+import type { RawAddonEntry } from "@/config/schemas"
+import {
+  addonRootExists,
+  isLocalAddonSpec,
+  isNpmAddonSpec,
+  normalizeAddonEntry,
+  resolveLocalAddonRoot,
+} from "./spec"
+
+export interface LoadAddonsOptions {
+  entries: RawAddonEntry[]
+  configDir: string
+  homeDir: string
+  currentApiVersion: number
+  cacheDir?: string
+  projectDir?: string
+  globalPackageRoots?: ReadonlyArray<string>
+}
+
+export interface ResolvedExternalAddon {
+  manifest: AddonManifestV1
+  source: { kind: "local" | "npm"; specifier: string; resolvedPath: string }
+  // ponytail: resolved module path the bridge should import to load this
+  // addon's frontend + globalService. Same file exports both; one path
+  // serves both import slots.
+  entryPath: string
+  // ponytail: when the manifest declares `frontendEntry`, the BROWSER loads
+  // this instead of `entryPath`. The Node bundle has the host's UI primitives
+  // stubbed out (Node cannot import the host's .tsx sources), so rendering it
+  // in the browser draws those components as nothing. Null when the addon
+  // ships a single bundle, in which case callers fall back to entryPath.
+  browserEntryPath: string | null
+}
+
+export interface LoadAddonsResult {
+  addons: ResolvedExternalAddon[]
+  themes: LoadedTheme[]
+  issues: AddonLoadIssue[]
+}
+
+const recordIssue = (issues: AddonLoadIssue[], issue: AddonLoadIssue): void => {
+  issues.push(issue)
+}
+
+const importAddonModule = async (resolvedPath: string): Promise<unknown> => {
+  const url = pathToFileURL(resolvedPath).href
+  return import(url)
+}
+
+const readJsonManifest = (root: string): AddonJsonManifest | null => {
+  const manifestPath = join(root, "sirenodeck.json")
+  if (!existsSync(manifestPath)) return null
+  let raw: unknown
+  try {
+    raw = JSON.parse(readFileSync(manifestPath, "utf8")) as unknown
+  } catch {
+    return null
+  }
+  if (raw === null || typeof raw !== "object") return null
+  const obj = raw as Record<string, unknown>
+  if (obj["apiVersion"] !== 1) return null
+  const kind = obj["kind"]
+  if (kind !== "addon" && kind !== "theme") return null
+  const name = obj["name"]
+  const entry = obj["entry"]
+  if (typeof name !== "string" || typeof entry !== "string") return null
+  // Optional; ignored entirely when absent, so older manifests are unaffected.
+  const frontendEntry = obj["frontendEntry"]
+  return {
+    kind,
+    apiVersion: 1,
+    name,
+    entry,
+    ...(typeof frontendEntry === "string" && frontendEntry.length > 0
+      ? { frontendEntry }
+      : {}),
+  }
+}
+
+// ponytail: resolve the manifest's optional `frontendEntry` against the addon
+// root. Returns null when the field is absent OR the file is missing, so a
+// stale manifest degrades to the single-bundle behaviour instead of handing
+// the browser a path that 404s.
+const resolveBrowserEntry = (
+  root: string,
+  json: AddonJsonManifest,
+): string | null => {
+  if (json.frontendEntry === undefined) return null
+  const candidate = join(root, json.frontendEntry)
+  return existsSync(candidate) ? candidate : null
+}
+
+const resolveEntryPaths = (
+  root: string,
+  json: AddonJsonManifest,
+): { ts: string; js: string } => {
+  const entryExt = json.entry
+  const extTs = entryExt.endsWith(".ts")
+    ? join(root, entryExt)
+    : join(root, `${entryExt}.ts`)
+  const extJs = join(root, entryExt)
+  return { ts: extTs, js: extJs }
+}
+
+// ponytail: ESM-CJS interop wraps CJS exports as `mod.default`, and some
+// addons also wrap the manifest under a named key (e.g. chrome-overlay uses
+// `module.exports = { manifest: {...} }`). Some combine both: the CJS wrapper
+// becomes `mod.default`, then chrome-overlay's `.manifest` lives one level
+// down. Walk at most two levels deep — never deeper, to avoid accidental
+// infinite recursion on hostile modules.
+const unwrapManifestExport = (mod: unknown): unknown => {
+  let cur: unknown = mod
+  for (let i = 0; i < 2; i += 1) {
+    if (cur === null || typeof cur !== "object") return cur
+    const rec = cur as Record<string, unknown>
+    const candidate = rec["manifest"] ?? rec["default"]
+    if (
+      candidate !== undefined &&
+      typeof candidate === "object" &&
+      candidate !== null &&
+      typeof (candidate as Record<string, unknown>)["apiVersion"] ===
+        "number" &&
+      typeof (candidate as Record<string, unknown>)["name"] === "string"
+    ) {
+      return candidate
+    }
+    if (candidate !== undefined) {
+      cur = candidate
+      continue
+    }
+    return cur
+  }
+  return cur
+}
+
+const validateAndLoadEntry = async (
+  source: string,
+  tsPath: string,
+  jsPath: string,
+  issues: AddonLoadIssue[],
+): Promise<{ manifest: AddonManifestV1; entryPath: string } | null> => {
+  const candidatePath = existsSync(tsPath) ? tsPath : jsPath
+  if (!existsSync(candidatePath)) {
+    recordIssue(issues, {
+      level: "error",
+      source,
+      message: `Entry file not found: tried ${tsPath} and ${jsPath}`,
+    })
+    return null
+  }
+  let mod: unknown
+  try {
+    mod = await importAddonModule(candidatePath)
+  } catch (err) {
+    recordIssue(issues, {
+      level: "error",
+      source,
+      message: `Failed to import addon entry: ${err instanceof Error ? err.message : String(err)}`,
+    })
+    return null
+  }
+  const exported = unwrapManifestExport(mod)
+  if (
+    exported === null ||
+    typeof exported !== "object" ||
+    typeof (exported as Record<string, unknown>)["apiVersion"] !== "number" ||
+    typeof (exported as Record<string, unknown>)["name"] !== "string"
+  ) {
+    const gotKeys =
+      exported !== null && typeof exported === "object"
+        ? Object.keys(exported as Record<string, unknown>).join(",")
+        : typeof exported
+    recordIssue(issues, {
+      level: "error",
+      source,
+      message: `Entry at ${candidatePath} did not export a valid AddonManifestV1 (apiVersion + name required). Got keys: [${gotKeys}]`,
+    })
+    return null
+  }
+  const manifest = exported as AddonManifestV1
+  if (Object.keys(manifest.buttonTypes ?? {}).length === 0 && !manifest.decks) {
+    recordIssue(issues, {
+      level: "error",
+      source,
+      message: `Addon ${source} defines no buttons or decks`,
+    })
+    return null
+  }
+  return { manifest, entryPath: candidatePath }
+}
+
+const loadLocalAddon = async (
+  source: string,
+  configDir: string,
+  homeDir: string,
+  issues: AddonLoadIssue[],
+  currentApi: number,
+): Promise<ResolvedExternalAddon | null> => {
+  const root = resolveLocalAddonRoot(source, configDir, homeDir)
+  if (!isLocalAddonSpec(source)) {
+    recordIssue(issues, {
+      level: "error",
+      source,
+      message: `Spec does not look like a local path: ${source}`,
+    })
+    return null
+  }
+  if (!addonRootExists(root)) {
+    recordIssue(issues, {
+      level: "error",
+      source,
+      message: `Local addon path does not exist: ${root}`,
+    })
+    return null
+  }
+  const json = readJsonManifest(root)
+  if (json === null) {
+    recordIssue(issues, {
+      level: "error",
+      source,
+      message: `Missing or invalid sirenodeck.json at ${root}`,
+    })
+    return null
+  }
+  if (json.kind === "theme") {
+    // ponytail: 3rd-party themes are loaded via the themes loader, not the
+    // addons loader. A theme author drops their package into
+    // `packages/cli/src/themes/<name>/` (or wires a custom themeDir via
+    // the CLI) and the discovery loop picks it up. Rejecting theme-kind
+    // entries from addons[] keeps the contracts clean and surfaces a
+    // clear error to anyone trying to put a theme in the wrong place.
+    recordIssue(issues, {
+      level: "warning",
+      source,
+      message: `Theme '${json.name}' declared via addons[] — drop themes into packages/cli/src/themes/<name>/ or pass --theme-dir; they aren't addons.`,
+    })
+    return null
+  }
+  if (json.apiVersion !== currentApi) {
+    recordIssue(issues, {
+      level: "warning",
+      source,
+      message: `Addon apiVersion mismatch: expected ${currentApi}, got ${json.apiVersion}`,
+    })
+  }
+  const { ts, js } = resolveEntryPaths(root, json)
+  const loaded = await validateAndLoadEntry(source, ts, js, issues)
+  if (!loaded) return null
+  return {
+    manifest: loaded.manifest,
+    source: { kind: "local", specifier: source, resolvedPath: root },
+    entryPath: loaded.entryPath,
+    browserEntryPath: resolveBrowserEntry(root, json),
+  }
+}
+
+interface ParsedSpecifier {
+  packageName: string
+  version: string | null
+}
+
+// npm package name spec — scoped names + optional @version
+const NPM_SPECIFIER =
+  /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*(?:@[a-z0-9][a-z0-9._-]*)?$/i
+const NPM_VERSION = /^[a-z0-9][a-z0-9._-]*$/i
+
+const parseNpmSpecifier = (spec: string): ParsedSpecifier | null => {
+  if (typeof spec !== "string" || !NPM_SPECIFIER.test(spec)) return null
+  const atIdx = spec.lastIndexOf("@")
+  if (atIdx <= 0) {
+    return { packageName: spec, version: null }
+  }
+  const packageName = spec.slice(0, atIdx)
+  const version = spec.slice(atIdx + 1)
+  if (version.length === 0 || !NPM_VERSION.test(version)) return null
+  return { packageName, version }
+}
+
+const readInstalledPackageJson = (
+  installPath: string,
+): {
+  name: string
+  version: string
+  apiVersion: number
+} | null => {
+  const pkgPath = resolvePath(installPath, "package.json")
+  if (!existsSync(pkgPath)) return null
+  let raw: unknown
+  try {
+    raw = JSON.parse(readFileSync(pkgPath, "utf8")) as unknown
+  } catch {
+    return null
+  }
+  if (raw === null || typeof raw !== "object") return null
+  const obj = raw as Record<string, unknown>
+  const name = typeof obj["name"] === "string" ? (obj["name"] as string) : null
+  const version =
+    typeof obj["version"] === "string" ? (obj["version"] as string) : null
+  const apiVersion = obj["sirenoAddonApiVersion"]
+  if (name === null || version === null) return null
+  if (typeof apiVersion !== "number") return null
+  return { name, version, apiVersion }
+}
+
+const loadNpmAddon = async (
+  source: string,
+  cacheDir: string,
+  projectDir: string | undefined,
+  globalPackageRoots: ReadonlyArray<string>,
+  issues: AddonLoadIssue[],
+  currentApi: number,
+): Promise<ResolvedExternalAddon | null> => {
+  const parsed = parseNpmSpecifier(source)
+  if (parsed === null) {
+    recordIssue(issues, {
+      level: "error",
+      source,
+      message: "Invalid npm specifier",
+    })
+    return null
+  }
+
+  const roots = [
+    ...(projectDir !== undefined ? [join(projectDir, "node_modules")] : []),
+    ...globalPackageRoots,
+    addonNpmRoot(cacheDir),
+  ]
+  const installPath = roots
+    .map((root) => join(root, parsed.packageName))
+    .find((path) => {
+      const pkg = readInstalledPackageJson(path)
+      return (
+        pkg !== null &&
+        (parsed.version === null || pkg.version === parsed.version)
+      )
+    })
+  const pkg =
+    installPath === undefined ? null : readInstalledPackageJson(installPath)
+
+  if (installPath === undefined) {
+    recordIssue(issues, {
+      level: "error",
+      source,
+      message: `Package '${source}' is not installed. Run 'sirenodeck install ${source}'.`,
+    })
+    return null
+  }
+  if (pkg === null) return null
+  const json = readJsonManifest(installPath)
+  if (json === null) {
+    recordIssue(issues, {
+      level: "error",
+      source,
+      message: `Missing or invalid sirenodeck.json at ${installPath}`,
+    })
+    return null
+  }
+  if (json.apiVersion !== currentApi) {
+    recordIssue(issues, {
+      level: "warning",
+      source,
+      message: `Addon apiVersion mismatch: expected ${currentApi}, got ${json.apiVersion}`,
+    })
+  }
+
+  const { ts, js } = resolveEntryPaths(installPath, json)
+  const loaded = await validateAndLoadEntry(source, ts, js, issues)
+  if (!loaded) return null
+  return {
+    manifest: loaded.manifest,
+    source: { kind: "npm", specifier: source, resolvedPath: installPath },
+    entryPath: loaded.entryPath,
+    browserEntryPath: resolveBrowserEntry(installPath, json),
+  }
+}
+
+export const loadAddons = async ({
+  entries,
+  configDir,
+  homeDir,
+  currentApiVersion,
+  cacheDir,
+  projectDir,
+  globalPackageRoots = [],
+}: LoadAddonsOptions): Promise<LoadAddonsResult> => {
+  const issues: AddonLoadIssue[] = []
+  const addons: ResolvedExternalAddon[] = []
+  const themes: LoadedTheme[] = []
+  for (const rawEntry of entries) {
+    const entry = normalizeAddonEntry(rawEntry)
+    if (!entry.enabled) {
+      recordIssue(issues, {
+        level: "info",
+        source: entry.source,
+        message: "Addon disabled in config",
+      })
+      continue
+    }
+    if (entry.isLocal || isLocalAddonSpec(entry.source)) {
+      const loaded = await loadLocalAddon(
+        entry.source,
+        configDir,
+        homeDir,
+        issues,
+        currentApiVersion,
+      )
+      if (loaded) addons.push(loaded)
+      continue
+    }
+    if (isNpmAddonSpec(entry.source) && cacheDir !== undefined) {
+      const loaded = await loadNpmAddon(
+        entry.source,
+        cacheDir,
+        projectDir,
+        entry.global ? globalPackageRoots : [],
+        issues,
+        currentApiVersion,
+      )
+      if (loaded) addons.push(loaded)
+      continue
+    }
+    recordIssue(issues, {
+      level: "error",
+      source: entry.source,
+      message: `Unknown addon spec: '${entry.source}'. Use a local path (./my-addon) or an npm specifier (my-addon, @scope/my-addon, my-addon@1.2.3).`,
+    })
+  }
+  return { addons, themes, issues }
+}

package/src/addon/registry.ts

@@ -0,0 +1,230 @@
+import type {
+  AddonButtonTypeDef,
+  AddonDeckDefinition,
+  AddonManifestV1,
+  LoadedTheme,
+} from "./api"
+import type { GestureKind } from "@/core/gesture-state"
+
+export class AddonRegistry {
+  private readonly addonsByName = new Map<string, AddonManifestV1>()
+  private readonly buttonsByType = new Map<
+    string,
+    { addonName: string; def: AddonButtonTypeDef }
+  >()
+  private readonly decksByType = new Map<
+    string,
+    { addonName: string; def: AddonDeckDefinition }
+  >()
+  private readonly themesByName = new Map<string, LoadedTheme>()
+
+  load(manifest: AddonManifestV1): void {
+    const name = manifest.name
+    if (this.addonsByName.has(name)) {
+      throw new Error(`Duplicate addon name: ${name}`)
+    }
+
+    // ponytail: hard cutover from legacy Record<key, {type, createDecks}>
+    // shape. Addons shipping the old JS shape (e.g. the 3 Phase-10 addons
+    // before phase-11 migration) hit this branch with a clear migration
+    // hint. TypeScript-shape manifests fail at type-check, never runtime.
+    if (
+      manifest.decks !== undefined &&
+      !Array.isArray(manifest.decks) &&
+      typeof manifest.decks === "object" &&
+      manifest.decks !== null
+    ) {
+      throw new Error(
+        `Addon '${name}' uses legacy decks format (Record keyed by '<addon>:<deck>'). ` +
+          `Migrate to an array: [{ id: '<addon>:<deck>', ...static fields }, ...]. ` +
+          `See phase-11 docs.`,
+      )
+    }
+
+    for (const buttonType of Object.keys(manifest.buttonTypes)) {
+      if (!buttonType.startsWith(`${name}:`)) {
+        throw new Error(
+          `Button type '${buttonType}' in addon '${name}' must be prefixed with '${name}:'`,
+        )
+      }
+    }
+
+    for (const [buttonType, def] of Object.entries(manifest.buttonTypes)) {
+      const service = def.service
+      if (!service) continue
+      const hasOnTap = typeof service.onTap === "function"
+      const hasOnDblTap = typeof service.onDblTap === "function"
+      const hasOnHold = typeof service.onHold === "function"
+      if (!hasOnTap && !hasOnDblTap && !hasOnHold) continue
+      const allowed = service.gestureHandlers ?? []
+      const toStrip: string[] = []
+      if (hasOnTap && !allowed.includes("tap" as GestureKind))
+        toStrip.push("onTap")
+      if (hasOnDblTap && !allowed.includes("dbl-tap" as GestureKind))
+        toStrip.push("onDblTap")
+      if (hasOnHold && !allowed.includes("hold" as GestureKind))
+        toStrip.push("onHold")
+      if (toStrip.length > 0) {
+        console.warn(
+          `[sirenodeck] addon "${name}" button "${buttonType}" declares [${toStrip.join(", ")}] ` +
+            `but not in gestureHandlers (default-deny). Stripping undeclared handlers. ` +
+            `Add gestureHandlers: [${toStrip.map((h) => `'${h.replace("on", "").toLowerCase()}'`).join(", ")}] to silence this.`,
+        )
+      }
+    }
+
+    this.addonsByName.set(name, manifest)
+    for (const [buttonType, def] of Object.entries(manifest.buttonTypes)) {
+      if (this.buttonsByType.has(buttonType)) {
+        throw new Error(
+          `Duplicate button type '${buttonType}' in addon ${name}`,
+        )
+      }
+      this.buttonsByType.set(buttonType, { addonName: name, def })
+      if (buttonType === `${name}:${name}`) {
+        this.buttonsByType.set(name, { addonName: name, def })
+      }
+    }
+
+    for (const entry of manifest.decks ?? []) {
+      // ponytail: three shapes — static, single-dynamic, multi-dynamic. The
+      // id (or each key returned from createDecks) becomes the deck-type key.
+      // Validation: ids must start with `<addon>:` prefix.
+      const prefix = `${name}:`
+      if (
+        typeof entry.createDeck === "function" &&
+        typeof entry.createDecks === "function"
+      ) {
+        throw new Error(
+          `Addon '${name}' deck entry has both createDeck and createDecks; choose one.`,
+        )
+      }
+      if (typeof entry.createDecks === "function") {
+        const def: AddonDeckDefinition = {
+          type: `${name}:__multi__`,
+          createDecks: entry.createDecks,
+        }
+        const syntheticKey = `${name}:__multi__`
+        if (this.decksByType.has(syntheticKey)) {
+          throw new Error(`Duplicate deck '${syntheticKey}' in addon ${name}`)
+        }
+        this.decksByType.set(syntheticKey, { addonName: name, def })
+        continue
+      }
+      if (typeof entry.createDeck === "function") {
+        if (entry.id === undefined || entry.id.length === 0) {
+          throw new Error(
+            `Addon '${name}' deck entry with createDeck must have an id.`,
+          )
+        }
+        if (!entry.id.startsWith(prefix)) {
+          throw new Error(
+            `Deck '${entry.id}' in addon '${name}' must be prefixed with '${prefix}'.`,
+          )
+        }
+        const def: AddonDeckDefinition = {
+          type: entry.id,
+          createDecks: (ctx) => ({ [entry.id]: entry.createDeck(ctx) }),
+        }
+        if (this.decksByType.has(entry.id)) {
+          throw new Error(`Duplicate deck '${entry.id}' in addon ${name}`)
+        }
+        this.decksByType.set(entry.id, { addonName: name, def })
+        continue
+      }
+      // ponytail: static — the entry IS the deck.
+      if (entry.id === undefined || entry.id.length === 0) {
+        throw new Error(`Addon '${name}' static deck entry must have an id.`)
+      }
+      if (!entry.id.startsWith(prefix)) {
+        throw new Error(
+          `Deck '${entry.id}' in addon '${name}' must be prefixed with '${prefix}'.`,
+        )
+      }
+      const def: AddonDeckDefinition = {
+        type: entry.id,
+        createDecks: () => ({ [entry.id]: entry }),
+      }
+      if (this.decksByType.has(entry.id)) {
+        throw new Error(`Duplicate deck '${entry.id}' in addon ${name}`)
+      }
+      this.decksByType.set(entry.id, { addonName: name, def })
+    }
+  }
+
+  getAddon(name: string): AddonManifestV1 | undefined {
+    return this.addonsByName.get(name)
+  }
+
+  listAddons(): AddonManifestV1[] {
+    return Array.from(this.addonsByName.values())
+  }
+
+  getButtonType(
+    type: string,
+  ): { addonName: string; def: AddonButtonTypeDef } | undefined {
+    return this.buttonsByType.get(type)
+  }
+
+  getDeckType(
+    type: string,
+  ): { addonName: string; def: AddonDeckDefinition } | undefined {
+    return this.decksByType.get(type)
+  }
+
+  hasButtonType(type: string): boolean {
+    return this.buttonsByType.has(type)
+  }
+
+  hasDeckType(type: string): boolean {
+    return this.decksByType.has(type)
+  }
+
+  listDeckTypes(): ReadonlyArray<{ id: string; addonName: string }> {
+    return [...this.decksByType.entries()].map(([id, v]) => ({
+      id,
+      addonName: v.addonName,
+    }))
+  }
+
+  loadTheme(theme: LoadedTheme): void {
+    if (this.themesByName.has(theme.name)) {
+      throw new Error(`Duplicate theme name: ${theme.name}`)
+    }
+    this.themesByName.set(theme.name, theme)
+  }
+
+  getTheme(name: string): LoadedTheme | undefined {
+    return this.themesByName.get(name)
+  }
+
+  listThemes(): LoadedTheme[] {
+    return Array.from(this.themesByName.values())
+  }
+
+  hasTheme(name: string): boolean {
+    return this.themesByName.has(name)
+  }
+
+  resolveActiveTheme(name: string | undefined): LoadedTheme {
+    const target = name ?? "default"
+    const theme = this.themesByName.get(target)
+    if (!theme) {
+      const available = this.listThemes()
+        .map((t) => t.name)
+        .sort()
+        .join(", ")
+      throw new Error(
+        `Theme '${target}' is not registered. Available themes: ${available || "(none)"}`,
+      )
+    }
+    return theme
+  }
+
+  reset(): void {
+    this.addonsByName.clear()
+    this.buttonsByType.clear()
+    this.decksByType.clear()
+    this.themesByName.clear()
+  }
+}