@shigureni/minion 0.1.0 → 0.2.0

package/README.md

@@ -1,65 +1,111 @@
 # 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.
+A tiny desktop pet that walks around your macOS screen and reacts to your
+[Claude Code](https://claude.com/claude-code) sessions — napping while you're
+idle, running around while Claude is busy working.
 
-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.
+The more you use Claude Code, the more you collect: heavy usage, late-night
+sessions, and day streaks unlock achievements and rare minions in a built-in dex.
 
 ## Requirements
 
 - macOS
 - [Bun](https://bun.sh)
-- Xcode Command Line Tools (`xcode-select --install`) — needed once, to compile the
-  Swift app on first run
+- Xcode Command Line Tools (`xcode-select --install`) — needed once, to compile
+  the pet on first run
 
-## Usage
+## Quick start
 
 ```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.
+The first run compiles the pet (takes a minute), then it appears on your screen
+and starts watching your Claude Code sessions. Later runs reuse the build.
 
-Or install it globally so the `minion` command is always available:
+To keep the `minion` command around:
 
 ```sh
 bun add -g @shigureni/minion
 minion
 ```
 
-### Commands
+## 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.                              |
+| Command                          | What it does                             |
+| -------------------------------- | ---------------------------------------- |
+| `minion` / `minion start`        | Start the pet. No-op if already running. |
+| `minion kill`                    | Stop the pet and its gateway.            |
+| `minion reboot`                  | Restart.                                 |
+| `minion status`                  | Is it running?                           |
+| `minion dex`                     | Your achievements and minion collection. |
+| `minion config list / get / set` | Tweak settings.                          |
+| `minion dev`                     | Restart with a debug build.              |
 
-Add `-h` to any command for its help text (e.g. `minion start -h`).
+Add `-h` to any command for details. State lives in `~/.minion`.
 
-State (pid files, config, and the Swift build output) lives in `~/.minion`,
-independent of wherever the package itself is installed.
+## The dex
+
+`minion dex` turns your Claude Code habits into a collection game. It reads your
+session activity and token usage (from Claude Code's local transcripts) and
+unlocks two kinds of things:
+
+- **Achievements** — milestones like your first session, a 7-day streak, running
+  5 sessions at once, or burning a million tokens in a day.
+- **Minions** — the five common species come out at different times of day; the
+  rare ones demand something special: 5+ parallel sessions, a week-long streak,
+  hopping across 10 different projects, 10M lifetime tokens, coding at 3am...
+
+Undiscovered entries stay hidden as `???` until you earn them. Sprites aren't
+wired into the desktop pet yet — for now the dex is a text-only collection — but
+per-species art hooks are already in place.
+
+## Use it as a library
+
+Everything the CLI does is also a programmable API:
+
+```ts
+import { Minion } from "@shigureni/minion"
+
+const minion = new Minion()
+// { kind: "started", pid } | { kind: "build-failed", ... } | ... | Error — the library never throws
+const result = await minion.app.start()
+
+const stats = minion.stats.collect()
+const { species } = minion.collection.evaluate(stats)
+console.log(`right now: ${species.name}`)
+```
+
+Everything is injectable. Bring your own species/achievement catalogs — including
+your own art via each entry's `asset` field — or run fully sandboxed in tests:
+
+```ts
+// Custom catalog: your species, your conditions, your sprites.
+const custom = new Minion({
+  species: [
+    {
+      id: "sunny",
+      name: "Sunny Pal",
+      rarity: "common",
+      description: "Appears during the day.",
+      condition: (s) => s.timeBucket === "day",
+      asset: "sprites/sunny.png",
+    },
+  ],
+})
+
+// Sandbox: no real disk, processes, or clock.
+const sandbox = Minion.inMemory()
+```
+
+See `lib/index.ts` for the full API surface.
 
 ## Development
 
 ```sh
 bun install
-bun run check   # format + lint + type-check (vite-plus)
+bun run check   # format + lint + type-check
 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`.
+Architecture notes and contributor conventions live in [CLAUDE.md](CLAUDE.md).

package/cli/src/app.ts

@@ -4,6 +4,7 @@ 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 dex from "@/routes/dex/route"
 import kill from "@/routes/kill/route"
 import { notFound } from "@/routes/not-found"
 import reboot from "@/routes/reboot/route"
@@ -17,6 +18,7 @@ base.notFound(notFound)
 export const app = base
   .post("/start", ...start)
   .post("/dev", ...dev)
+  .post("/dex", ...dex)
   .post("/kill", ...kill)
   .post("/reboot", ...reboot)
   .post("/status", ...status)

package/cli/src/factory.ts

@@ -1,3 +1,10 @@
 import { createFactory } from "hono/factory"
+import type { Minion } from "@lib/minion"
 
-export const factory = createFactory()
+export type Env = {
+  Bindings: {
+    minion: Minion
+  }
+}
+
+export const factory = createFactory<Env>()

package/cli/src/index.ts

@@ -2,9 +2,17 @@
 import { app } from "@/app"
 import { postJson } from "@/lib/post-json"
 import { toRequest } from "@/router"
+import { Minion } from "@lib/minion"
 
 import pkg from "../../package.json" with { type: "json" }
 
+const minion = new Minion({
+  onEvent: (event) => {
+    if (event.type === "build-start") console.log("ビルド中...")
+  },
+})
+const env = { minion }
+
 const HELP = `minion - open-minion CLI
 
 Usage:
@@ -17,6 +25,7 @@ Commands:
   kill                      停止する
   reboot                    停止してリリースビルドで起動し直す
   status                    起動状況を表示する
+  dex                       実績とミニオン図鑑を表示する
   config list               設定値を一覧表示する
   config get <key>          設定値を取得する
   config set <key> <value>  設定値を書き込む
@@ -41,13 +50,17 @@ if (request.global.help) {
     process.exit()
   }
 
-  const helpResponse = await app.request(request.path, postJson({ ...request.body, help: "true" }))
+  const helpResponse = await app.request(
+    request.path,
+    postJson({ ...request.body, help: "true" }),
+    env,
+  )
   console.log(helpResponse.ok ? await helpResponse.text() : HELP)
   process.exit()
 }
 
 try {
-  const response = await app.request(request.path, postJson(request.body))
+  const response = await app.request(request.path, postJson(request.body), env)
   const text = await response.text()
 
   if (!response.ok) {

package/cli/src/lib/body-validator.ts

@@ -0,0 +1,13 @@
+import { zValidator } from "@hono/zod-validator"
+import type { z } from "zod"
+
+// zValidator の 400 応答(zod エラーの JSON ダンプ)を CLI 向けの短いテキストにする。
+// strict スキーマと組み合わせて、未知のフラグを黙って無視せずエラーにする。
+export function bodyValidator<T extends z.ZodType>(schema: T) {
+  return zValidator("json", schema, (result, c) => {
+    if (!result.success) {
+      const message = result.error.issues.map((issue) => issue.message).join("\n")
+      return c.text(message, 400)
+    }
+  })
+}

package/cli/src/lib/format.ts

@@ -0,0 +1,36 @@
+import type {
+  MinionAppStatus,
+  MinionKillResult,
+  MinionStartResult,
+} from "@lib/engine/app/app-runner"
+
+// ライブラリは構造化された結果を返す。日本語の表示文字列への整形はCLIの責務。
+
+export function formatStartResult(result: MinionStartResult): string {
+  switch (result.kind) {
+    case "started":
+      return `起動した (pid ${result.pid})`
+    case "already-running":
+      return `すでに起動中 (pid ${result.pid})`
+    case "build-failed":
+      return "ビルド失敗"
+    case "lock-conflict":
+      return "他の起動処理と競合したため中止"
+  }
+}
+
+export function isStartError(result: MinionStartResult): boolean {
+  return result.kind === "build-failed" || result.kind === "lock-conflict"
+}
+
+export function formatKillResult(result: MinionKillResult): string {
+  return result.kind === "killed" ? `停止した (pid ${result.pid})` : "起動していない"
+}
+
+export function formatAppStatus(status: MinionAppStatus): string {
+  const appLine = status.app.running ? `起動中 (pid ${status.app.pid})` : "停止中"
+  const gatewayLine = status.gateway.running
+    ? `gateway起動中 (pid ${status.gateway.pid})`
+    : "gateway停止中"
+  return [appLine, gatewayLine].join("\n")
+}

package/cli/src/router.ts

@@ -40,6 +40,7 @@ export function toRequest(args: string[]) {
     }
   }
 
-  const path = `/${segments.join("/")}`
+  // `/` や `:` を含む値(URLなど)がルーティングを壊さないようエンコードする。Hono がパラメータ取得時にデコードする。
+  const path = `/${segments.map(encodeURIComponent).join("/")}`
   return { path, body, global }
 }

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

@@ -1,17 +1,17 @@
-import { zValidator } from "@hono/zod-validator"
 import { z } from "zod"
 import { factory } from "@/factory"
+import { bodyValidator } from "@/lib/body-validator"
 import { helpGuard } from "@/lib/help-guard"
-import { readConfig } from "@/lib/process"
 
-const schema = z.object({})
+const schema = z.strictObject({})
 
 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 ?? ""] ?? "")
+export default factory.createHandlers(helpGuard(help), bodyValidator(schema), async (c) => {
+  const key = c.req.param("key") ?? ""
+  const value = c.env.minion.config.get(key)
+  if (value === undefined) return c.text(`未設定: ${key}`, 404)
+  return c.text(value)
 })

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

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

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

@@ -1,20 +1,18 @@
-import { zValidator } from "@hono/zod-validator"
 import { z } from "zod"
 import { factory } from "@/factory"
+import { bodyValidator } from "@/lib/body-validator"
 import { helpGuard } from "@/lib/help-guard"
-import { readConfig, writeConfig } from "@/lib/process"
 
-const schema = z.object({})
+const schema = z.strictObject({})
 
 export const help = `Usage: minion config set <key> <value>
 
 設定値を書き込む。`
 
-export default factory.createHandlers(helpGuard(help), zValidator("json", schema), async (c) => {
+export default factory.createHandlers(helpGuard(help), bodyValidator(schema), async (c) => {
   const key = c.req.param("key") ?? ""
   const value = c.req.param("value") ?? ""
-  const config = readConfig()
-  config[key] = value
-  writeConfig(config)
+  const setError = c.env.minion.config.set(key, value)
+  if (setError) return c.text(setError.message, 500)
   return c.text(`${key} = ${value}`)
 })

package/cli/src/routes/dev/route.ts

@@ -1,17 +1,22 @@
-import { zValidator } from "@hono/zod-validator"
 import { z } from "zod"
 import { factory } from "@/factory"
+import { bodyValidator } from "@/lib/body-validator"
+import { formatKillResult, formatStartResult, isStartError } from "@/lib/format"
 import { helpGuard } from "@/lib/help-guard"
-import { killApp, startApp } from "@/lib/process"
 
-const schema = z.object({})
+const schema = z.strictObject({})
 
 export const help = `Usage: minion dev
 
 一旦停止してから、デバッグビルドで起動し直す。`
 
-export default factory.createHandlers(helpGuard(help), zValidator("json", schema), async (c) => {
-  const killMessage = killApp()
-  const startMessage = await startApp(true)
-  return c.text([killMessage, startMessage].join("\n"))
+export default factory.createHandlers(helpGuard(help), bodyValidator(schema), async (c) => {
+  const killResult = c.env.minion.app.kill()
+  if (killResult instanceof Error) return c.text(killResult.message, 500)
+  const startResult = await c.env.minion.app.start({ debug: true })
+  if (startResult instanceof Error) {
+    return c.text([formatKillResult(killResult), startResult.message].join("\n"), 500)
+  }
+  const text = [formatKillResult(killResult), formatStartResult(startResult)].join("\n")
+  return c.text(text, isStartError(startResult) ? 500 : 200)
 })

package/cli/src/routes/dex/route.ts

@@ -0,0 +1,66 @@
+import { z } from "zod"
+import { factory } from "@/factory"
+import { bodyValidator } from "@/lib/body-validator"
+import { helpGuard } from "@/lib/help-guard"
+import type { MinionRarity } from "@lib/engine/collection/species"
+
+const schema = z.strictObject({})
+
+export const help = `Usage: minion dex
+
+実績とミニオン図鑑を表示する。セッション数・同時実行数・時間帯・トークン消費量を
+元に実績を解除し、条件を満たすと珍しいミニオンが出現する。`
+
+export default factory.createHandlers(helpGuard(help), bodyValidator(schema), async (c) => {
+  const minion = c.env.minion
+  const stats = minion.stats.collect()
+  if (stats instanceof Error) return c.text(stats.message, 500)
+  const evaluation = minion.collection.evaluate(stats)
+  if (evaluation instanceof Error) return c.text(evaluation.message, 500)
+  const { achievements, species } = minion.collection.dex()
+
+  const lines: string[] = []
+
+  lines.push(
+    `現在のミニオン: ${evaluation.species.name} (${rarityLabel(evaluation.species.rarity)})`,
+  )
+
+  const newlyUnlocked = evaluation.newlyUnlockedAchievements
+  if (newlyUnlocked.length > 0) {
+    lines.push("")
+    lines.push("実績を解除した!")
+    for (const a of newlyUnlocked) lines.push(`  ★ ${a.name} — ${a.description}`)
+  }
+  if (evaluation.newlyDiscoveredSpecies.length > 0) {
+    lines.push("")
+    for (const discovered of evaluation.newlyDiscoveredSpecies) {
+      lines.push(`新しいミニオンを発見した! ${discovered.name} (${rarityLabel(discovered.rarity)})`)
+    }
+  }
+
+  const unlockedCount = achievements.filter((a) => a.unlocked).length
+  lines.push("")
+  lines.push(`== 実績 (${unlockedCount}/${achievements.length}) ==`)
+  for (const a of achievements) {
+    const mark = a.unlocked ? "[x]" : "[ ]"
+    const detail = a.unlocked ? a.description : "???"
+    lines.push(`${mark} ${a.name} — ${detail}`)
+  }
+
+  const discoveredCount = species.filter((s) => s.discovered).length
+  lines.push("")
+  lines.push(`== ミニオン図鑑 (${discoveredCount}/${species.length}) ==`)
+  for (const s of species) {
+    const mark = s.discovered ? "[x]" : "[ ]"
+    const label = s.discovered
+      ? `${s.name} (${rarityLabel(s.rarity)}) — ${s.description}`
+      : `??? (${rarityLabel(s.rarity)})`
+    lines.push(`${mark} ${label}`)
+  }
+
+  return c.text(lines.join("\n"))
+})
+
+function rarityLabel(rarity: MinionRarity): string {
+  return rarity === "rare" ? "レア" : "コモン"
+}

package/cli/src/routes/kill/route.ts

@@ -1,15 +1,17 @@
-import { zValidator } from "@hono/zod-validator"
 import { z } from "zod"
 import { factory } from "@/factory"
+import { bodyValidator } from "@/lib/body-validator"
+import { formatKillResult } from "@/lib/format"
 import { helpGuard } from "@/lib/help-guard"
-import { killApp } from "@/lib/process"
 
-const schema = z.object({})
+const schema = z.strictObject({})
 
 export const help = `Usage: minion kill
 
 アプリとgatewayを停止する。`
 
-export default factory.createHandlers(helpGuard(help), zValidator("json", schema), async (c) => {
-  return c.text(killApp())
+export default factory.createHandlers(helpGuard(help), bodyValidator(schema), async (c) => {
+  const result = c.env.minion.app.kill()
+  if (result instanceof Error) return c.text(result.message, 500)
+  return c.text(formatKillResult(result))
 })

package/cli/src/routes/not-found.ts

@@ -2,7 +2,7 @@ import type { NotFoundHandler } from "hono"
 
 export const notFound: NotFoundHandler = (c) => {
   return c.text(
-    `使い方: minion [start|dev|kill|reboot|status|config]\n不明なコマンド: ${c.req.path}`,
+    `使い方: minion [start|dev|kill|reboot|status|dex|config]\n不明なコマンド: ${c.req.path}`,
     404,
   )
 }

package/cli/src/routes/reboot/route.ts

@@ -1,17 +1,22 @@
-import { zValidator } from "@hono/zod-validator"
 import { z } from "zod"
 import { factory } from "@/factory"
+import { bodyValidator } from "@/lib/body-validator"
+import { formatKillResult, formatStartResult, isStartError } from "@/lib/format"
 import { helpGuard } from "@/lib/help-guard"
-import { killApp, startApp } from "@/lib/process"
 
-const schema = z.object({})
+const schema = z.strictObject({})
 
 export const help = `Usage: minion reboot
 
 一旦停止してから、リリースビルドで起動し直す。`
 
-export default factory.createHandlers(helpGuard(help), zValidator("json", schema), async (c) => {
-  const killMessage = killApp()
-  const startMessage = await startApp(false)
-  return c.text([killMessage, startMessage].join("\n"))
+export default factory.createHandlers(helpGuard(help), bodyValidator(schema), async (c) => {
+  const killResult = c.env.minion.app.kill()
+  if (killResult instanceof Error) return c.text(killResult.message, 500)
+  const startResult = await c.env.minion.app.start()
+  if (startResult instanceof Error) {
+    return c.text([formatKillResult(killResult), startResult.message].join("\n"), 500)
+  }
+  const text = [formatKillResult(killResult), formatStartResult(startResult)].join("\n")
+  return c.text(text, isStartError(startResult) ? 500 : 200)
 })

package/cli/src/routes/start/route.ts

@@ -1,16 +1,17 @@
-import { zValidator } from "@hono/zod-validator"
 import { z } from "zod"
 import { factory } from "@/factory"
+import { bodyValidator } from "@/lib/body-validator"
+import { formatStartResult, isStartError } from "@/lib/format"
 import { helpGuard } from "@/lib/help-guard"
-import { startApp } from "@/lib/process"
 
-const schema = z.object({})
+const schema = z.strictObject({})
 
 export const help = `Usage: minion start
 
 アプリをリリースビルドで起動する。すでに起動中なら何もしない。`
 
-export default factory.createHandlers(helpGuard(help), zValidator("json", schema), async (c) => {
-  const message = await startApp(false)
-  return c.text(message)
+export default factory.createHandlers(helpGuard(help), bodyValidator(schema), async (c) => {
+  const result = await c.env.minion.app.start()
+  if (result instanceof Error) return c.text(result.message, 500)
+  return c.text(formatStartResult(result), isStartError(result) ? 500 : 200)
 })

package/cli/src/routes/status/route.ts

@@ -1,15 +1,15 @@
-import { zValidator } from "@hono/zod-validator"
 import { z } from "zod"
 import { factory } from "@/factory"
+import { bodyValidator } from "@/lib/body-validator"
+import { formatAppStatus } from "@/lib/format"
 import { helpGuard } from "@/lib/help-guard"
-import { statusApp } from "@/lib/process"
 
-const schema = z.object({})
+const schema = z.strictObject({})
 
 export const help = `Usage: minion status
 
 アプリとgatewayの起動状況を表示する。`
 
-export default factory.createHandlers(helpGuard(help), zValidator("json", schema), async (c) => {
-  return c.text(statusApp())
+export default factory.createHandlers(helpGuard(help), bodyValidator(schema), async (c) => {
+  return c.text(formatAppStatus(c.env.minion.app.status()))
 })

package/lib/engine/app/app-paths.ts

@@ -0,0 +1,46 @@
+import { homedir } from "node:os"
+import { join } from "node:path"
+
+export type MinionPaths = {
+  /** `~/.minion` by default — state lives here independent of where the package itself is installed. */
+  dataDir: string
+  /** The `swift/` directory containing the Xcode Swift Package. */
+  appRoot: string
+  buildPath: string
+  binPath: string
+  debugBinPath: string
+  dataFile: string
+  pidFile: string
+  gatewayPidFile: string
+  configFile: string
+  sessionStatsFile: string
+  usageScanFile: string
+  collectionFile: string
+}
+
+type Props = {
+  /** The directory containing `swift/` (the package root). */
+  packageRoot: string
+  dataDir?: string
+}
+
+export function resolveMinionPaths(props: Props): MinionPaths {
+  const dataDir = props.dataDir ?? join(homedir(), ".minion")
+  const appRoot = join(props.packageRoot, "swift")
+  const buildPath = join(dataDir, "build")
+
+  return {
+    dataDir,
+    appRoot,
+    buildPath,
+    binPath: join(buildPath, "release", "open-minion"),
+    debugBinPath: join(buildPath, "debug", "open-minion"),
+    dataFile: join(dataDir, "data.json"),
+    pidFile: join(dataDir, "pid"),
+    gatewayPidFile: join(dataDir, "gateway.pid"),
+    configFile: join(dataDir, "config.json"),
+    sessionStatsFile: join(dataDir, "session-stats.json"),
+    usageScanFile: join(dataDir, "usage-scan.json"),
+    collectionFile: join(dataDir, "collection.json"),
+  }
+}