@sirenodeck/sirenodeck 0.1.1-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergio Carracedo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,69 @@
+# sirenodeck (CLI internals)
+
+Internal docs for the `sireno` CLI package. **User-facing docs** (quickstart, config.yml example, addon list) live at the [repo-root README](../../README.md).
+
+## Scripts
+
+| Command                                          | Purpose                                                        |
+| ------------------------------------------------ | -------------------------------------------------------------- |
+| `pnpm --filter @sirenodeck/sirenodeck dev`       | `node bin/dev.js` — dev CLI shim                               |
+| `pnpm --filter @sirenodeck/sirenodeck start`     | `node --import tsx src/cli/main.ts` — production-style startup |
+| `pnpm --filter @sirenodeck/sirenodeck build`     | bundles the frontend (`vite build`) and the CLI                |
+| `pnpm --filter @sirenodeck/sirenodeck test`      | `vitest run`                                                   |
+| `pnpm --filter @sirenodeck/sirenodeck typecheck` | `tsc --noEmit`                                                 |
+| `pnpm --filter @sirenodeck/sirenodeck lint`      | `oxlint src`                                                   |
+| `pnpm --filter @sirenodeck/sirenodeck format`    | `oxfmt src`                                                    |
+
+## Layout
+
+```
+packages/cli/
+  bin/
+    sireno.js                # entry shim (spawns tsx)
+    dev.js                   # dev shim (pnpm + vite)
+  src/
+    cli/                     # yargs CLI surface
+      main.ts                # argv parser + handler dispatch
+      index.ts               # command registry
+      http-server.ts         # prod HTTP server (in-memory WS token injection)
+      commands/
+        run.ts               # foreground dev runner
+        start.ts             # detached daemon
+        stop.ts              # SIGTERM → 5s → SIGKILL on children + daemon
+        status.ts            # pid + token preview + tracked children
+        emulator-mode.ts     # WS bridge + virtual-device vite children spawner
+        real-mode.ts         # Playwright screenshot → hardware write
+    addon/                   # addon API + loader (local + npm)
+    api/                     # shared types
+    builtin-addons/          # 10 builtin addons
+    core/                    # gesture state machine, pub-sub, store
+    deck/                    # deck runtime + methods
+    device/                  # device enumeration + models (mk2, plus, mini, xl)
+    os-providers/            # session, active-app, key-macro, media (Linux/macOS/Windows)
+    render/                  # Playwright + sharp + WS bridge
+    themes/
+      default/               # default theme (ButtonFrame + 4 surfaces)
+      light/                 # light theme override
+    util/                    # daemon, logger, cache-paths, device-config
+    vite/                    # vite plugin (sirenoDeck2)
+  frontend/                  # vite React 19 + Tailwind 4 frontend
+  config-ui/                  # vite configuration UI shell
+```
+
+## Conventions
+
+- **No comments in code** unless the task description explicitly asks for them.
+- **Indentation:** 2 spaces, no tabs.
+- **Quotes:** single quotes.
+- **Semicolons:** none.
+- **Trailing commas:** all.
+- **Print width:** 110.
+- **Imports:** no file extensions on relative imports.
+
+## Architecture rules
+
+- All cross-package code lives in `packages/cli`. No other packages in the workspace.
+- Sub-path exports: `.`, `./api`, `./react`, `./vite`.
+- Addon contract: `SIRENO_ADDON_API_VERSION = 3`.
+- WS protocol version: 3.
+- `core:*` prefix on all built-in button types.

package/bin/_wrapper-shared.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+import { platform } from "node:process"
+
+// ponytail: the dev wrappers (bin/dev.js, bin/sirenodeck.js) are pure JS so
+// they can't import the tsx-transpiled helpers under packages/cli/src/.
+// Re-implement the title/group-kill bits inline here — small enough that
+// the duplication is cheaper than a build step.
+
+const TITLE_MAX = 15
+
+export const setWrapperTitle = (title) => {
+  const capped =
+    platform === "linux" && title.length > TITLE_MAX
+      ? title.slice(0, TITLE_MAX)
+      : title
+  process.title = capped
+  return capped
+}
+
+// ponytail: when the daemon (`tsx -> main.ts`) exits, the wrapper used to
+// exit immediately and leave the daemon's children (vite on :5180, :52938,
+// :52937) reparented to init, still holding their ports. POSIX keeps the
+// process group alive after the leader dies, so `kill(-pgid, SIGTERM)`
+// followed by SIGKILL after a grace window cleans them up. The daemon was
+// spawned with `detached: true`, so its pid IS the pgid. We try the
+// negative-pid form first; Windows silently ignores it, so the unix guard
+// is the only behavioural branch.
+export const killProcessGroup = (pgid, signal) => {
+  if (platform === "win32") return
+  try {
+    process.kill(-pgid, signal)
+  } catch {
+    // group already empty or perms — best effort
+  }
+}
+
+export const reapOrphanProcessGroup = (pgid, graceMs = 500) => {
+  if (pgid === undefined || pgid === null || pgid <= 0) return
+  if (platform === "win32") return
+  killProcessGroup(pgid, "SIGTERM")
+  setTimeout(() => killProcessGroup(pgid, "SIGKILL"), graceMs).unref?.()
+}

package/bin/dev.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process"
+import { fileURLToPath } from "node:url"
+import { dirname, resolve } from "node:path"
+
+// eslint-disable-next-line import/extensions
+import { reapOrphanProcessGroup, setWrapperTitle } from "./_wrapper-shared.js"
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const cliRoot = resolve(__dirname, "..")
+const cliEntry = resolve(cliRoot, "src/cli/main.ts")
+
+const tsxBin = resolve(cliRoot, "node_modules", ".bin", "tsx")
+const tsconfigPath = resolve(cliRoot, "tsconfig.json")
+
+/**
+ * Tell tsx --watch to ignore the frontend workspace and theme assets. Those
+ * are served by Vite's own dev server; tsx restarting the daemon on a
+ * `frontend.tsx` change would kill Vite, the WebSocket bridge, and the
+ * emulator — exactly the "silent crash" we saw before adding ErrorBoundary.
+ *
+ * Use `tsx watch --exclude <patterns>` (a chokidar glob per token).
+ * The frontend lives at packages/cli/frontend and its addons live at
+ * packages/cli/src/builtin-addons/*\/frontend*; both should be hot-loaded
+ * by Vite alone, not trigger a daemon restart.
+ */
+const excludePatterns = [
+  "packages/cli/frontend/**",
+  "packages/cli/src/builtin-addons/**/frontend.tsx",
+  "packages/cli/src/builtin-addons/**/frontend/**",
+  "packages/cli/config-ui/**",
+  // Also match by the bare path tsx reports from the workspace root, where
+  // tsx is invoked relative to `src/cli/main.ts`:
+  "src/builtin-addons/**/frontend.tsx",
+  "src/builtin-addons/**/frontend/**",
+  "**/frontend.tsx",
+  "**/frontend/**",
+  "**/vite.config.ts",
+  "**/vite.config.cts",
+  "**/vite.config.mts",
+]
+
+// ponytail: tsx watch is designed to stay alive across script restarts —
+// wrapping it around a short-lived command (help, stop, status, restart,
+// reload) hangs the wrapper forever waiting for tsx to exit, even though
+// the script exits cleanly. Reserve `tsx watch` for `logs` (foreground
+// tail). Everything else runs under plain `tsx`, which exits with the
+// script.
+//
+// `start` is the load-bearing case: dev mode is detached (see
+// startInBackground in src/cli/commands/start.ts) — the wrapper spawns the
+// daemon via `spawnDetached`, writes the pid file, and exits. Plain tsx
+// gives us that exit; tsx watch would block the terminal forever.
+const LONG_LIVED_COMMANDS = new Set(["logs"])
+const firstArg = process.argv[2]
+const restArgs = process.argv.slice(2)
+
+const spawnTsx = (args, envExtra = {}) =>
+  spawn(tsxBin, args, {
+    stdio: "inherit",
+    cwd: cliRoot,
+    env: {
+      ...process.env,
+      SIRENO_CWD: process.cwd(),
+      TSX_TSCONFIG_PATH: tsconfigPath,
+      ...envExtra,
+    },
+  })
+
+const exitChild = (child) => new Promise((resolve) => child.on("exit", resolve))
+
+setWrapperTitle("sirenodeck:wrp")
+
+const useWatch = firstArg !== undefined && LONG_LIVED_COMMANDS.has(firstArg)
+
+const args = useWatch
+  ? [
+      "watch",
+      ...excludePatterns.flatMap((p) => ["--exclude", p]),
+      cliEntry,
+      ...restArgs,
+    ]
+  : [cliEntry, ...restArgs]
+
+const child = spawnTsx(args, {
+  SIRENO_DEV_MODE: "true",
+  SIRENO_WRAPPER_CHILD: "1",
+})
+
+child.on("exit", (code) => {
+  if (child.pid !== undefined) {
+    reapOrphanProcessGroup(child.pid)
+  }
+  process.exit(code ?? 0)
+})

package/bin/sirenodeck.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process"
+import { existsSync } from "node:fs"
+import { fileURLToPath } from "node:url"
+import { dirname, resolve } from "node:path"
+
+// eslint-disable-next-line import/extensions
+import { reapOrphanProcessGroup, setWrapperTitle } from "./_wrapper-shared.js"
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const cliRoot = resolve(__dirname, "..")
+const cliEntry = resolve(cliRoot, "dist", "main.mjs")
+
+setWrapperTitle("sirenodeck:bin")
+
+if (!existsSync(cliEntry)) {
+  // ponytail: the bundled CLI ships next to this wrapper. If it's missing,
+  // the consumer likely installed from npm before `prepublishOnly` ran the
+  // build, or the install was corrupted. Surface a clear error rather than
+  // failing silently with `Cannot find module`.
+  console.error(`sirenodeck: bundled CLI not found at ${cliEntry}`)
+  console.error(
+    "Reinstall the package or run `pnpm --filter @sirenodeck/sirenodeck build`.",
+  )
+  process.exit(1)
+}
+
+const child = spawn(process.execPath, [cliEntry, ...process.argv.slice(2)], {
+  stdio: "inherit",
+  env: {
+    ...process.env,
+    SIRENO_CWD: process.cwd(),
+    SIRENO_WRAPPER_CHILD: "1",
+  },
+})
+
+child.on("exit", (code) => {
+  if (child.pid !== undefined) {
+    reapOrphanProcessGroup(child.pid)
+  }
+  process.exit(code ?? 0)
+})

package/config/default-config.yml

@@ -0,0 +1,117 @@
+# sirenodeck — bundled default config
+# This is the same config shipped at the project root. The `!include` directives
+# reference paths relative to the project root (e.g. ./demos/...). When placed
+# at ~/.config/sirenodeck/config.yml those include paths will not resolve —
+# remove the demo `!include` lines or point them at absolute paths to your own
+# deck files. The `main` deck works without includes.
+theme: default
+
+addons:
+  - src: ./packages/addons/app-shortcuts
+    config:
+      defaults:
+        autoShow: false
+  - src: ./packages/addons/pomodoro
+
+logging:
+  level: info
+
+decks:
+  main:
+    name: Main Deck
+    buttons:
+      - position: 0
+        type: "system-status:system-status"
+        config:
+          pages:
+            - type: bars
+              metrics:
+                - cpu
+                - ram
+                - swap
+            - type: kpis
+              metrics:
+                - disk-io
+                - network-read
+                - network-write
+            - type: kpis
+              metrics:
+                - temperature
+                - gpu-temp
+                - fan-rpm
+            - type: kpis
+              metrics:
+                - uptime
+                - load
+
+      - position: 1
+        type: "core:change-deck"
+        config:
+          deck: demo-decks-index
+          icon: icon://layout-grid
+          label: Demos
+
+      - position: 2
+        type: "date-time:time"
+        config:
+          variant: big
+
+      - position: 3
+        type: "date-time:date"
+        actions:
+          tap: "xdg-open https://calendar.google.com"
+
+      - position: 4
+        type: "weather:weather"
+        config:
+          location:
+            latitude: 42.2304
+            longitude: -8.7256
+            name: Vigo
+
+      - position: 5
+        type: "system-status:system-status"
+        config:
+          pages:
+            - type: chart
+              metrics:
+                - cpu
+              windowSeconds: 60
+
+      - position: 6
+        type: "media:volume:down"
+
+      - position: 7
+        type: "media:volume:up"
+
+      - position: 8
+        type: "media:mute"
+
+      - position: 9
+        type: "emoji-selector:launcher"
+
+      - position: 10
+        type: "pomodoro:pomodoro"
+        config:
+          durationSec: 5
+
+      - position: 12
+        type: "media:player"
+
+      - type: "system-status"
+        config:
+          type: kpis
+          metrics:
+            - uptime
+
+  demo-decks-index: !include demos/demo-decks-index.yml
+  demo-app-shortcuts: !include demos/demo-app-shortcuts.yml
+  demo-app-overlays: !include demos/demo-app-overlays.yml
+  demo-system-status: !include demos/demo-system-status.yml
+  demo-media: !include demos/demo-media.yml
+  demo-weather: !include demos/demo-weather.yml
+  demo-emoji-selector: !include demos/demo-emoji-selector.yml
+  demo-date-time: !include demos/demo-date-time.yml
+  demo-value-display: !include demos/demo-value-display.yml
+  demo-core: !include demos/demo-core.yml
+  demo-pomodoro: !include demos/demo-pomodoro.yml

package/config/starter-config.yml

@@ -0,0 +1,54 @@
+# sirenodeck — starter config
+#
+# This is what `sirenodeck system-requirements` seeds to
+# $XDG_CONFIG_HOME/sirenodeck/config.yml on first run. It is deliberately
+# self-contained: no `!include` directives and no `addons:` entries with
+# relative `src:` paths, because both resolve relative to THIS file and would
+# fail the moment it is copied out of the repo.
+#
+# Only built-in addons are referenced, and only metrics that work on every
+# platform. See docs/ for the full button catalog.
+theme: default
+
+logging:
+  level: info
+
+decks:
+  main:
+    name: Main Deck
+    buttons:
+      - position: 0
+        type: "date-time:time"
+        config:
+          variant: big
+
+      - position: 1
+        type: "date-time:date"
+
+      - position: 2
+        type: "system-status:system-status"
+        config:
+          pages:
+            - type: bars
+              metrics:
+                - cpu
+                - ram
+            - type: kpis
+              metrics:
+                - uptime
+                - load
+
+      - position: 3
+        type: "media:player"
+
+      - position: 4
+        type: "media:volume:down"
+
+      - position: 5
+        type: "media:volume:up"
+
+      - position: 6
+        type: "media:mute"
+
+      - position: 7
+        type: "emoji-selector:launcher"