@shigureni/minion 0.1.0 → 0.3.0

package/lib/engine/collection/species.ts

@@ -0,0 +1,275 @@
+import { isFullMoon, isNewMoon } from "@lib/engine/collection/moon"
+import type { StatsSnapshot } from "@lib/engine/stats/stats-snapshot"
+
+export type MinionRarity = "common" | "rare"
+
+export type MinionSpecies = {
+  id: string
+  name: string
+  rarity: MinionRarity
+  description: string
+  condition: (stats: StatsSnapshot) => boolean
+  /**
+   * Opaque reference to this species' art (a sprite path, bundle key, URL —
+   * whatever scheme the host app's renderer uses). This library never reads
+   * or interprets it; it just carries it through `dex()` for a host to
+   * consume. Left `undefined` in the built-in catalog — pass your own
+   * catalog (see `MinionCollectionTracker`'s `species` prop) to fill it in.
+   */
+  asset?: string
+}
+
+/**
+ * The built-in minion species catalog. `resolveSpecies` picks the first
+ * entry whose condition matches, so order is priority: rare/specific
+ * conditions are listed first, and the five time-of-day commons — which
+ * together cover every hour — sit last as the guaranteed fallback.
+ *
+ * This is only the default; pass a custom `species` array to
+ * `MinionCollectionTracker` (or `Minion`) to replace it entirely — e.g. to
+ * add your own species, retheme the built-ins, or attach real `asset`
+ * references once art exists.
+ */
+export const DEFAULT_MINION_SPECIES: MinionSpecies[] = [
+  {
+    id: "zorome",
+    name: "ゾロめミニオン",
+    rarity: "rare",
+    description: "時計が11:11か22:22を指す瞬間だけ現れる。",
+    condition: (s) => {
+      const minute = s.now.getMinutes()
+      return (s.hour === 11 && minute === 11) || (s.hour === 22 && minute === 22)
+    },
+  },
+  {
+    id: "full-moon",
+    name: "まんげつミニオン",
+    rarity: "rare",
+    description: "満月の夜(20時〜5時)に現れる。",
+    condition: (s) =>
+      isFullMoon(s.now) && (s.timeBucket === "night" || s.timeBucket === "lateNight"),
+  },
+  {
+    id: "new-moon",
+    name: "しんげつミニオン",
+    rarity: "rare",
+    description: "新月の深夜、月のない暗い夜に現れる。",
+    condition: (s) => isNewMoon(s.now) && s.timeBucket === "lateNight",
+  },
+  {
+    id: "mega-swarm",
+    name: "だいぐんせいミニオン",
+    rarity: "rare",
+    description: "同時に10以上のセッションが動く修羅場に現れる。",
+    condition: (s) => s.currentConcurrentSessions >= 10,
+  },
+  {
+    id: "swarm",
+    name: "ぐんせいミニオン",
+    rarity: "rare",
+    description: "同時に5つ以上のセッションが動いているときだけ現れる。",
+    condition: (s) => s.currentConcurrentSessions >= 5,
+  },
+  {
+    id: "overdrive",
+    name: "オーバードライブミニオン",
+    rarity: "rare",
+    description: "同時に3つ以上のセッションが動いているときに現れる。",
+    condition: (s) => s.currentConcurrentSessions >= 3,
+  },
+  {
+    id: "insomniac",
+    name: "ふみんミニオン",
+    rarity: "rare",
+    description: "深夜(0時〜5時)にセッションを動かしていると現れる。",
+    condition: (s) => s.timeBucket === "lateNight" && s.currentConcurrentSessions >= 1,
+  },
+  {
+    id: "morning-active",
+    name: "あさかつミニオン",
+    rarity: "rare",
+    description: "朝(5時〜10時)にセッションを動かしていると現れる。",
+    condition: (s) => s.timeBucket === "morning" && s.currentConcurrentSessions >= 1,
+  },
+  {
+    id: "lunch-break",
+    name: "おひるミニオン",
+    rarity: "rare",
+    description: "お昼(12時台)にセッションを動かしていると現れる。",
+    condition: (s) => s.hour === 12 && s.currentConcurrentSessions >= 1,
+  },
+  {
+    id: "twins",
+    name: "ふたごミニオン",
+    rarity: "rare",
+    description: "同時に2つのセッションが動いていると現れる。",
+    condition: (s) => s.currentConcurrentSessions >= 2,
+  },
+  {
+    id: "legend",
+    name: "でんせつミニオン",
+    rarity: "rare",
+    description: "累計1億トークンを消費したでんせつのもとに現れる。",
+    condition: (s) => s.tokensTotal >= 100_000_000,
+  },
+  {
+    id: "torrent",
+    name: "トレントミニオン",
+    rarity: "rare",
+    description: "1週間で500万トークンを消費すると現れる。",
+    condition: (s) => s.tokensThisWeek >= 5_000_000,
+  },
+  {
+    id: "golden",
+    name: "こがねミニオン",
+    rarity: "rare",
+    description: "累計1000万トークンを消費した猛者に現れる。",
+    condition: (s) => s.tokensTotal >= 10_000_000,
+  },
+  {
+    id: "big-spender",
+    name: "だいしょうひミニオン",
+    rarity: "rare",
+    description: "1日で100万トークンを消費すると現れる。",
+    condition: (s) => s.tokensToday >= 1_000_000,
+  },
+  {
+    id: "glutton",
+    name: "おおぐいミニオン",
+    rarity: "rare",
+    description: "1日で30万トークンを消費すると現れる。",
+    condition: (s) => s.tokensToday >= 300_000,
+  },
+  {
+    id: "perfect-attendance",
+    name: "かいきんミニオン",
+    rarity: "rare",
+    description: "30日連続でセッションを実行していると現れる。",
+    condition: (s) => s.currentStreakDays >= 30,
+  },
+  {
+    id: "marathon",
+    name: "マラソンミニオン",
+    rarity: "rare",
+    description: "7日連続でセッションを実行していると現れる。",
+    condition: (s) => s.currentStreakDays >= 7,
+  },
+  {
+    id: "three-day-streak",
+    name: "みっかミニオン",
+    rarity: "rare",
+    description: "3日連続でセッションを実行していると現れる。みっかぼうず卒業。",
+    condition: (s) => s.currentStreakDays >= 3,
+  },
+  {
+    id: "month-end",
+    name: "しめきりミニオン",
+    rarity: "rare",
+    description: "月末の日に現れる。しめきりは大丈夫?",
+    condition: (s) =>
+      new Date(s.now.getFullYear(), s.now.getMonth(), s.now.getDate() + 1).getDate() === 1,
+  },
+  {
+    id: "friday-night",
+    name: "きんようミニオン",
+    rarity: "rare",
+    description: "金曜の夜(20時〜24時)にセッションを動かしていると現れる。",
+    condition: (s) =>
+      s.now.getDay() === 5 && s.timeBucket === "night" && s.currentConcurrentSessions >= 1,
+  },
+  {
+    id: "sunday-worker",
+    name: "にちようミニオン",
+    rarity: "rare",
+    description: "日曜にセッションを動かしていると現れる。",
+    condition: (s) => s.now.getDay() === 0 && s.currentConcurrentSessions >= 1,
+  },
+  {
+    id: "devoted",
+    name: "いちずミニオン",
+    rarity: "rare",
+    description: "累計50セッションを超えてもプロジェクトがひとつだけだと現れる。",
+    condition: (s) => s.uniqueProjectsSeen === 1 && s.totalSessionsSeen >= 50,
+  },
+  {
+    id: "wanderer",
+    name: "ほうろうミニオン",
+    rarity: "rare",
+    description: "10個以上の異なるプロジェクトを渡り歩くと現れる。",
+    condition: (s) => s.uniqueProjectsSeen >= 10,
+  },
+  {
+    id: "juggler",
+    name: "かけもちミニオン",
+    rarity: "rare",
+    description: "3つ以上のプロジェクトをかけもちすると現れる。",
+    condition: (s) => s.uniqueProjectsSeen >= 3,
+  },
+  {
+    id: "veteran",
+    name: "ベテランミニオン",
+    rarity: "rare",
+    description: "累計100セッションを超えたころに現れる。",
+    condition: (s) => s.totalSessionsSeen >= 100,
+  },
+  {
+    id: "rookie",
+    name: "ひよこミニオン",
+    rarity: "rare",
+    description: "累計10セッションを実行したかけだしに現れる。",
+    condition: (s) => s.totalSessionsSeen >= 10,
+  },
+  {
+    id: "late-night",
+    name: "しんやミニオン",
+    rarity: "common",
+    description: "深夜(0時〜5時)に現れる。",
+    condition: (s) => s.timeBucket === "lateNight",
+  },
+  {
+    id: "morning",
+    name: "あさミニオン",
+    rarity: "common",
+    description: "朝(5時〜10時)に現れる。",
+    condition: (s) => s.timeBucket === "morning",
+  },
+  {
+    id: "day",
+    name: "ひなたミニオン",
+    rarity: "common",
+    description: "日中(10時〜17時)に現れる。",
+    condition: (s) => s.timeBucket === "day",
+  },
+  {
+    id: "evening",
+    name: "ゆうやけミニオン",
+    rarity: "common",
+    description: "夕方(17時〜20時)に現れる。",
+    condition: (s) => s.timeBucket === "evening",
+  },
+  {
+    id: "night",
+    name: "よふかしミニオン",
+    rarity: "common",
+    description: "夜(20時〜24時)に現れる。",
+    condition: (s) => s.timeBucket === "night",
+  },
+]
+
+/**
+ * The species that manifests right now, per `stats`. Checks `catalog` in
+ * order and returns the first match — defaults to `DEFAULT_MINION_SPECIES`,
+ * whose time-of-day commons cover every hour so it always resolves. A custom
+ * catalog must include an unconditional (or otherwise fully-covering)
+ * fallback entry, or this returns an Error when nothing matches.
+ */
+export function resolveSpecies(
+  stats: StatsSnapshot,
+  catalog: MinionSpecies[] = DEFAULT_MINION_SPECIES,
+): MinionSpecies | Error {
+  const found = catalog.find((species) => species.condition(stats))
+  if (!found) {
+    return new Error("no minion species matched — the catalog needs a fully-covering fallback")
+  }
+  return found
+}

package/lib/engine/config/config-store.ts

@@ -0,0 +1,36 @@
+import { z } from "zod"
+import type { MinionFileSystem } from "@lib/engine/fs/file-system"
+import { JsonFileStore } from "@lib/engine/fs/json-file-store"
+
+type Props = {
+  fs: MinionFileSystem
+  path: string
+}
+
+const schema = z.record(z.string(), z.string())
+
+const EMPTY: Record<string, string> = {}
+
+/** Reads/writes the flat string-keyed `config.json` (`minion config get/set/list`). */
+export class MinionConfigStore {
+  private readonly store: JsonFileStore<Record<string, string>>
+
+  constructor(props: Props) {
+    this.store = new JsonFileStore({ fs: props.fs, path: props.path, schema, defaultValue: EMPTY })
+  }
+
+  list(): Record<string, string> {
+    return this.store.read()
+  }
+
+  /** Returns `undefined` when the key is unset — distinguishable from an empty-string value. */
+  get(key: string): string | undefined {
+    return this.list()[key]
+  }
+
+  set(key: string, value: string): Error | null {
+    const config = this.list()
+    config[key] = value
+    return this.store.write(config)
+  }
+}

package/lib/engine/errors.ts

@@ -0,0 +1,20 @@
+/**
+ * Error-as-value helpers. The library never throws across its public surface —
+ * fallible operations return `T | Error`, checked with `instanceof Error`.
+ * These helpers convert the throwing world (node:fs, Bun, JSON.parse) into
+ * that convention at the boundary.
+ */
+
+/** Normalizes a caught value into an Error without losing the original message. */
+export function toError(thrown: unknown): Error {
+  return thrown instanceof Error ? thrown : new Error(String(thrown))
+}
+
+/** `JSON.parse` without the throw. JSON can never encode an `Error` instance, so `instanceof Error` cleanly separates failure. */
+export function safeJsonParse(text: string): unknown {
+  try {
+    return JSON.parse(text)
+  } catch (thrown) {
+    return toError(thrown)
+  }
+}

package/lib/engine/fs/file-system.ts

@@ -0,0 +1,31 @@
+export type MinionFileStat = {
+  mtimeMs: number
+}
+
+/**
+ * Filesystem boundary used everywhere minion reads or writes.
+ * Default is NodeMinionFileSystem (real `node:fs`); MemoryMinionFileSystem
+ * provides a sandbox for tests and embedded use.
+ *
+ * Fallible operations return `T | Error` (checked with `instanceof Error`)
+ * instead of throwing — implementations must catch their runtime's exceptions
+ * at this boundary.
+ */
+export abstract class MinionFileSystem {
+  abstract existsSync(path: string): boolean
+  abstract readFileSync(path: string): string | Error
+  abstract writeFileSync(path: string, data: string): Error | null
+  abstract mkdirSync(path: string, options?: { recursive?: boolean }): Error | null
+  abstract rmSync(path: string, options?: { force?: boolean }): Error | null
+  abstract readdirSync(path: string): string[] | Error
+  /** Recursively list files under `path`, as `/`-joined paths relative to `path`. */
+  abstract readdirRecursiveSync(path: string): string[] | Error
+  /**
+   * Atomically create `path` only if it does not already exist (O_EXCL).
+   * Returns `true` if this call created it, `false` if it already existed.
+   * Used for the start-lock / pid-file singleton guard.
+   */
+  abstract createExclusiveSync(path: string): boolean
+  /** Used to detect whether a file changed since it was last scanned (e.g. transcript token-usage scanning). */
+  abstract statSync(path: string): MinionFileStat | Error
+}

package/lib/engine/fs/json-file-store.ts

@@ -0,0 +1,57 @@
+import { dirname } from "node:path"
+import type { z } from "zod"
+import { safeJsonParse } from "@lib/engine/errors"
+import type { MinionFileSystem } from "@lib/engine/fs/file-system"
+
+type Props<T> = {
+  fs: MinionFileSystem
+  path: string
+  /**
+   * Runtime shape guard for what comes back off disk — `JSON.parse` alone
+   * would let a hand-edited or version-skewed file flow through as `T` and
+   * crash later. Give evolving schemas per-field `.catch()` defaults so a
+   * file written by an older version backfills instead of falling back wholesale.
+   */
+  schema: z.ZodType<T>
+  defaultValue: T
+}
+
+/**
+ * Reads/writes a single JSON value at `path`, creating parent directories as
+ * needed. Falls back to a fresh clone of `defaultValue` when the file is
+ * missing, unreadable, corrupt, or fails `schema` validation. Shared by every
+ * `~/.minion/*.json` store (config, session stats, token usage, collection)
+ * to avoid re-deriving the same read/parse/validate/write boilerplate in each one.
+ */
+export class JsonFileStore<T> {
+  private readonly fs: MinionFileSystem
+  private readonly path: string
+  private readonly schema: z.ZodType<T>
+  private readonly defaultValue: T
+
+  constructor(props: Props<T>) {
+    this.fs = props.fs
+    this.path = props.path
+    this.schema = props.schema
+    this.defaultValue = props.defaultValue
+  }
+
+  read(): T {
+    if (!this.fs.existsSync(this.path)) return structuredClone(this.defaultValue)
+
+    const content = this.fs.readFileSync(this.path)
+    if (content instanceof Error) return structuredClone(this.defaultValue)
+
+    const json = safeJsonParse(content)
+    if (json instanceof Error) return structuredClone(this.defaultValue)
+
+    const result = this.schema.safeParse(json)
+    return result.success ? result.data : structuredClone(this.defaultValue)
+  }
+
+  write(value: T): Error | null {
+    const mkdirError = this.fs.mkdirSync(dirname(this.path), { recursive: true })
+    if (mkdirError) return mkdirError
+    return this.fs.writeFileSync(this.path, JSON.stringify(value, null, 2))
+  }
+}

package/lib/engine/fs/memory-file-system.ts

@@ -0,0 +1,106 @@
+import { type MinionFileStat, MinionFileSystem } from "@lib/engine/fs/file-system"
+
+type Props = {
+  dirs?: string[]
+  files?: Record<string, string>
+  mtimes?: Record<string, number>
+  /** Clock used to stamp mtimes on write, when a file's mtime isn't set explicitly via `setMtime`. Defaults to `Date.now`. */
+  now?: () => number
+}
+
+export class MemoryMinionFileSystem extends MinionFileSystem {
+  private readonly dirs: Set<string>
+  private readonly files: Map<string, string>
+  private readonly mtimes: Map<string, number>
+  private readonly now: () => number
+
+  constructor(props: Props = {}) {
+    super()
+    this.dirs = new Set(props.dirs ?? [])
+    this.files = new Map(Object.entries(props.files ?? {}))
+    this.mtimes = new Map(Object.entries(props.mtimes ?? {}))
+    this.now = props.now ?? (() => Date.now())
+  }
+
+  existsSync(path: string): boolean {
+    return this.dirs.has(path) || this.files.has(path)
+  }
+
+  readFileSync(path: string): string | Error {
+    const data = this.files.get(path)
+    if (data === undefined) return new Error(`not found: ${path}`)
+    return data
+  }
+
+  writeFileSync(path: string, data: string): Error | null {
+    this.files.set(path, data)
+    this.touch(path)
+    return null
+  }
+
+  mkdirSync(path: string, options?: { recursive?: boolean }): Error | null {
+    void options
+    this.dirs.add(path)
+    return null
+  }
+
+  rmSync(path: string, options?: { force?: boolean }): Error | null {
+    if (!options?.force && !this.existsSync(path)) {
+      return new Error(`not found: ${path}`)
+    }
+    this.files.delete(path)
+    this.dirs.delete(path)
+    this.mtimes.delete(path)
+    return null
+  }
+
+  readdirSync(path: string): string[] | Error {
+    const prefix = path.endsWith("/") ? path : `${path}/`
+    const names = new Set<string>()
+
+    for (const file of this.files.keys()) {
+      if (!file.startsWith(prefix)) continue
+      const rest = file.slice(prefix.length)
+      const [first] = rest.split("/")
+      if (first) names.add(first)
+    }
+
+    return Array.from(names)
+  }
+
+  /** Returns file paths only (no directory entries), unlike node:fs's recursive readdirSync. */
+  readdirRecursiveSync(path: string): string[] | Error {
+    const prefix = path.endsWith("/") ? path : `${path}/`
+    const names: string[] = []
+
+    for (const file of this.files.keys()) {
+      if (!file.startsWith(prefix)) continue
+      names.push(file.slice(prefix.length))
+    }
+
+    return names
+  }
+
+  createExclusiveSync(path: string): boolean {
+    if (this.files.has(path)) return false
+    this.files.set(path, "")
+    this.touch(path)
+    return true
+  }
+
+  statSync(path: string): MinionFileStat | Error {
+    if (!this.files.has(path)) return new Error(`not found: ${path}`)
+    const mtimeMs = this.mtimes.get(path)
+    if (mtimeMs === undefined) this.touch(path)
+    return { mtimeMs: this.mtimes.get(path) ?? this.now() }
+  }
+
+  /** Sets a file's mtime explicitly — useful for asserting "unchanged since last scan" behavior in tests. */
+  setMtime(path: string, mtimeMs: number): void {
+    this.mtimes.set(path, mtimeMs)
+  }
+
+  private touch(path: string): void {
+    this.mtimes.set(path, this.now())
+  }
+}

package/lib/engine/fs/node-file-system.ts

@@ -0,0 +1,87 @@
+import {
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs"
+import { toError } from "@lib/engine/errors"
+import { type MinionFileStat, MinionFileSystem } from "@lib/engine/fs/file-system"
+
+export class NodeMinionFileSystem extends MinionFileSystem {
+  existsSync(path: string): boolean {
+    return existsSync(path)
+  }
+
+  readFileSync(path: string): string | Error {
+    try {
+      return readFileSync(path, "utf8")
+    } catch (thrown) {
+      return toError(thrown)
+    }
+  }
+
+  writeFileSync(path: string, data: string): Error | null {
+    try {
+      writeFileSync(path, data)
+      return null
+    } catch (thrown) {
+      return toError(thrown)
+    }
+  }
+
+  mkdirSync(path: string, options?: { recursive?: boolean }): Error | null {
+    try {
+      mkdirSync(path, { recursive: options?.recursive ?? false })
+      return null
+    } catch (thrown) {
+      return toError(thrown)
+    }
+  }
+
+  rmSync(path: string, options?: { force?: boolean }): Error | null {
+    try {
+      rmSync(path, { force: options?.force ?? false })
+      return null
+    } catch (thrown) {
+      return toError(thrown)
+    }
+  }
+
+  readdirSync(path: string): string[] | Error {
+    try {
+      return readdirSync(path)
+    } catch (thrown) {
+      return toError(thrown)
+    }
+  }
+
+  readdirRecursiveSync(path: string): string[] | Error {
+    try {
+      return readdirSync(path, { recursive: true }) as string[]
+    } catch (thrown) {
+      return toError(thrown)
+    }
+  }
+
+  createExclusiveSync(path: string): boolean {
+    try {
+      closeSync(openSync(path, "wx"))
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  statSync(path: string): MinionFileStat | Error {
+    try {
+      return { mtimeMs: statSync(path).mtimeMs }
+    } catch (thrown) {
+      return toError(thrown)
+    }
+  }
+}

package/lib/engine/gateway/gateway-daemon.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env bun
+import { Minion } from "@lib/minion"
+
+const minion = new Minion()
+const port = Number(process.env.MINION_GATEWAY_PORT) || undefined
+
+const handle = minion.gatewayServer({ port }).start()
+
+if (handle instanceof Error) {
+  console.error(`gateway failed to start: ${handle.message}`)
+  process.exit(1)
+}
+
+console.log(`gateway listening on :${handle.port}`)

package/lib/engine/gateway/gateway-routes.ts

@@ -0,0 +1,17 @@
+import { Hono } from "hono"
+import type { PetBehaviorEngine } from "@lib/engine/gateway/pet-behavior"
+
+/**
+ * GET /sessions — the current pet snapshot as JSON. Kept as a plain Hono app
+ * (rather than inlined into `Bun.serve`'s fetch handler) so it can be
+ * exercised with `.request()` in tests without a real Bun server. The `/ws`
+ * upgrade path lives in gateway-server.ts since it needs the raw Bun server
+ * instance to call `server.upgrade(req)`.
+ */
+export function buildGatewayRoutes(engine: PetBehaviorEngine) {
+  const app = new Hono()
+  app.get("/sessions", (c) => c.json({ sessions: engine.snapshot() }))
+  return app
+}
+
+export type GatewayRoutesApp = ReturnType<typeof buildGatewayRoutes>