@shigureni/minion 0.1.0

package/README.md

@@ -0,0 +1,65 @@
+# minion
+
+A tiny desktop pet that walks around your screen and reacts to your
+[Claude Code](https://claude.com/claude-code) sessions — idle while you're idle,
+running around while a session is busy.
+
+It's two parts: a Swift menu-less overlay app (`swift/`) that draws the pet, and a
+CLI (`cli/`) that builds/runs it and watches `~/.claude/sessions` to decide how the
+pet should behave.
+
+## Requirements
+
+- macOS
+- [Bun](https://bun.sh)
+- Xcode Command Line Tools (`xcode-select --install`) — needed once, to compile the
+  Swift app on first run
+
+## Usage
+
+```sh
+bunx @shigureni/minion
+```
+
+This builds the app on first run (subsequent runs reuse the build unless the Swift
+source changed) and starts it in the background, alongside a small local gateway
+that watches your Claude Code sessions.
+
+Or install it globally so the `minion` command is always available:
+
+```sh
+bun add -g @shigureni/minion
+minion
+```
+
+### Commands
+
+| Command                           | Description                                      |
+| --------------------------------- | ------------------------------------------------ |
+| `minion` / `minion start`         | Start (release build). No-op if already running. |
+| `minion dev`                      | Restart with a debug build.                      |
+| `minion kill`                     | Stop the app and its gateway.                    |
+| `minion reboot`                   | Restart with a release build.                    |
+| `minion status`                   | Show whether the app/gateway are running.        |
+| `minion config list`              | List config values.                              |
+| `minion config get <key>`         | Get a config value.                              |
+| `minion config set <key> <value>` | Set a config value.                              |
+
+Add `-h` to any command for its help text (e.g. `minion start -h`).
+
+State (pid files, config, and the Swift build output) lives in `~/.minion`,
+independent of wherever the package itself is installed.
+
+## Development
+
+```sh
+bun install
+bun run check   # format + lint + type-check (vite-plus)
+bun run test
+bun run fmt
+bun run lint
+```
+
+`cli/src/routes/<command>/route.ts` is one file per command (hono-routed, mirrors
+the structure of jobantenna-cli) — adding a command means adding a route file and
+wiring it into `cli/src/app.ts`.

package/cli/src/app.ts

@@ -0,0 +1,27 @@
+import { factory } from "@/factory"
+import { onError } from "@/on-error"
+import configGet from "@/routes/config/get/[key]/route"
+import configList from "@/routes/config/list/route"
+import configSet from "@/routes/config/set/[key]/[value]/route"
+import dev from "@/routes/dev/route"
+import kill from "@/routes/kill/route"
+import { notFound } from "@/routes/not-found"
+import reboot from "@/routes/reboot/route"
+import start from "@/routes/start/route"
+import status from "@/routes/status/route"
+
+const base = factory.createApp()
+base.onError(onError)
+base.notFound(notFound)
+
+export const app = base
+  .post("/start", ...start)
+  .post("/dev", ...dev)
+  .post("/kill", ...kill)
+  .post("/reboot", ...reboot)
+  .post("/status", ...status)
+  .post("/config/list", ...configList)
+  .post("/config/get/:key", ...configGet)
+  .post("/config/set/:key/:value", ...configSet)
+
+export type AppType = typeof app

package/cli/src/factory.ts

@@ -0,0 +1,3 @@
+import { createFactory } from "hono/factory"
+
+export const factory = createFactory()

package/cli/src/gateway.ts

@@ -0,0 +1,204 @@
+#!/usr/bin/env bun
+
+import { readdirSync, readFileSync } from "node:fs"
+import { homedir } from "node:os"
+import { join } from "node:path"
+
+const SESSIONS_DIR = join(homedir(), ".claude", "sessions")
+const STALE_MS = 8 * 60 * 1000
+const TICK_MS = 250
+const PORT = Number(process.env.MINION_GATEWAY_PORT) || 4756
+
+// Swift側 PetView.clips と同じ並び順・重み(合計100)。座標や速度はSwiftが持つ
+// clip定義とスクリーン形状に依存するため、ここでは「どの行動を・どれだけ続けるか」だけを決める。
+const ACTIONS: { durationMs: [number, number]; weight: number }[] = [
+  { weight: 14, durationMs: [3000, 6000] }, // 0 待機
+  { weight: 10, durationMs: [3000, 6000] }, // 1 歩く
+  { weight: 28, durationMs: [4000, 7000] }, // 2 走る
+  { weight: 3, durationMs: [1000, 2000] }, // 3 ジャンプ1
+  { weight: 3, durationMs: [1000, 2000] }, // 4 ジャンプ2
+  { weight: 3, durationMs: [1000, 2000] }, // 5 ジャンプ3
+  { weight: 3, durationMs: [1000, 2000] }, // 6 ジャンプ4
+  { weight: 8, durationMs: [4000, 7000] }, // 7 座る1
+  { weight: 8, durationMs: [4000, 7000] }, // 8 座る2
+  { weight: 8, durationMs: [4000, 7000] }, // 9 座る3
+  { weight: 8, durationMs: [4000, 7000] }, // 10 座る4
+  { weight: 2, durationMs: [2000, 3000] }, // 11 食べる1
+  { weight: 2, durationMs: [2000, 3000] }, // 12 食べる2
+]
+const IDLE_CLIP = 0
+
+function pickAction(): { clipIndex: number; durationMs: number } {
+  const roll = Math.random() * 100
+  let cumulative = 0
+  let chosen = IDLE_CLIP
+  for (let i = 0; i < ACTIONS.length; i++) {
+    cumulative += ACTIONS[i].weight
+    if (roll < cumulative) {
+      chosen = i
+      break
+    }
+  }
+  const [min, max] = ACTIONS[chosen].durationMs
+  return { clipIndex: chosen, durationMs: min + Math.random() * (max - min) }
+}
+
+function isPidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch {
+    return false
+  }
+}
+
+// updatedAt はステータスが切り替わった時にしか更新されないため、
+// ずっと busy のまま長時間動いているセッションは経過時間だけでは判定できない。
+// プロセスが生きている間は経過時間を無視し、死んでから8分の猶予で消す。
+interface SessionInfo {
+  running: boolean
+  name: string
+}
+
+function readActiveSessions(): Map<string, SessionInfo> {
+  let files: string[]
+  try {
+    files = readdirSync(SESSIONS_DIR).filter((f) => f.endsWith(".json"))
+  } catch {
+    return new Map()
+  }
+
+  const now = Date.now()
+  const result = new Map<string, SessionInfo>()
+
+  for (const file of files) {
+    try {
+      const raw = JSON.parse(readFileSync(join(SESSIONS_DIR, file), "utf8"))
+      if (typeof raw.sessionId !== "string" || typeof raw.pid !== "number") continue
+
+      const alive = isPidAlive(raw.pid)
+      if (!alive) {
+        const updatedAt = raw.updatedAt ?? raw.statusUpdatedAt ?? raw.startedAt
+        if (typeof updatedAt !== "number" || now - updatedAt > STALE_MS) continue
+      }
+
+      result.set(raw.sessionId, {
+        running: alive && raw.status === "busy",
+        name: typeof raw.name === "string" ? raw.name : "",
+      })
+    } catch {
+      // 書き込み途中などで壊れているファイルは無視
+    }
+  }
+
+  return result
+}
+
+interface PetBehavior {
+  running: boolean
+  name: string
+  clipIndex: number
+  actionEndsAt: number
+}
+
+const behaviors = new Map<string, PetBehavior>()
+const clients = new Set()
+
+function snapshot() {
+  return Array.from(behaviors.entries()).map(([id, b]) => ({
+    id,
+    state: b.running ? "running" : "sleeping",
+    clipIndex: b.clipIndex,
+    name: b.name,
+  }))
+}
+
+function broadcast(): void {
+  const payload = JSON.stringify({ sessions: snapshot() })
+  for (const ws of clients) {
+    ;(ws as { send: (data: string) => void }).send(payload)
+  }
+}
+
+function tick(): void {
+  const now = Date.now()
+  const activeSessions = readActiveSessions()
+  let dirty = false
+
+  for (const id of behaviors.keys()) {
+    if (!activeSessions.has(id)) {
+      behaviors.delete(id)
+      dirty = true
+    }
+  }
+
+  for (const [id, info] of activeSessions) {
+    const existing = behaviors.get(id)
+
+    if (!existing) {
+      const action = info.running ? pickAction() : { clipIndex: IDLE_CLIP, durationMs: 0 }
+      behaviors.set(id, {
+        running: info.running,
+        name: info.name,
+        clipIndex: action.clipIndex,
+        actionEndsAt: now + action.durationMs,
+      })
+      dirty = true
+      continue
+    }
+
+    if (existing.name !== info.name) {
+      existing.name = info.name
+      dirty = true
+    }
+
+    if (existing.running !== info.running) {
+      existing.running = info.running
+      if (info.running) {
+        const action = pickAction()
+        existing.clipIndex = action.clipIndex
+        existing.actionEndsAt = now + action.durationMs
+      }
+      dirty = true
+    } else if (info.running && now >= existing.actionEndsAt) {
+      const action = pickAction()
+      existing.clipIndex = action.clipIndex
+      existing.actionEndsAt = now + action.durationMs
+      dirty = true
+    }
+  }
+
+  if (dirty) broadcast()
+}
+
+setInterval(tick, TICK_MS)
+tick()
+
+Bun.serve({
+  port: PORT,
+  fetch(req, server) {
+    const url = new URL(req.url)
+    if (url.pathname === "/sessions") {
+      return Response.json({ sessions: snapshot() })
+    }
+    if (url.pathname === "/ws") {
+      if (server.upgrade(req)) return undefined
+      return new Response("upgrade failed", { status: 400 })
+    }
+    return new Response("not found", { status: 404 })
+  },
+  websocket: {
+    open(ws) {
+      clients.add(ws)
+      ws.send(JSON.stringify({ sessions: snapshot() }))
+    },
+    close(ws) {
+      clients.delete(ws)
+    },
+    message() {
+      // クライアントからのメッセージは使わない
+    },
+  },
+})
+
+console.log(`gateway listening on :${PORT}`)

package/cli/src/index.ts

@@ -0,0 +1,63 @@
+#!/usr/bin/env bun
+import { app } from "@/app"
+import { postJson } from "@/lib/post-json"
+import { toRequest } from "@/router"
+
+import pkg from "../../package.json" with { type: "json" }
+
+const HELP = `minion - open-minion CLI
+
+Usage:
+  minion [command] [options]
+  minion <command> -h          Show help for a command
+
+Commands:
+  start                     起動する (デフォルト)
+  dev                       停止してデバッグビルドで起動し直す
+  kill                      停止する
+  reboot                    停止してリリースビルドで起動し直す
+  status                    起動状況を表示する
+  config list               設定値を一覧表示する
+  config get <key>          設定値を取得する
+  config set <key> <value>  設定値を書き込む
+
+Global flags:
+  -h, --help     Show help
+  -v, --version  Show version`
+
+const argv = process.argv.slice(2)
+const args = argv.length === 0 ? ["start"] : argv
+
+const request = toRequest(args)
+
+if (request.global.version) {
+  console.log(pkg.version)
+  process.exit()
+}
+
+if (request.global.help) {
+  if (request.path === "/") {
+    console.log(HELP)
+    process.exit()
+  }
+
+  const helpResponse = await app.request(request.path, postJson({ ...request.body, help: "true" }))
+  console.log(helpResponse.ok ? await helpResponse.text() : HELP)
+  process.exit()
+}
+
+try {
+  const response = await app.request(request.path, postJson(request.body))
+  const text = await response.text()
+
+  if (!response.ok) {
+    console.error(text || `Error ${response.status}`)
+    process.exit(1)
+  }
+
+  console.log(text)
+} catch (err) {
+  const error = err instanceof Error ? err : new Error(String(err))
+  console.error(error.message)
+  process.exit(1)
+}

package/cli/src/lib/help-guard.ts

@@ -0,0 +1,15 @@
+import type { MiddlewareHandler } from "hono"
+
+// --help を zValidator より先に処理する。必須フィールドを持つコマンドでも
+// `minion <command> --help` が検証エラー(400)で弾かれず help を返せるようにする。
+export function helpGuard(help: string): MiddlewareHandler {
+  return async (c, next) => {
+    const body = await c.req.json().catch(() => null)
+
+    if (body && typeof body === "object" && "help" in body && body.help) {
+      return c.text(help)
+    }
+
+    await next()
+  }
+}

package/cli/src/lib/post-json.ts

@@ -0,0 +1,8 @@
+// POST + JSON body の RequestInit を作る。Hono の app.request に渡す。
+export function postJson(body: Record<string, unknown> = {}) {
+  return {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  }
+}

package/cli/src/lib/process.ts

@@ -0,0 +1,204 @@
+import { createHash } from "node:crypto"
+import {
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs"
+import { homedir } from "node:os"
+import { join } from "node:path"
+
+const PACKAGE_ROOT = join(import.meta.dir, "..", "..", "..")
+const APP_ROOT = join(PACKAGE_ROOT, "swift")
+// bunx はパッケージ本体をキャッシュディレクトリに展開するため、状態とビルド
+// 成果物はパッケージの場所に依存しないよう ~/.minion に置く。
+const DATA_DIR = join(homedir(), ".minion")
+const BUILD_PATH = join(DATA_DIR, "build")
+const BIN_PATH = join(BUILD_PATH, "release", "open-minion")
+const DEBUG_BIN_PATH = join(BUILD_PATH, "debug", "open-minion")
+const DATA_FILE = join(DATA_DIR, "data.json")
+const PID_FILE = join(DATA_DIR, "pid")
+const CONFIG_FILE = join(DATA_DIR, "config.json")
+const GATEWAY_SCRIPT = join(import.meta.dir, "..", "gateway.ts")
+const GATEWAY_PID_FILE = join(DATA_DIR, "gateway.pid")
+
+interface BuildData {
+  sourceHash: string
+}
+
+function computeSourceHash(): string {
+  const files = [
+    join(APP_ROOT, "Package.swift"),
+    ...Array.from(new Bun.Glob("Sources/**/*.swift").scanSync({ cwd: APP_ROOT })).map((f) =>
+      join(APP_ROOT, f),
+    ),
+  ].sort()
+  const hash = createHash("sha256")
+  for (const file of files) {
+    hash.update(readFileSync(file))
+  }
+  return hash.digest("hex")
+}
+
+function readBuildData(): BuildData | null {
+  if (!existsSync(DATA_FILE)) return null
+  try {
+    return JSON.parse(readFileSync(DATA_FILE, "utf8"))
+  } catch {
+    return null
+  }
+}
+
+function writeBuildData(data: BuildData): void {
+  mkdirSync(DATA_DIR, { recursive: true })
+  writeFileSync(DATA_FILE, JSON.stringify(data, null, 2))
+}
+
+function readPid(pidFile: string = PID_FILE): number | null {
+  if (!existsSync(pidFile)) return null
+  const pid = parseInt(readFileSync(pidFile, "utf8").trim(), 10)
+  return Number.isNaN(pid) ? null : pid
+}
+
+function isRunning(pid: number): boolean {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch {
+    return false
+  }
+}
+
+function acquireStartLock(): boolean {
+  mkdirSync(DATA_DIR, { recursive: true })
+  try {
+    closeSync(openSync(PID_FILE, "wx"))
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function build(debug: boolean): Promise<boolean> {
+  console.log("ビルド中...")
+  const args = debug
+    ? ["swift", "build", "--scratch-path", BUILD_PATH]
+    : ["swift", "build", "-c", "release", "--scratch-path", BUILD_PATH]
+  const proc = Bun.spawn(args, {
+    cwd: APP_ROOT,
+    stdout: "inherit",
+    stderr: "inherit",
+  })
+  const code = await proc.exited
+  if (code !== 0) {
+    console.error("ビルド失敗")
+    return false
+  }
+  return true
+}
+
+function startGateway(): void {
+  const pid = readPid(GATEWAY_PID_FILE)
+  if (pid !== null && isRunning(pid)) return
+
+  mkdirSync(DATA_DIR, { recursive: true })
+  const proc = Bun.spawn(["bun", GATEWAY_SCRIPT], {
+    stdout: "ignore",
+    stderr: "ignore",
+    stdin: "ignore",
+  })
+  proc.unref()
+  writeFileSync(GATEWAY_PID_FILE, String(proc.pid))
+}
+
+function killGateway(): void {
+  const pid = readPid(GATEWAY_PID_FILE)
+  if (pid !== null && isRunning(pid)) {
+    process.kill(pid, "SIGTERM")
+  }
+  rmSync(GATEWAY_PID_FILE, { force: true })
+}
+
+export async function startApp(debug: boolean): Promise<string> {
+  const existingPid = readPid()
+  if (existingPid !== null) {
+    if (isRunning(existingPid)) {
+      return `すでに起動中 (pid ${existingPid})`
+    }
+    rmSync(PID_FILE, { force: true })
+  }
+
+  if (!acquireStartLock()) {
+    return "他の起動処理と競合したため中止"
+  }
+
+  const binPath = debug ? DEBUG_BIN_PATH : BIN_PATH
+
+  if (debug) {
+    if (!(await build(true))) {
+      rmSync(PID_FILE, { force: true })
+      return "ビルド失敗"
+    }
+  } else {
+    const currentHash = computeSourceHash()
+    const buildData = readBuildData()
+    if (!existsSync(binPath) || buildData?.sourceHash !== currentHash) {
+      if (!(await build(false))) {
+        rmSync(PID_FILE, { force: true })
+        return "ビルド失敗"
+      }
+      writeBuildData({ sourceHash: currentHash })
+    }
+  }
+
+  const proc = Bun.spawn([binPath], {
+    cwd: APP_ROOT,
+    stdout: "ignore",
+    stderr: "ignore",
+    stdin: "ignore",
+  })
+  proc.unref()
+  writeFileSync(PID_FILE, String(proc.pid))
+  startGateway()
+  return `起動した (pid ${proc.pid})`
+}
+
+export function killApp(): string {
+  killGateway()
+  const pid = readPid()
+  if (!pid || !isRunning(pid)) {
+    if (existsSync(PID_FILE)) rmSync(PID_FILE, { force: true })
+    return "起動していない"
+  }
+  process.kill(pid, "SIGTERM")
+  rmSync(PID_FILE, { force: true })
+  return `停止した (pid ${pid})`
+}
+
+export function statusApp(): string {
+  const pid = readPid()
+  const appLine = pid && isRunning(pid) ? `起動中 (pid ${pid})` : "停止中"
+
+  const gatewayPid = readPid(GATEWAY_PID_FILE)
+  const gatewayLine =
+    gatewayPid && isRunning(gatewayPid) ? `gateway起動中 (pid ${gatewayPid})` : "gateway停止中"
+
+  return [appLine, gatewayLine].join("\n")
+}
+
+export function readConfig(): Record<string, string> {
+  if (!existsSync(CONFIG_FILE)) return {}
+  try {
+    return JSON.parse(readFileSync(CONFIG_FILE, "utf8"))
+  } catch {
+    return {}
+  }
+}
+
+export function writeConfig(config: Record<string, string>): void {
+  mkdirSync(DATA_DIR, { recursive: true })
+  writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2))
+}

package/cli/src/on-error.ts

@@ -0,0 +1,10 @@
+import type { ErrorHandler } from "hono"
+import { HTTPException } from "hono/http-exception"
+
+export const onError: ErrorHandler = (err, c) => {
+  if (err instanceof HTTPException) {
+    return c.text(err.message, err.status)
+  }
+
+  return c.text(err.message, 500)
+}

package/cli/src/router.ts

@@ -0,0 +1,45 @@
+const SHORT_FLAGS: Record<string, string> = {
+  h: "help",
+  v: "version",
+}
+
+const GLOBAL_FLAGS = new Set(["help", "version"])
+
+export function toRequest(args: string[]) {
+  const segments: string[] = []
+  const body: Record<string, string> = {}
+
+  let i = 0
+  while (i < args.length) {
+    const arg = args[i]
+    if (arg.startsWith("--")) {
+      const key = arg.slice(2)
+      const next = args[i + 1]
+      if (next && !next.startsWith("-")) {
+        body[key] = next
+        i += 2
+      } else {
+        body[key] = "true"
+        i++
+      }
+    } else if (arg.startsWith("-") && arg.length === 2) {
+      const long = SHORT_FLAGS[arg[1]]
+      if (long) body[long] = "true"
+      i++
+    } else {
+      segments.push(arg)
+      i++
+    }
+  }
+
+  const global: Record<string, boolean> = {}
+  for (const flag of GLOBAL_FLAGS) {
+    if (flag in body) {
+      global[flag] = true
+      delete body[flag]
+    }
+  }
+
+  const path = `/${segments.join("/")}`
+  return { path, body, global }
+}

package/cli/src/routes/config/get/[key]/route.ts

@@ -0,0 +1,17 @@
+import { zValidator } from "@hono/zod-validator"
+import { z } from "zod"
+import { factory } from "@/factory"
+import { helpGuard } from "@/lib/help-guard"
+import { readConfig } from "@/lib/process"
+
+const schema = z.object({})
+
+export const help = `Usage: minion config get <key>
+
+設定値を取得する。`
+
+export default factory.createHandlers(helpGuard(help), zValidator("json", schema), async (c) => {
+  const key = c.req.param("key")
+  const config = readConfig()
+  return c.text(config[key ?? ""] ?? "")
+})

package/cli/src/routes/config/list/route.ts

@@ -0,0 +1,17 @@
+import { zValidator } from "@hono/zod-validator"
+import { z } from "zod"
+import { factory } from "@/factory"
+import { helpGuard } from "@/lib/help-guard"
+import { readConfig } from "@/lib/process"
+
+const schema = z.object({})
+
+export const help = `Usage: minion config list
+
+設定値を一覧表示する。`
+
+export default factory.createHandlers(helpGuard(help), zValidator("json", schema), async (c) => {
+  const config = readConfig()
+  const lines = Object.entries(config).map(([k, v]) => `${k} = ${v}`)
+  return c.text(lines.join("\n"))
+})