@sirenodeck/sirenodeck 0.1.1-alpha.0

package/src/config/schemas.ts

@@ -0,0 +1,223 @@
+import { z } from "zod"
+
+import { isIconSource } from "@/core/icon-source"
+
+export const TriggerSchema = z
+  .object({
+    process_name: z.union([z.string(), z.array(z.string()).min(1)]).optional(),
+    window_name: z.union([z.string(), z.array(z.string()).min(1)]).optional(),
+  })
+  .strict()
+  .refine((t) => t.process_name !== undefined || t.window_name !== undefined, {
+    message: "trigger requires at least one of `process_name` or `window_name`",
+  })
+
+export const ButtonActionsSchema = z
+  .object({
+    tap: z.string().min(1).optional(),
+    dbltap: z.string().min(1).optional(),
+    hold: z.string().min(1).optional(),
+  })
+  .strict()
+
+export type ButtonActions = z.infer<typeof ButtonActionsSchema>
+
+/**
+ * Runtime icon source. Accepted shapes:
+ *   - `icon://<name>` — Lucide icon by name (resolved at render time)
+ *   - `asset://<id>`  — pre-resolved asset id from the registry
+ *   - a single emoji (Presentation or base+VS16 like ✈️)
+ *
+ * Anything else is rejected at config-load time so typos surface before
+ * the daemon starts. The runtime also has a fallback path (alert-circle
+ * Lucide icon) so an invalid source that's slipped through can't crash
+ * the render tree.
+ */
+export const IconSourceSchema = z.string().min(1).refine(isIconSource, {
+  message:
+    "icon must be icon://<name>, asset://<id>, or a single emoji (one Presentation character or one base+VS16 like ✈️)",
+})
+
+export const ButtonConfigSchema = z.record(z.string(), z.unknown()).optional()
+
+/**
+ * Closed core set of per-button hue names. Themes declare which of these
+ * (or which additional names like riptide's `neon-pink`) they support
+ * by adding entries to `variants.<name>` in their manifest. Themes are
+ * authoritative — this list is a convention hint, not a constraint on
+ * the theme. Names not declared in the active theme fall back to
+ * "default" with a console.warn at render time (ButtonFrame).
+ */
+export const ButtonColorSchema = z.enum([
+  "blue",
+  "green",
+  "purple",
+  "cyan",
+  "magenta",
+  "amber",
+  "lime",
+])
+
+export const ButtonDefSchema = z
+  .object({
+    position: z.number().int().nonnegative().optional(),
+    type: z.string().min(1),
+    config: ButtonConfigSchema,
+    accent: z.string().optional(),
+    background: z.string().optional(),
+    actions: ButtonActionsSchema.optional(),
+    /**
+     * Variant token name. Resolved by ButtonFrame against the active
+     * theme's CSS vars at render time. Themes may declare extra
+     * variants beyond the 5-required set; users pick from whatever the
+     * active theme supports. Unknown names fall back to "default" with
+     * a console.warn.
+     */
+    variant: z.string().min(1).optional(),
+    /**
+     * Per-button hue customisation. Themes declare a `variants.<name>`
+     * entry for each buttonColor they support. See ButtonColorSchema
+     * for the closed core set; themes may add their own names
+     * (e.g. riptide's `neon-pink`) and the runtime accepts them — but
+     * this Zod schema restricts to the core set so typos fail-fast at
+     * config load.
+     */
+    buttonColor: ButtonColorSchema.optional(),
+    label: z.string().optional(),
+    icon: IconSourceSchema.optional(),
+    iconUrl: z.string().min(1).optional(),
+    size: z.string().optional(),
+    textSize: z.string().optional(),
+    borderRadius: z.string().optional(),
+    addon: z.string().optional(),
+    action: z.string().optional(),
+  })
+  .strict()
+
+export const ButtonEntrySchema = z.union([ButtonDefSchema, z.string()])
+
+export const DeckDefSchema = z
+  .object({
+    name: z.string().min(1).optional(),
+    label: z.string().min(1).optional(),
+    columns: z.number().int().positive().optional(),
+    rows: z.number().int().positive().optional(),
+    icon: IconSourceSchema.optional(),
+    background: z.string().min(1).optional(),
+    paginated: z.boolean().optional(),
+    trigger: TriggerSchema.optional(),
+    autoShow: z.boolean().optional(),
+    buttons: z.array(ButtonEntrySchema),
+  })
+  .strict()
+
+export const UserDeckCreateSchema = z
+  .object({
+    id: z.string().min(1),
+    name: z.string().min(1).optional(),
+    icon: IconSourceSchema.optional(),
+    background: z.string().min(1).optional(),
+    paginated: z.boolean().optional(),
+  })
+  .strict()
+
+export const UserDeckUpdateSchema = z
+  .object({
+    name: z.string().min(1).optional(),
+    icon: IconSourceSchema.nullable().optional(),
+    background: z.string().min(1).nullable().optional(),
+    paginated: z.boolean().optional(),
+    trigger: TriggerSchema.nullable().optional(),
+    autoShow: z.boolean().optional(),
+  })
+  .strict()
+
+/**
+ * Phase 11: per-deck overrides for an addon-deck generated by `createDeck(s)`.
+ * The deck id is the key in the parent record. Field-level overrides
+ * (`autoShow`/`name`/`icon`/`trigger`) apply on top of the generated
+ * deck; `config` is forwarded to `createDeck(s)({config})` as an
+ * additive merge over the addon's default config.
+ */
+export const AddonDeckOverrideSchema = z
+  .object({
+    autoShow: z.boolean().optional(),
+    name: z.string().min(1).optional(),
+    icon: IconSourceSchema.optional(),
+    trigger: TriggerSchema.optional(),
+    config: z.record(z.string(), z.unknown()).optional(),
+  })
+  .strict()
+
+export const AddonDeckDefaultsSchema = z
+  .object({
+    autoShow: z.boolean().optional(),
+  })
+  .strict()
+
+/**
+ * Phase 11: addon-config block under `addons[i]`. Hosts three shape variants:
+ * - `defaults:` addon-wide deck defaults (applied before per-deck overrides)
+ * - `decks:` record keyed by addon deck id, with per-deck overrides
+ * - addon-wide opaque config (anything else; merged into `createDeck(s)({config})`)
+ */
+export const AddonConfigSchema = z
+  .object({
+    defaults: AddonDeckDefaultsSchema.optional(),
+    decks: z.record(z.string(), AddonDeckOverrideSchema).optional(),
+  })
+  .strict()
+
+export const AddonEntrySchema = z.union([
+  z.string().min(1),
+  z
+    .object({
+      src: z.string().min(1),
+      enabled: z.boolean().optional(),
+      global: z.boolean().optional(),
+      config: AddonConfigSchema.optional(),
+    })
+    .strict(),
+])
+
+export const LoggingSchema = z
+  .object({
+    level: z
+      .enum(["trace", "debug", "info", "warn", "error", "fatal", "silent"])
+      .optional(),
+    verbose: z.boolean().optional(),
+  })
+  .strict()
+  .optional()
+
+export const LockSchema = z
+  .object({
+    buttons: z.array(ButtonDefSchema).optional(),
+  })
+  .strict()
+  .optional()
+
+export const ThemeEntrySchema = z.union([
+  z.string().min(1),
+  z.object({ src: z.string().min(1), global: z.boolean().optional() }).strict(),
+])
+
+export const RawConfigSchema = z
+  .object({
+    theme: ThemeEntrySchema.optional(),
+    logging: LoggingSchema,
+    decks: z.record(z.string(), DeckDefSchema),
+    addons: z.array(AddonEntrySchema).optional(),
+    lock: LockSchema,
+  })
+  .strict()
+
+export type RawButtonDef = z.infer<typeof ButtonDefSchema>
+export type RawButtonEntry = z.infer<typeof ButtonEntrySchema>
+export type RawDeckDef = z.infer<typeof DeckDefSchema>
+export type UserDeckCreate = z.infer<typeof UserDeckCreateSchema>
+export type UserDeckUpdate = z.infer<typeof UserDeckUpdateSchema>
+export type RawAddonEntry = z.infer<typeof AddonEntrySchema>
+export type RawConfig = z.infer<typeof RawConfigSchema>
+export type TriggerDef = z.infer<typeof TriggerSchema>
+export type ThemeEntry = z.infer<typeof ThemeEntrySchema>

package/src/config/validation.ts

@@ -0,0 +1,254 @@
+import type { AddonRegistry } from "@/addon/registry"
+import { z } from "zod"
+import { isSystemButtonType } from "@/deck/system-buttons/types"
+import type { RawButtonDef, RawConfig } from "./schemas"
+
+export interface BootstrapIssue {
+  level: "error" | "warning"
+  path: string
+  message: string
+}
+
+export interface BootstrapResult {
+  issues: BootstrapIssue[]
+}
+
+export type ValidationReason =
+  | "unknown-type"
+  | "internal-type"
+  | "malformed-config"
+  | "duplicate-position"
+  | "missing-main-deck"
+
+export interface FullValidationIssue {
+  level: "error" | "warning"
+  path: string
+  message: string
+  reason?: ValidationReason
+  deckId?: string
+  position?: number
+}
+
+export interface FullValidationResult {
+  issues: FullValidationIssue[]
+}
+
+const reportDuplicatePositions = (
+  deckId: string,
+  deck: RawConfig["decks"][string],
+): BootstrapIssue[] => {
+  const seen = new Map<number, number>()
+  const issues: BootstrapIssue[] = []
+  deck.buttons.forEach((btn, index) => {
+    if (typeof btn === "string") return
+    if (btn.position === undefined) return
+    const prev = seen.get(btn.position)
+    if (prev !== undefined) {
+      issues.push({
+        level: "warning",
+        path: `decks.${deckId}.buttons[${index}]`,
+        message: `Duplicate position ${btn.position} (also at index ${prev})`,
+      })
+    } else {
+      seen.set(btn.position, index)
+    }
+  })
+  return issues
+}
+
+export const validateBootstrap = (config: RawConfig): BootstrapResult => {
+  const issues: BootstrapIssue[] = []
+  if (!("main" in config.decks)) {
+    issues.push({
+      level: "warning",
+      path: "decks",
+      message:
+        "Missing required `main` deck — synthetic main deck will be created",
+    })
+  }
+  for (const [id, deck] of Object.entries(config.decks)) {
+    issues.push(...reportDuplicatePositions(id, deck))
+  }
+  return { issues }
+}
+
+export const isBootstrapValid = (result: BootstrapResult): boolean =>
+  result.issues.every((i) => i.level !== "error")
+
+export const formatBootstrapIssues = (issues: BootstrapIssue[]): string =>
+  issues
+    .map((issue) => {
+      const tag = issue.level === "error" ? "error" : "warning"
+      return `[${tag}] ${issue.path}: ${issue.message}`
+    })
+    .join("\n")
+
+export interface ConfigSchemaIssue {
+  readonly path: ReadonlyArray<string | number>
+  readonly message: string
+}
+
+export interface ButtonValidationResult {
+  readonly issues: FullValidationIssue[]
+  readonly schemaIssues: ConfigSchemaIssue[]
+}
+
+export const validateButton = (
+  btn: RawButtonDef,
+  registry: AddonRegistry,
+  path: string,
+  deckId?: string,
+  position?: number,
+): ButtonValidationResult => {
+  const base = { deckId, position }
+  const issues: FullValidationIssue[] = []
+  if (!registry.hasButtonType(btn.type)) {
+    issues.push({
+      level: "error",
+      path: `${path}.type`,
+      message: `Unknown button type: ${btn.type}`,
+      reason: "unknown-type",
+      ...base,
+    })
+    return { issues, schemaIssues: [] }
+  }
+  const def = registry.getButtonType(btn.type)!
+  if (isSystemButtonType(btn.type) || def.def.service.internal === true) {
+    issues.push({
+      level: "error",
+      path: `${path}.type`,
+      message: `Internal button type ${btn.type} cannot be used in user config`,
+      reason: "internal-type",
+      ...base,
+    })
+    return { issues, schemaIssues: [] }
+  }
+  const schema = def.def.service.configSchema as
+    | {
+        safeParse: (input: unknown) => {
+          success: boolean
+          error?: {
+            issues: Array<{ path: Array<string | number>; message: string }>
+          }
+        }
+      }
+    | undefined
+  if (schema === undefined) return { issues, schemaIssues: [] }
+  const parseResult = schema.safeParse(btn.config ?? {})
+  if (!parseResult.success) {
+    const schemaIssues = parseResult.error?.issues ?? []
+    for (const issue of schemaIssues) {
+      issues.push({
+        level: "error",
+        path: `${path}.config.${[...issue.path].join(".")}`,
+        message: issue.message,
+        reason: "malformed-config",
+        ...base,
+      })
+    }
+    return { issues, schemaIssues }
+  }
+  return { issues, schemaIssues: [] }
+}
+
+export const serializeButtonSchemas = (
+  registry: AddonRegistry,
+): Record<string, Record<string, unknown>> => {
+  const schemas: Record<string, Record<string, unknown>> = {}
+  for (const addon of registry.listAddons()) {
+    for (const [type, definition] of Object.entries(addon.buttonTypes)) {
+      const schema = definition.service?.configSchema
+      if (schema === undefined) continue
+      try {
+        schemas[type] = z.toJSONSchema(schema as never, {
+          io: "input",
+          unrepresentable: "any",
+        }) as Record<string, unknown>
+      } catch {
+        // Some external addons expose only a safeParse-compatible schema.
+      }
+    }
+  }
+  return schemas
+}
+
+// ponytail: deckId/position lets the runtime replace the button in-place
+// without a second validation pass or path-string parsing.
+
+export const validateFull = (
+  config: RawConfig,
+  registry: AddonRegistry,
+): FullValidationResult => {
+  const issues: FullValidationIssue[] = []
+  for (const [deckId, deck] of Object.entries(config.decks)) {
+    deck.buttons.forEach((btn, index) => {
+      if (typeof btn === "string") return
+      const path = `decks.${deckId}.buttons[${index}]`
+      issues.push(
+        ...validateButton(btn, registry, path, deckId, btn.position).issues,
+      )
+    })
+  }
+  return { issues }
+}
+
+export interface PerButtonValidationV2 {
+  deckId: string
+  buttonIndex: number
+  button: RawButtonDef
+  buttonId: string
+  position: number | undefined
+  path: string
+  issues: FullValidationIssue[]
+  schemaIssues: ConfigSchemaIssue[]
+}
+
+export interface PerDeckValidationV2 {
+  issues: FullValidationIssue[]
+  perButton: PerButtonValidationV2[]
+}
+
+export const validatePerDeck = (
+  config: RawConfig,
+  registry: AddonRegistry,
+): PerDeckValidationV2 => {
+  const issues: FullValidationIssue[] = []
+  const perButton: PerButtonValidationV2[] = []
+  for (const [deckId, deck] of Object.entries(config.decks)) {
+    deck.buttons.forEach((btn, index) => {
+      if (typeof btn === "string") return
+      const path = `decks.${deckId}.buttons[${index}]`
+      const { issues: buttonIssues, schemaIssues } = validateButton(
+        btn,
+        registry,
+        path,
+        deckId,
+        btn.position,
+      )
+      const buttonId = btn.position?.toString() ?? `b${index}`
+      perButton.push({
+        deckId,
+        buttonIndex: index,
+        button: btn,
+        buttonId,
+        position: btn.position,
+        path,
+        issues: buttonIssues,
+        schemaIssues,
+      })
+      issues.push(...buttonIssues)
+    })
+  }
+  return { issues, perButton }
+}
+
+export const isFullValid = (result: FullValidationResult): boolean =>
+  result.issues.every((i) => i.level !== "error")
+
+export const formatFullIssues = (issues: FullValidationIssue[]): string =>
+  issues
+    .map((issue) => {
+      const tag = issue.level === "error" ? "error" : "warning"
+      return `[${tag}] ${issue.path}: ${issue.message}`
+    })
+    .join("\n")

package/src/core/asset-id.ts

@@ -0,0 +1,21 @@
+import { basename } from "node:path"
+
+import { createHash } from "node:crypto"
+
+const HASH_BYTES = 8
+
+export const makeAssetId = (
+  fullPath: string,
+  filesize: number,
+  mtime: number,
+): string => {
+  const hash = createHash("sha256")
+    .update(fullPath)
+    .update("\0")
+    .update(String(filesize))
+    .update("\0")
+    .update(String(mtime))
+    .digest("hex")
+    .slice(0, HASH_BYTES * 2)
+  return `${basename(fullPath)}-${hash}`
+}