@sirenodeck/sirenodeck 0.1.1-alpha.0

package/src/config/builtin-icons.ts

@@ -0,0 +1,57 @@
+import { homedir } from "node:os"
+
+export const defaultResolveHome = (p: string): string => {
+  if (p === "~") return homedir()
+  if (p.startsWith("~/") || p.startsWith("~\\")) {
+    return homedir() + p.slice(1)
+  }
+  return p
+}
+
+export const BUILTIN_CLI_ICONS: ReadonlySet<string> = new Set<string>([
+  "play",
+  "pause",
+  "next",
+  "previous",
+  "stop",
+  "settings",
+  "back",
+  "home",
+  "lock",
+  "unlock",
+  "wifi",
+  "wifi-off",
+  "battery-full",
+  "battery-half",
+  "battery-low",
+  "battery-charging",
+  "volume-high",
+  "volume-mid",
+  "volume-low",
+  "volume-mute",
+  "cpu",
+  "memory",
+  "clock",
+  "calendar",
+  "sun",
+  "moon",
+  "spotify",
+  "chrome",
+  "firefox",
+  "discord",
+  "slack",
+  "vscode",
+  "terminal",
+  "folder",
+  "file",
+  "power",
+  "refresh",
+  "search",
+  "star",
+  "heart",
+  "check",
+  "close",
+  "add",
+  "remove",
+  "menu",
+])

package/src/config/config-diff.ts

@@ -0,0 +1,54 @@
+import type { RawButtonEntry, RawConfig, RawDeckDef } from "./schemas"
+
+const buttonKey = (entry: RawButtonEntry, idx: number): string => {
+  if (typeof entry === "string") return `s:${idx}:${entry}`
+  return `o:${idx}:${JSON.stringify(entry)}`
+}
+
+const stableValue = (value: unknown): unknown => {
+  if (Array.isArray(value)) return value.map(stableValue)
+  if (typeof value !== "object" || value === null) return value
+  return Object.fromEntries(
+    Object.entries(value)
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([key, entry]) => [key, stableValue(entry)]),
+  )
+}
+
+const sameButtons = (a: RawDeckDef, b: RawDeckDef): boolean => {
+  if (a.buttons.length !== b.buttons.length) return false
+  for (let i = 0; i < a.buttons.length; i += 1) {
+    if (buttonKey(a.buttons[i]!, i) !== buttonKey(b.buttons[i]!, i)) {
+      return false
+    }
+  }
+  return true
+}
+
+export const decksChanged = (prev: RawConfig, next: RawConfig): boolean => {
+  const prevKeys = Object.keys(prev.decks)
+  const nextKeys = Object.keys(next.decks)
+  if (prevKeys.length !== nextKeys.length) return true
+  for (const id of prevKeys) {
+    if (!Object.prototype.hasOwnProperty.call(next.decks, id)) return true
+  }
+  for (const id of nextKeys) {
+    const prevDeck = prev.decks[id]
+    const nextDeck = next.decks[id]
+    if (prevDeck === undefined || nextDeck === undefined) return true
+    if (
+      JSON.stringify(stableValue(prevDeck)) !==
+      JSON.stringify(stableValue(nextDeck))
+    )
+      return true
+    if (!sameButtons(prevDeck, nextDeck)) return true
+  }
+  return false
+}
+
+/** Returns true for every config change that can affect runtime/editor state. */
+export const configChanged = (prev: RawConfig, next: RawConfig): boolean =>
+  JSON.stringify(stableValue(prev)) !== JSON.stringify(stableValue(next))
+
+// Kept as the explicit old name used by the initial corrective tests.
+export const onlyDecksChanged = decksChanged

package/src/config/discovery.ts

@@ -0,0 +1,64 @@
+import { existsSync } from "node:fs"
+import { dirname, isAbsolute, resolve as resolvePath } from "node:path"
+
+import { getOriginalCwd } from "@/cli/cwd"
+
+export interface FindConfigOptions {
+  cwd?: string
+  explicitPath?: string
+  envVar?: string
+  homeDir: string
+  xdgConfigHome?: string
+}
+
+export const DEFAULT_CONFIG_FILENAME = "config.yml"
+export const XDG_CONFIG_SUBDIR = "sirenodeck"
+
+const resolvePath_ = (p: string, cwd: string): string =>
+  isAbsolute(p) ? p : resolvePath(cwd, p)
+
+// ponytail: precedence is cli arg → ~/.config/sirenodeck/config.yml →
+// ./config.yml (run folder / cwd). Parent-directory walk removed: the run
+// folder is the canonical place for a project config, and silently walking
+// up makes a "missing config" failure look like a "found some other config"
+// one. The previous walk also kept selectors scripts out of the canoe.
+export const findConfigPath = (options: FindConfigOptions): string | null => {
+  const cwd = options.cwd ?? getOriginalCwd()
+  if (options.explicitPath) {
+    const abs = resolvePath_(options.explicitPath, cwd)
+    return existsSync(abs) ? abs : null
+  }
+  if (options.envVar) {
+    const abs = resolvePath_(options.envVar, cwd)
+    if (existsSync(abs)) return abs
+  }
+  const xdgRoot =
+    options.xdgConfigHome ?? resolvePath(options.homeDir, ".config")
+  const xdgConfig = resolvePath(
+    xdgRoot,
+    XDG_CONFIG_SUBDIR,
+    DEFAULT_CONFIG_FILENAME,
+  )
+  if (existsSync(xdgConfig)) return xdgConfig
+  const cwdConfig = resolvePath(cwd, DEFAULT_CONFIG_FILENAME)
+  if (existsSync(cwdConfig)) return cwdConfig
+  return null
+}
+
+// ponytail: kept for the parent-walk test fixture — call sites should use
+// findConfigPath. Removing the export would break the existing test, so
+// the helper stays here as an explicit escape hatch with no callers.
+export const walkUpForConfig = (
+  startDir: string,
+  maxDepth: number,
+): string | null => {
+  let current = startDir
+  for (let depth = 0; depth <= maxDepth; depth += 1) {
+    const candidate = resolvePath(current, DEFAULT_CONFIG_FILENAME)
+    if (existsSync(candidate)) return candidate
+    const parent = dirname(current)
+    if (parent === current) return null
+    current = parent
+  }
+  return null
+}

package/src/config/icon-resolver.ts

@@ -0,0 +1,90 @@
+import { isAbsolute, resolve as resolvePath } from "node:path"
+
+export type IconSource =
+  | { kind: "path"; absolutePath: string }
+  | { kind: "cli-builtin"; id: string }
+  | { kind: "builtin-addon"; addonName: string; subPath: string }
+  | { kind: "addon"; addonName: string; subPath: string }
+
+export interface ResolveIconRefContext {
+  configDir: string
+  resolveHome(p: string): string
+  builtinIconIds: ReadonlySet<string>
+}
+
+const CLI_BUILTIN_PREFIX = "icon://"
+const BUILTIN_ADDON_PREFIX = "builtin://"
+const ADDON_PREFIX = "addon://"
+
+const startsWith = (s: string, prefix: string): boolean => s.startsWith(prefix)
+
+export const isLocalIconPath = (ref: string): boolean => {
+  if (startsWith(ref, "./") || startsWith(ref, "../") || startsWith(ref, "/"))
+    return true
+  if (startsWith(ref, "~/") || startsWith(ref, "~\\")) return true
+  if (/[\\/]/.test(ref)) return true
+  return false
+}
+
+export const resolveIconRef = (
+  ref: string,
+  ctx: ResolveIconRefContext,
+): IconSource => {
+  if (startsWith(ref, CLI_BUILTIN_PREFIX)) {
+    const id = ref.slice(CLI_BUILTIN_PREFIX.length)
+    if (id.length === 0) {
+      throw new Error(`Invalid CLI-builtin icon ref: ${ref} (missing id)`)
+    }
+    if (!ctx.builtinIconIds.has(id)) {
+      throw new Error(`Unknown CLI-builtin icon: ${id}`)
+    }
+    return { kind: "cli-builtin", id }
+  }
+  if (startsWith(ref, BUILTIN_ADDON_PREFIX)) {
+    const rest = ref.slice(BUILTIN_ADDON_PREFIX.length)
+    const slash = rest.indexOf("/")
+    if (slash <= 0 || slash === rest.length - 1) {
+      throw new Error(`Invalid builtin:// addon ref: ${ref}`)
+    }
+    return {
+      kind: "builtin-addon",
+      addonName: rest.slice(0, slash),
+      subPath: rest.slice(slash + 1),
+    }
+  }
+  if (startsWith(ref, ADDON_PREFIX)) {
+    const rest = ref.slice(ADDON_PREFIX.length)
+    const slash = rest.indexOf("/")
+    if (slash <= 0 || slash === rest.length - 1) {
+      throw new Error(`Invalid addon:// ref: ${ref}`)
+    }
+    return {
+      kind: "addon",
+      addonName: rest.slice(0, slash),
+      subPath: rest.slice(slash + 1),
+    }
+  }
+  if (isLocalIconPath(ref)) {
+    const expanded = startsWith(ref, "~") ? ctx.resolveHome(ref) : ref
+    const absolutePath = isAbsolute(expanded)
+      ? expanded
+      : resolvePath(ctx.configDir, expanded)
+    return { kind: "path", absolutePath }
+  }
+  throw new Error(
+    `Unrecognized icon ref: ${ref} — must be a relative path, icon://<id>, builtin://<addon>/<path>, or addon://<addon>/<path>`,
+  )
+}
+
+export const iconSourceToString = (src: IconSource): string => {
+  switch (src.kind) {
+    case "path":
+      return src.absolutePath
+    case "cli-builtin":
+      return `icon://${src.id}`
+    case "builtin-addon":
+      return `builtin://${src.addonName}/${src.subPath}`
+    case "addon":
+      return `addon://${src.addonName}/${src.subPath}`
+  }
+}

package/src/config/include-resolver.ts

@@ -0,0 +1,202 @@
+import { readFileSync, realpathSync } from "node:fs"
+import {
+  basename,
+  dirname,
+  isAbsolute,
+  resolve as resolvePath,
+} from "node:path"
+
+export class IncludeResolutionError extends Error {
+  readonly issues: { message: string; path?: string }[]
+
+  constructor(
+    message: string,
+    issues: { message: string; path?: string }[] = [],
+  ) {
+    super(message)
+    this.name = "IncludeResolutionError"
+    this.issues = issues
+  }
+}
+
+const INCLUDE_RE = /^(\s*)(.*?)\s*!include\s+(\S+)(.*)$/
+
+/**
+ * Resolves symlinks so two spellings of the same directory compare equal.
+ *
+ * ponytail: the containment check below is a plain string prefix, so a config
+ * reached through a symlinked parent failed it — the defining file had already
+ * been canonicalised while an absolute `!include` had not, and the two never
+ * shared a prefix. On macOS that is every config under a temp dir, since /var
+ * is a symlink to /private/var, but it applies to any symlinked config
+ * directory. Falls back to the literal path when the target does not exist yet
+ * (a missing include must be reported as missing, not as an escape attempt).
+ */
+const canonical = (p: string): string => {
+  try {
+    return realpathSync.native(p)
+  } catch {
+    try {
+      return resolvePath(realpathSync.native(dirname(p)), basename(p))
+    } catch {
+      return p
+    }
+  }
+}
+
+const isUnder = (candidate: string, root: string): boolean =>
+  candidate.startsWith(root.endsWith("/") ? root : `${root}/`)
+
+const resolveIncludePath = (
+  pathStr: string,
+  definingFilePath: string,
+): string => {
+  const lexicalRoot = resolvePath(dirname(definingFilePath))
+  const includePath = isAbsolute(pathStr)
+    ? pathStr
+    : resolvePath(lexicalRoot, pathStr)
+
+  // ponytail: containment is judged LEXICALLY, and that is the whole point.
+  // This check exists to stop `../../etc/passwd`, not to police where the
+  // user's own files live. Resolving symlinks first broke a perfectly ordinary
+  // setup — a `demos -> ../../repo/demos` symlink placed inside the config
+  // directory on purpose — by reporting the user's deliberate choice as a path
+  // traversal attempt and refusing to start the daemon.
+  //
+  // The canonical forms are still accepted, because the defining file may
+  // arrive already realpath'd while an absolute !include has not (on macOS
+  // /var is a symlink to /private/var, so this is every config under a temp
+  // dir). Any of the spellings matching is enough; `../` escapes match none.
+  const canonicalRoot = canonical(lexicalRoot)
+  const contained =
+    isUnder(includePath, lexicalRoot) ||
+    isUnder(includePath, canonicalRoot) ||
+    isUnder(canonical(includePath), canonicalRoot)
+
+  if (!contained) {
+    throw new IncludeResolutionError(
+      `!include path escapes config directory: ${includePath} (from ${definingFilePath})`,
+      [
+        {
+          message: `path traversal blocked: ${pathStr}`,
+          path: definingFilePath,
+        },
+      ],
+    )
+  }
+  return includePath
+}
+
+const processLine = (
+  line: string,
+  definingFilePath: string,
+  visited: Set<string>,
+  replacements: ReadonlyMap<string, string>,
+): string[] => {
+  const match = line.match(INCLUDE_RE)
+  if (match === null) return [line]
+  const indent = match[1] ?? ""
+  const before = match[2] ?? ""
+  const pathStr = match[3] ?? ""
+  if (pathStr.length === 0) {
+    throw new IncludeResolutionError(
+      `Empty !include path at ${definingFilePath}`,
+      [{ message: "empty path after !include", path: definingFilePath }],
+    )
+  }
+  // ponytail: !include must stay within the defining file's directory.
+  const includePath = resolveIncludePath(pathStr, definingFilePath)
+  if (visited.has(includePath)) {
+    const cycle = [...visited, includePath].join(" -> ")
+    throw new IncludeResolutionError(`Circular include detected: ${cycle}`, [
+      { message: `cycle: ${cycle}`, path: definingFilePath },
+    ])
+  }
+  let raw = replacements.get(includePath)
+  if (raw === undefined) {
+    try {
+      raw = readFileSync(includePath, "utf8")
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        throw new IncludeResolutionError(
+          `Included file not found: ${includePath} (from ${definingFilePath})`,
+          [{ message: `not found: ${includePath}`, path: definingFilePath }],
+        )
+      }
+      throw err
+    }
+  }
+  const next = new Set(visited)
+  next.add(includePath)
+  const inlined = inlineIncludes(raw, includePath, next, replacements)
+  if (before.trim().length === 0) {
+    return inlined.split("\n")
+  }
+  if (before.trim().endsWith(":")) {
+    const childIndent = `${indent}  `
+    const childContent = inlined
+      .split("\n")
+      .map((l) => (l.length === 0 ? l : childIndent + l))
+      .join("\n")
+    return [`${indent}${before}`, childContent]
+  }
+  throw new IncludeResolutionError(
+    `Unsupported !include position in line "${line}" (from ${definingFilePath})`,
+    [{ message: `unsupported !include position`, path: definingFilePath }],
+  )
+}
+
+const inlineIncludes = (
+  text: string,
+  definingFilePath: string,
+  visited: Set<string>,
+  replacements: ReadonlyMap<string, string>,
+): string => {
+  const lines = text.split("\n")
+  const out: string[] = []
+  for (const line of lines) {
+    out.push(...processLine(line, definingFilePath, visited, replacements))
+  }
+  return out.join("\n")
+}
+
+export const resolveIncludes = (
+  text: string,
+  definingFilePath: string,
+  replacements: ReadonlyMap<string, string> = new Map(),
+): string =>
+  inlineIncludes(
+    text,
+    definingFilePath,
+    new Set([definingFilePath]),
+    replacements,
+  )
+
+const discoverFromFile = (filePath: string, visited: Set<string>): string[] => {
+  const canonicalPath = realpathSync(filePath)
+  if (visited.has(canonicalPath)) {
+    throw new IncludeResolutionError(
+      `Circular include detected: ${canonicalPath}`,
+    )
+  }
+  const next = new Set(visited)
+  next.add(canonicalPath)
+  const sources = [canonicalPath]
+  for (const line of readFileSync(canonicalPath, "utf8").split("\n")) {
+    const match = line.match(INCLUDE_RE)
+    if (match === null) continue
+    const pathStr = match[3]
+    if (pathStr === undefined || pathStr.length === 0) {
+      throw new IncludeResolutionError(
+        `Empty !include path at ${canonicalPath}`,
+      )
+    }
+    const includePath = resolveIncludePath(pathStr, canonicalPath)
+    sources.push(...discoverFromFile(includePath, next))
+  }
+  return [...new Set(sources)]
+}
+
+/** Returns the canonical files reachable through !include, including root. */
+export const discoverIncludeGraph = (rootPath: string): string[] =>
+  discoverFromFile(rootPath, new Set())

package/src/config/index.ts

@@ -0,0 +1,9 @@
+export * from "./builtin-icons"
+export * from "./discovery"
+export * from "./icon-resolver"
+export * from "./include-resolver"
+export * from "./loader"
+export * from "./mutation"
+export * from "./reference-expander"
+export * from "./schemas"
+export * from "./validation"

package/src/config/loader.ts

@@ -0,0 +1,187 @@
+import { readFileSync } from "node:fs"
+import { dirname, isAbsolute, resolve as resolvePath } from "node:path"
+
+import { parseDocument, YAMLParseError } from "yaml"
+
+import { getOriginalCwd } from "@/cli/cwd"
+
+import { IncludeResolutionError, resolveIncludes } from "./include-resolver"
+import { RawConfigSchema, type RawConfig } from "./schemas"
+import { expandButtonReferences } from "./reference-expander"
+
+export interface LoadConfigOptions {
+  configPath: string
+}
+
+export interface LoadConfigResult {
+  config: RawConfig
+  configDir: string
+}
+
+export interface LineLocation {
+  line: number
+  col: number
+}
+
+export interface ConfigError {
+  message: string
+  location?: LineLocation
+  path?: string
+}
+
+export class ConfigLoadError extends Error {
+  readonly issues: ConfigError[]
+
+  constructor(message: string, issues: ConfigError[] = []) {
+    super(message)
+    this.name = "ConfigLoadError"
+    this.issues = issues
+  }
+}
+
+const formatLineCol = (loc: LineLocation): string =>
+  `line ${loc.line + 1}, col ${loc.col + 1}`
+
+const convertYamlErrors = (err: unknown): ConfigError[] => {
+  if (err instanceof YAMLParseError) {
+    const linePos = err.linePos?.[0]
+    return [
+      {
+        message: err.message,
+        ...(linePos
+          ? { location: { line: linePos.line, col: linePos.col } }
+          : {}),
+      },
+    ]
+  }
+  if (Array.isArray(err)) {
+    return err.map((e) => {
+      const linePos = e.linePos?.[0]
+      return {
+        message: e.message ?? String(e),
+        ...(linePos
+          ? { location: { line: linePos.line, col: linePos.col } }
+          : {}),
+      } satisfies ConfigError
+    })
+  }
+  return [{ message: err instanceof Error ? err.message : String(err) }]
+}
+
+export const loadConfigFile = (configPath: string): unknown => {
+  const absolutePath = isAbsolute(configPath)
+    ? configPath
+    : resolvePath(getOriginalCwd(), configPath)
+  let raw: string
+  try {
+    raw = readFileSync(absolutePath, "utf8")
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      throw new ConfigLoadError(`Config file not found: ${absolutePath}`)
+    }
+    throw err
+  }
+  const doc = parseDocument(raw, { keepSourceTokens: true })
+  const errors = doc.errors
+  // ponytail: textual include inlining — pre-process before yaml parses so
+  // included content participates in normal yaml merge semantics. Cycle
+  // detection and missing-file errors are raised here, before schema validation.
+  let inlinedRaw: string
+  try {
+    inlinedRaw = resolveIncludes(raw, absolutePath)
+  } catch (err) {
+    if (err instanceof IncludeResolutionError) {
+      throw new ConfigLoadError(err.message, err.issues)
+    }
+    throw err
+  }
+  if (inlinedRaw !== raw) {
+    const inlinedDoc = parseDocument(inlinedRaw, { keepSourceTokens: true })
+    const inlinedErrors = inlinedDoc.errors
+    if (inlinedErrors.length > 0) {
+      throw new ConfigLoadError(
+        `YAML parse errors in ${absolutePath} (after inlining includes):\n${inlinedErrors
+          .map((e) => ` - ${e.message}`)
+          .join("\n")}`,
+        convertYamlErrors(inlinedErrors),
+      )
+    }
+    return inlinedDoc.toJSON()
+  }
+  if (errors.length > 0) {
+    throw new ConfigLoadError(
+      `YAML parse errors in ${absolutePath}:\n${errors.map((e) => ` - ${e.message}`).join("\n")}`,
+      convertYamlErrors(errors),
+    )
+  }
+  return doc.toJSON()
+}
+
+// ponytail: zod 4's z.union() surfaces a top-level "Invalid input"
+// with the per-variant reasons buried under `errors: Array<Array<issue>>`.
+// We flatten those variant arrays into the top-level issue list so users
+// see the actual cause (e.g. "Unrecognized key: \"src\"") instead of a
+// useless top-level generic.
+type RawZodIssue = {
+  message: string
+  path?: Array<string | number>
+  errors?: ReadonlyArray<ReadonlyArray<RawZodIssue>>
+}
+
+const flattenZodIssues = (
+  rawIssues: ReadonlyArray<RawZodIssue>,
+  basePath: ReadonlyArray<string | number> = [],
+): ConfigError[] => {
+  const out: ConfigError[] = []
+  for (const issue of rawIssues) {
+    const path = [...basePath, ...(issue.path ?? [])]
+    if (issue.errors !== undefined && issue.errors.length > 0) {
+      // ponytail: union variant issues — flatten ALL variants' issues so
+      // the user sees every possible mismatch. Filter out empty arrays
+      // (variants that matched nothing).
+      for (const variant of issue.errors) {
+        if (variant.length > 0) {
+          out.push(...flattenZodIssues(variant, path))
+        }
+      }
+      continue
+    }
+    out.push({
+      message: issue.message,
+      ...(path.length > 0 ? { path: path.join(".") } : {}),
+    })
+  }
+  return out
+}
+
+const reportZodIssues = (issues: ConfigError[]): string =>
+  issues
+    .map((issue) => {
+      const parts = [issue.message]
+      if (issue.location) parts.push(`@ ${formatLineCol(issue.location)}`)
+      if (issue.path) parts.push(`(at ${issue.path})`)
+      return ` - ${parts.join(" ")}`
+    })
+    .join("\n")
+
+export const loadConfig = ({
+  configPath,
+}: LoadConfigOptions): LoadConfigResult => {
+  const configDir = dirname(configPath)
+  const raw = loadConfigFile(configPath)
+  const expanded = expandButtonReferences(raw, configDir)
+  const result = RawConfigSchema.safeParse(expanded)
+  if (!result.success) {
+    // ponytail: recurse into unionErrors so the user sees the actual
+    // discriminator failure (e.g. "Unrecognized key 'src'") instead of
+    // a useless top-level "Invalid input".
+    const issues = flattenZodIssues(
+      result.error.issues as ReadonlyArray<RawZodIssue>,
+    )
+    throw new ConfigLoadError(
+      `Invalid config at ${configPath}:\n${reportZodIssues(issues)}`,
+      issues,
+    )
+  }
+  return { config: result.data, configDir }
+}