@shigureni/minion 0.1.0 → 0.3.0

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

@@ -0,0 +1,235 @@
+import { z } from "zod"
+import { safeJsonParse } from "@lib/engine/errors"
+import type { MinionFileSystem } from "@lib/engine/fs/file-system"
+import type { MinionProcessRunner } from "@lib/engine/process/process-runner"
+import type { MinionPaths } from "@lib/engine/app/app-paths"
+import { computeSourceHash } from "@lib/engine/app/source-hash"
+
+export type MinionBuildKind = "debug" | "release"
+
+/** Progress notification emitted while `start()` runs. Presentation belongs to the caller. */
+export type MinionAppEvent = { type: "build-start"; build: MinionBuildKind }
+
+export type MinionStartResult =
+  | { kind: "started"; pid: number }
+  | { kind: "already-running"; pid: number }
+  | { kind: "build-failed"; build: MinionBuildKind }
+  | { kind: "lock-conflict" }
+
+export type MinionKillResult = { kind: "killed"; pid: number } | { kind: "not-running" }
+
+export type MinionProcessStatus = {
+  running: boolean
+  /** Last recorded pid, if a pid file exists — may belong to a dead process when `running` is false. */
+  pid: number | null
+}
+
+export type MinionAppStatus = {
+  app: MinionProcessStatus
+  gateway: MinionProcessStatus
+}
+
+export type MinionStartOptions = {
+  /** Build and run the debug binary instead of the cached release build. */
+  debug?: boolean
+}
+
+type Props = {
+  fs: MinionFileSystem
+  process: MinionProcessRunner
+  paths: MinionPaths
+  /** Command used to launch the gateway daemon, e.g. `["bun", "/path/to/gateway-daemon.ts"]`. */
+  gatewayCommand: string[]
+  /** Progress events (build started, ...). Defaults to a no-op — the library never writes to stdout itself. */
+  onEvent?: (event: MinionAppEvent) => void
+}
+
+const buildDataSchema = z.object({ sourceHash: z.string() })
+
+type BuildData = z.infer<typeof buildDataSchema>
+
+/**
+ * Build/start/kill/status for the Swift app and its companion gateway daemon.
+ *
+ * Expected outcomes ("already running", "build failed", ...) come back as
+ * `MinionStartResult` / `MinionKillResult` kinds; unexpected IO failures
+ * (unwritable state dir, missing executable, ...) come back as an `Error`
+ * value. Nothing throws.
+ */
+export class MinionAppRunner {
+  private readonly fs: MinionFileSystem
+  private readonly process: MinionProcessRunner
+  private readonly paths: MinionPaths
+  private readonly gatewayCommand: string[]
+  private readonly onEvent: (event: MinionAppEvent) => void
+
+  constructor(props: Props) {
+    this.fs = props.fs
+    this.process = props.process
+    this.paths = props.paths
+    this.gatewayCommand = props.gatewayCommand
+    this.onEvent = props.onEvent ?? (() => {})
+  }
+
+  async start(options: MinionStartOptions = {}): Promise<MinionStartResult | Error> {
+    const debug = options.debug ?? false
+
+    const existingPid = this.readPid(this.paths.pidFile)
+    if (existingPid !== null) {
+      if (this.process.isAlive(existingPid)) {
+        return { kind: "already-running", pid: existingPid }
+      }
+      const rmError = this.fs.rmSync(this.paths.pidFile, { force: true })
+      if (rmError) return rmError
+    }
+
+    const lock = this.acquireStartLock()
+    if (lock instanceof Error) return lock
+    if (!lock) return { kind: "lock-conflict" }
+
+    const build: MinionBuildKind = debug ? "debug" : "release"
+    const binPath = debug ? this.paths.debugBinPath : this.paths.binPath
+
+    if (debug) {
+      const built = await this.build(build)
+      if (built !== true) return this.releaseLockAfter(built, build)
+    } else {
+      // A hash failure (unreadable source tree) just means "hash unknown":
+      // build unconditionally and skip recording, so the next start re-checks.
+      const currentHash = computeSourceHash({ fs: this.fs, appRoot: this.paths.appRoot })
+      const buildData = this.readBuildData()
+      if (!this.fs.existsSync(binPath) || buildData?.sourceHash !== currentHash) {
+        const built = await this.build(build)
+        if (built !== true) return this.releaseLockAfter(built, build)
+        if (typeof currentHash === "string") {
+          const writeError = this.writeBuildData({ sourceHash: currentHash })
+          if (writeError) return this.releaseLockAfter(writeError, build)
+        }
+      }
+    }
+
+    const pid = this.process.spawnDetached([binPath], { cwd: this.paths.appRoot })
+    if (pid instanceof Error) return this.releaseLockAfter(pid, build)
+
+    const pidWriteError = this.fs.writeFileSync(this.paths.pidFile, String(pid))
+    if (pidWriteError) {
+      // Untracked would mean unkillable — take the app back down.
+      this.process.kill(pid, "SIGTERM")
+      return this.releaseLockAfter(pidWriteError, build)
+    }
+
+    const gatewayError = this.startGateway()
+    if (gatewayError) return gatewayError
+
+    return { kind: "started", pid }
+  }
+
+  kill(): MinionKillResult | Error {
+    const gatewayError = this.killGateway()
+    if (gatewayError) return gatewayError
+
+    const pid = this.readPid(this.paths.pidFile)
+    if (!pid || !this.process.isAlive(pid)) {
+      if (this.fs.existsSync(this.paths.pidFile)) {
+        const rmError = this.fs.rmSync(this.paths.pidFile, { force: true })
+        if (rmError) return rmError
+      }
+      return { kind: "not-running" }
+    }
+
+    this.process.kill(pid, "SIGTERM")
+    const rmError = this.fs.rmSync(this.paths.pidFile, { force: true })
+    if (rmError) return rmError
+    return { kind: "killed", pid }
+  }
+
+  status(): MinionAppStatus {
+    return {
+      app: this.processStatus(this.paths.pidFile),
+      gateway: this.processStatus(this.paths.gatewayPidFile),
+    }
+  }
+
+  private processStatus(pidFile: string): MinionProcessStatus {
+    const pid = this.readPid(pidFile)
+    return { running: pid !== null && this.process.isAlive(pid), pid }
+  }
+
+  /** `true` on success, `{kind: "build-failed"}`-worthy `false` on a nonzero exit, `Error` when the build tool couldn't run at all. */
+  private async build(build: MinionBuildKind): Promise<true | false | Error> {
+    this.onEvent({ type: "build-start", build })
+    const args =
+      build === "debug"
+        ? ["swift", "build", "--scratch-path", this.paths.buildPath]
+        : ["swift", "build", "-c", "release", "--scratch-path", this.paths.buildPath]
+
+    const exitCode = await this.process.runInherit(args, { cwd: this.paths.appRoot })
+    if (exitCode instanceof Error) return exitCode
+    return exitCode === 0
+  }
+
+  /** Removes the start-lock pid file, then maps a mid-start failure to its result/Error. */
+  private releaseLockAfter(
+    failure: false | Error,
+    build: MinionBuildKind,
+  ): MinionStartResult | Error {
+    this.fs.rmSync(this.paths.pidFile, { force: true })
+    return failure === false ? { kind: "build-failed", build } : failure
+  }
+
+  private startGateway(): Error | null {
+    const pid = this.readPid(this.paths.gatewayPidFile)
+    if (pid !== null && this.process.isAlive(pid)) return null
+
+    const mkdirError = this.fs.mkdirSync(this.paths.dataDir, { recursive: true })
+    if (mkdirError) return mkdirError
+
+    const spawnedPid = this.process.spawnDetached(this.gatewayCommand)
+    if (spawnedPid instanceof Error) return spawnedPid
+
+    const writeError = this.fs.writeFileSync(this.paths.gatewayPidFile, String(spawnedPid))
+    if (writeError) {
+      this.process.kill(spawnedPid, "SIGTERM")
+      return writeError
+    }
+    return null
+  }
+
+  private killGateway(): Error | null {
+    const pid = this.readPid(this.paths.gatewayPidFile)
+    if (pid !== null && this.process.isAlive(pid)) {
+      this.process.kill(pid, "SIGTERM")
+    }
+    return this.fs.rmSync(this.paths.gatewayPidFile, { force: true })
+  }
+
+  private acquireStartLock(): boolean | Error {
+    const mkdirError = this.fs.mkdirSync(this.paths.dataDir, { recursive: true })
+    if (mkdirError) return mkdirError
+    return this.fs.createExclusiveSync(this.paths.pidFile)
+  }
+
+  private readPid(pidFile: string): number | null {
+    if (!this.fs.existsSync(pidFile)) return null
+    const content = this.fs.readFileSync(pidFile)
+    if (content instanceof Error) return null
+    const pid = Number.parseInt(content.trim(), 10)
+    return Number.isNaN(pid) ? null : pid
+  }
+
+  private readBuildData(): BuildData | null {
+    if (!this.fs.existsSync(this.paths.dataFile)) return null
+    const content = this.fs.readFileSync(this.paths.dataFile)
+    if (content instanceof Error) return null
+    const json = safeJsonParse(content)
+    if (json instanceof Error) return null
+    const parsed = buildDataSchema.safeParse(json)
+    return parsed.success ? parsed.data : null
+  }
+
+  private writeBuildData(data: BuildData): Error | null {
+    const mkdirError = this.fs.mkdirSync(this.paths.dataDir, { recursive: true })
+    if (mkdirError) return mkdirError
+    return this.fs.writeFileSync(this.paths.dataFile, JSON.stringify(data, null, 2))
+  }
+}

package/lib/engine/app/source-hash.ts

@@ -0,0 +1,34 @@
+import { createHash } from "node:crypto"
+import { join } from "node:path"
+import type { MinionFileSystem } from "@lib/engine/fs/file-system"
+
+type Props = {
+  fs: MinionFileSystem
+  appRoot: string
+}
+
+/**
+ * Hashes `Package.swift` plus every `.swift` file under `Sources/`, so a release
+ * build can be skipped when the source tree hasn't changed since the last build.
+ * Returns an Error when the tree can't be read — callers treat that as "hash
+ * unknown", i.e. rebuild.
+ */
+export function computeSourceHash(props: Props): string | Error {
+  const sourcesRoot = join(props.appRoot, "Sources")
+
+  const entries = props.fs.readdirRecursiveSync(sourcesRoot)
+  if (entries instanceof Error) return entries
+
+  const files = [
+    join(props.appRoot, "Package.swift"),
+    ...entries.filter((file) => file.endsWith(".swift")).map((file) => join(sourcesRoot, file)),
+  ].sort()
+
+  const hash = createHash("sha256")
+  for (const file of files) {
+    const content = props.fs.readFileSync(file)
+    if (content instanceof Error) return content
+    hash.update(content)
+  }
+  return hash.digest("hex")
+}

package/lib/engine/collection/achievements.ts

@@ -0,0 +1,143 @@
+import type { StatsSnapshot } from "@lib/engine/stats/stats-snapshot"
+
+export type Achievement = {
+  id: string
+  name: string
+  description: string
+  condition: (stats: StatsSnapshot) => boolean
+  /**
+   * Opaque reference to this achievement's badge art. Same contract as
+   * `MinionSpecies.asset` — carried through untouched, `undefined` by
+   * default. Pass your own catalog (see `MinionCollectionTracker`'s
+   * `achievements` prop) to fill it in.
+   */
+  asset?: string
+}
+
+/**
+ * The built-in achievement catalog. Only the default — pass a custom
+ * `achievements` array to `MinionCollectionTracker` (or `Minion`) to replace
+ * it entirely.
+ */
+export const DEFAULT_ACHIEVEMENTS: Achievement[] = [
+  {
+    id: "first-session",
+    name: "はじめの一歩",
+    description: "はじめてセッションを実行した。",
+    condition: (s) => s.totalSessionsSeen >= 1,
+  },
+  {
+    id: "sessions-10",
+    name: "駆け出し",
+    description: "累計10セッションを実行した。",
+    condition: (s) => s.totalSessionsSeen >= 10,
+  },
+  {
+    id: "sessions-100",
+    name: "常連",
+    description: "累計100セッションを実行した。",
+    condition: (s) => s.totalSessionsSeen >= 100,
+  },
+  {
+    id: "sessions-1000",
+    name: "生粋のヘビーユーザー",
+    description: "累計1000セッションを実行した。",
+    condition: (s) => s.totalSessionsSeen >= 1000,
+  },
+  {
+    id: "concurrent-3",
+    name: "マルチタスカー",
+    description: "同時に3つのセッションを動かした。",
+    condition: (s) => s.maxConcurrentSessions >= 3,
+  },
+  {
+    id: "concurrent-5",
+    name: "並列処理の鬼",
+    description: "同時に5つのセッションを動かした。",
+    condition: (s) => s.maxConcurrentSessions >= 5,
+  },
+  {
+    id: "concurrent-10",
+    name: "オーケストレーター",
+    description: "同時に10のセッションを動かした。",
+    condition: (s) => s.maxConcurrentSessions >= 10,
+  },
+  {
+    id: "early-bird",
+    name: "早起き",
+    description: "朝(5時〜10時)にセッションを実行した。",
+    condition: (s) => s.timeBucket === "morning",
+  },
+  {
+    id: "night-owl",
+    name: "夜ふかし",
+    description: "夜(20時〜24時)にセッションを実行した。",
+    condition: (s) => s.timeBucket === "night",
+  },
+  {
+    id: "midnight-coder",
+    name: "深夜コーダー",
+    description: "深夜(0時〜5時)にセッションを実行した。",
+    condition: (s) => s.timeBucket === "lateNight",
+  },
+  {
+    id: "streak-7",
+    name: "一週間皆勤",
+    description: "7日連続でセッションを実行した。",
+    condition: (s) => s.longestStreakDays >= 7,
+  },
+  {
+    id: "streak-30",
+    name: "一ヶ月皆勤",
+    description: "30日連続でセッションを実行した。",
+    condition: (s) => s.longestStreakDays >= 30,
+  },
+  {
+    id: "projects-5",
+    name: "多趣味",
+    description: "5つの異なるプロジェクトで実行した。",
+    condition: (s) => s.uniqueProjectsSeen >= 5,
+  },
+  {
+    id: "projects-20",
+    name: "プロジェクトホッパー",
+    description: "20の異なるプロジェクトで実行した。",
+    condition: (s) => s.uniqueProjectsSeen >= 20,
+  },
+  {
+    id: "tokens-100k",
+    name: "駆け出しの消費者",
+    description: "累計10万トークンを消費した。",
+    condition: (s) => s.tokensTotal >= 100_000,
+  },
+  {
+    id: "tokens-1m",
+    name: "百万トークン",
+    description: "累計100万トークンを消費した。",
+    condition: (s) => s.tokensTotal >= 1_000_000,
+  },
+  {
+    id: "tokens-10m",
+    name: "千万トークン",
+    description: "累計1000万トークンを消費した。",
+    condition: (s) => s.tokensTotal >= 10_000_000,
+  },
+  {
+    id: "tokens-100m",
+    name: "億トークン",
+    description: "累計1億トークンを消費した。",
+    condition: (s) => s.tokensTotal >= 100_000_000,
+  },
+  {
+    id: "daily-million",
+    name: "一日で百万トークン",
+    description: "1日で100万トークンを消費した。",
+    condition: (s) => s.tokensToday >= 1_000_000,
+  },
+  {
+    id: "weekly-million",
+    name: "週間百万トークン",
+    description: "1週間で100万トークンを消費した。",
+    condition: (s) => s.tokensThisWeek >= 1_000_000,
+  },
+]

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

@@ -0,0 +1,43 @@
+import { z } from "zod"
+import type { MinionFileSystem } from "@lib/engine/fs/file-system"
+import { JsonFileStore } from "@lib/engine/fs/json-file-store"
+
+const schema = z.object({
+  /** achievement id -> ISO timestamp of when it was unlocked */
+  achievements: z.record(z.string(), z.string()).catch({}),
+  /** species id -> ISO timestamp of when it was first seen */
+  species: z.record(z.string(), z.string()).catch({}),
+})
+
+type CollectionData = z.infer<typeof schema>
+
+const EMPTY: CollectionData = { achievements: {}, species: {} }
+
+/** Persisted unlock/discovery state backing the `minion dex` view (`~/.minion/collection.json`). */
+export class MinionCollectionStore {
+  private readonly store: JsonFileStore<CollectionData>
+
+  constructor(props: { fs: MinionFileSystem; path: string }) {
+    this.store = new JsonFileStore({ fs: props.fs, path: props.path, schema, defaultValue: EMPTY })
+  }
+
+  read(): CollectionData {
+    return this.store.read()
+  }
+
+  /** Records `id` as unlocked if it isn't already. Returns whether this call newly unlocked it, or the write failure. */
+  unlockAchievement(id: string, at: Date): boolean | Error {
+    const data = this.store.read()
+    if (data.achievements[id]) return false
+    data.achievements[id] = at.toISOString()
+    return this.store.write(data) ?? true
+  }
+
+  /** Records `id` as discovered if it isn't already. Returns whether this call newly discovered it, or the write failure. */
+  discoverSpecies(id: string, at: Date): boolean | Error {
+    const data = this.store.read()
+    if (data.species[id]) return false
+    data.species[id] = at.toISOString()
+    return this.store.write(data) ?? true
+  }
+}

package/lib/engine/collection/collection-tracker.ts

@@ -0,0 +1,97 @@
+import { type Achievement, DEFAULT_ACHIEVEMENTS } from "@lib/engine/collection/achievements"
+import type { MinionCollectionStore } from "@lib/engine/collection/collection-store"
+import {
+  DEFAULT_MINION_SPECIES,
+  type MinionSpecies,
+  resolveSpecies,
+} from "@lib/engine/collection/species"
+import type { StatsSnapshot } from "@lib/engine/stats/stats-snapshot"
+
+export type CollectionEvaluation = {
+  /** The one species manifesting right now — the first (= highest-priority) catalog match. */
+  species: MinionSpecies
+  newlyUnlockedAchievements: Achievement[]
+  /**
+   * Every species whose condition holds right now and wasn't discovered
+   * before — not just the manifesting one. A permanently-true high-priority
+   * species (e.g. a lifetime-token rare) would otherwise mask everything
+   * below it forever and make completing the dex impossible.
+   */
+  newlyDiscoveredSpecies: MinionSpecies[]
+}
+
+export type AchievementDexEntry = Achievement & { unlocked: boolean; unlockedAt: string | null }
+export type SpeciesDexEntry = MinionSpecies & { discovered: boolean; firstSeenAt: string | null }
+
+export type CollectionDex = {
+  achievements: AchievementDexEntry[]
+  species: SpeciesDexEntry[]
+}
+
+type Props = {
+  store: MinionCollectionStore
+  /** Species catalog to evaluate/resolve against. Defaults to `DEFAULT_MINION_SPECIES` — pass your own to add species, retheme the built-ins, or attach real `asset` references. */
+  species?: MinionSpecies[]
+  /** Achievement catalog to evaluate against. Defaults to `DEFAULT_ACHIEVEMENTS` — pass your own to replace it entirely. */
+  achievements?: Achievement[]
+}
+
+/** Resolves the currently-manifesting species, unlocks newly-earned achievements, and renders the `minion dex` view. */
+export class MinionCollectionTracker {
+  private readonly store: MinionCollectionStore
+  private readonly species: MinionSpecies[]
+  private readonly achievements: Achievement[]
+
+  constructor(props: Props) {
+    this.store = props.store
+    this.species = props.species ?? DEFAULT_MINION_SPECIES
+    this.achievements = props.achievements ?? DEFAULT_ACHIEVEMENTS
+  }
+
+  /**
+   * Evaluates `stats` against every achievement/species condition, persisting
+   * anything newly earned. Returns an Error when the catalog resolves no
+   * species (non-covering custom catalog) or persisting an unlock fails.
+   */
+  evaluate(stats: StatsSnapshot): CollectionEvaluation | Error {
+    const species = resolveSpecies(stats, this.species)
+    if (species instanceof Error) return species
+
+    const newlyUnlockedAchievements: Achievement[] = []
+    for (const achievement of this.achievements) {
+      if (!achievement.condition(stats)) continue
+      const unlocked = this.store.unlockAchievement(achievement.id, stats.now)
+      if (unlocked instanceof Error) return unlocked
+      if (unlocked) newlyUnlockedAchievements.push(achievement)
+    }
+
+    const newlyDiscoveredSpecies: MinionSpecies[] = []
+    for (const candidate of this.species) {
+      if (!candidate.condition(stats)) continue
+      const discovered = this.store.discoverSpecies(candidate.id, stats.now)
+      if (discovered instanceof Error) return discovered
+      if (discovered) newlyDiscoveredSpecies.push(candidate)
+    }
+
+    return { species, newlyUnlockedAchievements, newlyDiscoveredSpecies }
+  }
+
+  /** Catalog + unlock state, for rendering the CLI dex. Undiscovered species keep their id/rarity; the CLI is responsible for hiding name/description. */
+  dex(): CollectionDex {
+    const data = this.store.read()
+
+    const achievements = this.achievements.map((achievement) => ({
+      ...achievement,
+      unlocked: Boolean(data.achievements[achievement.id]),
+      unlockedAt: data.achievements[achievement.id] ?? null,
+    }))
+
+    const species = this.species.map((s) => ({
+      ...s,
+      discovered: Boolean(data.species[s.id]),
+      firstSeenAt: data.species[s.id] ?? null,
+    }))
+
+    return { achievements, species }
+  }
+}

package/lib/engine/collection/moon.ts

@@ -0,0 +1,26 @@
+const SYNODIC_MONTH_DAYS = 29.530588853
+const KNOWN_NEW_MOON_UTC_MS = Date.UTC(2000, 0, 6, 18, 14)
+const DAY_MS = 24 * 60 * 60 * 1000
+
+/**
+ * Days since the last new moon, in [0, ~29.53). A plain modulo over the mean
+ * synodic month from a known new moon — the real phase drifts up to ~±1 day
+ * from this because the lunar orbit is eccentric, which is why the phase
+ * predicates below default to a ±1-day tolerance. Plenty for a toy.
+ */
+export function moonAgeDays(date: Date): number {
+  const days = (date.getTime() - KNOWN_NEW_MOON_UTC_MS) / DAY_MS
+  const age = days % SYNODIC_MONTH_DAYS
+  return age < 0 ? age + SYNODIC_MONTH_DAYS : age
+}
+
+/** Within `toleranceDays` of the (approximate) full moon. */
+export function isFullMoon(date: Date, toleranceDays = 1): boolean {
+  return Math.abs(moonAgeDays(date) - SYNODIC_MONTH_DAYS / 2) <= toleranceDays
+}
+
+/** Within `toleranceDays` of the (approximate) new moon. */
+export function isNewMoon(date: Date, toleranceDays = 1): boolean {
+  const age = moonAgeDays(date)
+  return age <= toleranceDays || age >= SYNODIC_MONTH_DAYS - toleranceDays
+}