dsh-piggy 0.25.0

package/store/api.js

@@ -0,0 +1,260 @@
+// @ts-check
+/**
+ * store 的方法表：每个方法都转发给 core，并在成功后安排一次保存。
+ *
+ * 方法表单独成文件，是为了让 store.js 只剩"打开存档 + 节流写盘"这一件事
+ * （见 docs/CONVENTIONS.md 的单一职责与函数长度条款）。
+ *
+ * @module dsh-piggy/store/api
+ */
+import {
+  act as coreAct,
+  adopt as coreAdopt,
+  ageFromNow as coreAgeFromNow,
+  applyDevPatch as coreDevPatch,
+  buy as coreBuy,
+  callOffActivity as coreCallOff,
+  decay,
+  drainPending,
+  feed as coreFeed,
+  grantAll as coreGrantAll,
+  hatch as coreHatch,
+  hatchEgg,
+  chat as coreChat,
+  rename as coreRename,
+  replyToLine as coreReplyToLine,
+  openGift as coreOpenGift,
+  writeDiaryIfNewDay as coreWriteDiary,
+  recordOnline as coreRecordOnline,
+  signIn as coreSignIn,
+  reset as coreReset,
+  seeDoctor as coreSeeDoctor,
+  setCatchphrase as coreSetCatchphrase,
+  setMotto as coreSetMotto,
+  crown as coreCrown,
+  setOwnerName as coreSetOwnerName,
+  setQuiet as coreSetQuiet,
+  sellSouvenir as coreSellSouvenir,
+  setTimeScale as coreSetTimeScale,
+  startInterest as coreStartInterest,
+  startStudy as coreStartStudy,
+  startTrip as coreStartTrip,
+  startWork as coreStartWork,
+  takeOff as coreTakeOff,
+  useItem as coreUseItem,
+  wearItem as coreWearItem,
+} from '../core.js'
+
+/**
+ * @typedef {object} StoreControl
+ * @property {string} filePath - where this pig is saved
+ * @property {() => number} now - injectable clock
+ * @property {() => object|null} getState - live state (null until an egg is laid)
+ * @property {(next: object|null) => void} setState - replace the live state
+ * @property {() => void} scheduleSave - request a throttled write
+ * @property {(fn: (state: object) => object) => object} mutate - run a core mutator, saving on success
+ * @property {() => void} dispose - flush and stop the timer
+ */
+
+/**
+ * Build the store's public methods.
+ * @param {StoreControl} control
+ * @returns {object} the store API
+ */
+export function createApi(control) {
+  const { filePath, now, getState, setState, scheduleSave, mutate, dispose } = control
+
+  /** 上一次「面板轮询」的时刻，用来算在线时长；0 = 还没见过第一次。 */
+  let lastPollMs = 0
+
+  return {
+    /** The live state (null until an egg is laid). Exposed for rendering. */
+    get state() { return getState() },
+
+    /** Where this pig is saved. */
+    get filePath() { return filePath },
+
+    /** Digest one observed harness event; silently ignored before hatching. */
+    feed(event) {
+      const state = getState()
+      if (state === null) return []
+      try {
+        const crossed = coreFeed(state, event, now())
+        scheduleSave()
+        return crossed
+      } catch (error) {
+        console.warn(`[dsh-piggy] feed failed: event="${event}" reason="${error instanceof Error ? error.message : String(error)}"`)
+        return []
+      }
+    },
+
+    /** Fold wall-clock decay in (and resolve work/illness) then hand back state. */
+    freshen() {
+      const state = getState()
+      if (state === null) return null
+      try {
+        const nowMs = now()
+        // 在线时长按真实时间累计（与调试页的时间倍率无关）；每次读状态就是
+        // 一次「面板还在轮询」的证据。
+        coreRecordOnline(state, lastPollMs, nowMs)
+        lastPollMs = nowMs
+        // 跨过 06:00 之后第一次读状态，就把前一天写成一篇日记。
+        coreWriteDiary(state, nowMs)
+        decay(state, nowMs)
+        scheduleSave()
+      } catch (error) {
+        // Keep the stale-but-valid state, but say why it is stale.
+        console.warn(`[dsh-piggy] decay failed: reason="${error instanceof Error ? error.message : String(error)}"`)
+      }
+      return getState()
+    },
+
+    /** Apply one care action with its cooldown, spending `itemKey` when given. */
+    act: (action, itemKey) => mutate(live => coreAct(live, action, now(), itemKey)),
+
+    /** Send the pig out to work. */
+    startWork: jobKey => mutate(live => coreStartWork(live, jobKey, now())),
+
+    /** Send the pig to class. */
+    startStudy: (subjectKey, stageKey) => mutate(live => coreStartStudy(live, subjectKey, stageKey, now())),
+
+    /** Send the pig to an 兴趣课. */
+    startInterest: interestKey => mutate(live => coreStartInterest(live, interestKey, now())),
+
+    /** Debug: one of everything (consumables, 装扮, coins). */
+    grantAll: () => mutate(live => coreGrantAll(live, now())),
+
+    /** Send the pig travelling. */
+    startTrip: tripKey => mutate(live => coreStartTrip(live, tripKey, now())),
+
+    /** Bring the pig home early (work forfeits pay; study/trips are refunded). */
+    callOffActivity: () => mutate(live => coreCallOff(live, now())),
+
+    /** Back-compat alias. */
+    callOffWork: () => mutate(live => coreCallOff(live, now())),
+
+    /** Buy one item into the backpack. */
+    buy: itemKey => mutate(live => coreBuy(live, itemKey, now())),
+
+    /** Use one item from the backpack. */
+    useItem: itemKey => mutate(live => coreUseItem(live, itemKey, now())),
+
+    /** 看医生: pay to be cured without buying the medicine. */
+    seeDoctor: () => mutate(live => coreSeeDoctor(live, now())),
+    sellSouvenir: souvenirKey => mutate(live => coreSellSouvenir(live, souvenirKey, now())),
+
+    /** The pig speaks up on its own: 'enter' after a while away, or 'idle'. */
+    chat: reason => mutate(live => coreChat(live, reason === 'enter' ? 'enter' : 'idle', now())),
+
+    /** 免打扰 on or off. */
+    setQuiet: on => mutate(live => coreSetQuiet(live, on)),
+
+    /** The pig's catchphrase (居民卡). */
+    setCatchphrase: text => mutate(live => coreSetCatchphrase(live, text)),
+
+    /** The line on the pig's card (居民卡). */
+    setMotto: text => mutate(live => coreSetMotto(live, text)),
+
+    /** 加冕: the owner picks a form the pig qualifies for. */
+    crown: formKey => mutate(live => coreCrown(live, now(), formKey || undefined)),
+
+    /** What the pig calls its owner. */
+    setOwnerName: name => mutate(live => coreSetOwnerName(live, name)),
+
+    /** The owner answers the pig's latest line. */
+    reply: (lineId, replyIndex) => mutate(live => coreReplyToLine(live, lineId, replyIndex)),
+
+    /** 领今天的签到礼包。 */
+    signIn: () => mutate(live => coreSignIn(live, now())),
+
+    /** 开一个攒着的在线礼包。 */
+    openGift: () => mutate(live => coreOpenGift(live, now())),
+    wear: (itemKey, on) => mutate(live => (on ? coreWearItem(live, itemKey, now()) : coreTakeOff(live, itemKey, now()))),
+
+    /** Open the box. Only works when there is no living pig yet. */
+    hatch() {
+      const state = getState()
+      // A save that exists but is not hatched is a box — reset and adopt both
+      // produce one. Refusing because `state !== null` left the box unopenable.
+      if (state !== null && state.hatched === true) return false
+      setState(state === null ? hatchEgg(now()) : coreHatch(state, now()))
+      scheduleSave()
+      return true
+    },
+
+    /** Change how fast the pig ages. */
+    setTimeScale(scale) {
+      const state = getState()
+      if (state === null) return false
+      setState(coreSetTimeScale(state, scale, now()))
+      scheduleSave()
+      return true
+    },
+
+    /** Put the age back on the real clock. */
+    ageFromNow() {
+      const state = getState()
+      if (state === null) return false
+      setState(coreAgeFromNow(state, now()))
+      scheduleSave()
+      return true
+    },
+
+    /** Developer mode: force the pig into any state. */
+    dev(patch) {
+      // Through mutate(): a patch that blows up halfway must not be written.
+      return mutate(live => { coreDevPatch(live, patch, now()); return true }) === true
+    },
+
+    /** Start from a brand new box, living pig or not. */
+    reset() {
+      setState(coreReset(now()))
+      scheduleSave()
+      return true
+    },
+
+    /**
+     * Start over with a fresh box, keeping the old pig's memories. Only offered
+     * once a pig has died — you cannot throw a living one away.
+     */
+    adopt() {
+      const state = getState()
+      if (state === null) return false
+      if (state.dead !== true) return false
+      setState(coreAdopt(state, now()))
+      scheduleSave()
+      return true
+    },
+
+    /** Rename the pig; null when the name is unusable or the pig is absent. */
+    rename(rawName) {
+      const state = getState()
+      if (state === null) return null
+      try {
+        const cleaned = coreRename(state, rawName, now())
+        if (cleaned !== null) scheduleSave()
+        return cleaned
+      } catch (error) {
+        console.warn(`[dsh-piggy] rename failed: reason="${error instanceof Error ? error.message : String(error)}"`)
+        return null
+      }
+    },
+
+    /** Take the queued announcements (work done, got sick, got better…). */
+    drainPending() {
+      const state = getState()
+      if (state === null) return []
+      try {
+        const events = drainPending(state)
+        if (events.length > 0) scheduleSave()
+        return events
+      } catch (error) {
+        console.warn(`[dsh-piggy] drainPending failed: reason="${error instanceof Error ? error.message : String(error)}"`)
+        return []
+      }
+    },
+
+    /** Flush any pending write and stop the timer. Called on plugin unload. */
+    dispose,
+  }
+}

package/store/state-file.js

@@ -0,0 +1,129 @@
+// @ts-check
+/**
+ * 存档的读写：原子写、损坏时保留现场。这一层不含任何业务规则。
+ *
+ * @module dsh-piggy/store/state-file
+ */
+import { closeSync, cpSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, writeFileSync, writeSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join, resolve } from 'node:path'
+
+import { STATE_VERSION, migrate } from '../core.js'
+
+/** The harness home, matching the launcher's own resolution. */
+export function dshHome() {
+  const configured = process.env.DSH_HOME
+  return configured !== undefined && configured.trim() !== ''
+    ? resolve(configured.trim())
+    : join(homedir(), '.dsh')
+}
+
+/** Default save location. */
+export function defaultStatePath() {
+  return join(dshHome(), 'dsh-piggy', 'state.json')
+}
+
+/**
+ * The save used to live in `$DSH_HOME/dsh-pig/`. Move it to `dsh-piggy/` once:
+ * copy the whole folder (backups too), then rename the old one aside rather
+ * than deleting it. Does nothing when the new folder already exists.
+ * @returns {string | null} where the old folder went, or null if nothing moved
+ */
+export function moveLegacySaveDir(home = dshHome(), nowMs = Date.now()) {
+  const fresh = join(home, 'dsh-piggy')
+  const legacy = join(home, 'dsh-pig')
+  if (existsSync(fresh) || !existsSync(legacy)) return null
+  try {
+    cpSync(legacy, fresh, { recursive: true, errorOnExist: true })
+    const aside = `${legacy}.moved-${new Date(nowMs).toISOString().replace(/[:.]/g, '-')}`
+    renameSync(legacy, aside)
+    console.warn(`[dsh-piggy] save folder moved: "${legacy}" -> "${fresh}" (old folder kept as "${aside}")`)
+    return aside
+  } catch (error) {
+    console.warn(`[dsh-piggy] could not move the old save folder: reason="${error instanceof Error ? error.message : String(error)}"`)
+    return null
+  }
+}
+
+/** Copy an unusable save next to the original, then complain loudly. */
+function preserveUnusableSave(filePath, raw, reason, nowMs) {
+  const backup = `${filePath}.corrupt-${new Date(nowMs).toISOString().replace(/[:.]/g, '-')}`
+  try {
+    writeFileSync(backup, raw)
+  } catch (error) {
+    console.warn(`[dsh-piggy] save unusable (${reason}) and the backup failed: path="${filePath}" reason="${error instanceof Error ? error.message : String(error)}"`)
+    return
+  }
+  console.warn(`[dsh-piggy] save unusable (${reason}); kept a copy at "${backup}" and left the original untouched`)
+}
+
+/**
+ * Keep a copy of a save before it is upgraded to a newer version.
+ *
+ * An upgrade rewrites the file on the next save; if a step turns out to be
+ * wrong, this copy is the only way back to the pig as it was.
+ */
+function keepPreUpgradeCopy(filePath, raw, fromVersion, nowMs) {
+  const backup = `${filePath}.v${fromVersion}-backup-${new Date(nowMs).toISOString().replace(/[:.]/g, '-')}`
+  try {
+    writeFileSync(backup, raw)
+    console.warn(`[dsh-piggy] upgrading save v${fromVersion} -> v${STATE_VERSION}; kept a copy at "${backup}"`)
+  } catch (error) {
+    console.warn(`[dsh-piggy] upgrading save v${fromVersion} -> v${STATE_VERSION} without a backup: path="${filePath}" reason="${error instanceof Error ? error.message : String(error)}"`)
+  }
+}
+
+/**
+ * Read the save, keeping the evidence when it cannot be used.
+ *
+ * A bare `catch { return null }` used to turn a corrupt or unreadable save into
+ * "no pig" — the pig silently vanished and the next write would have buried the
+ * old file.
+ *
+ * @returns {{ state: object|null, needsSave: boolean }} the migrated state (or
+ *   null) and whether the file was on an older version and wants a rewrite.
+ */
+export function readStateFile(filePath, nowMs) {
+  let raw
+  try {
+    raw = readFileSync(filePath, 'utf8')
+  } catch (error) {
+    // A missing save is the normal first run; anything else is worth saying.
+    const code = typeof error === 'object' && error !== null && 'code' in error ? error.code : undefined
+    if (code !== 'ENOENT') {
+      console.warn(`[dsh-piggy] could not read save: path="${filePath}" reason="${error instanceof Error ? error.message : String(error)}"`)
+    }
+    return { state: null, needsSave: false }
+  }
+
+  let parsed
+  try {
+    parsed = JSON.parse(raw)
+  } catch (error) {
+    preserveUnusableSave(filePath, raw, `invalid JSON: ${error instanceof Error ? error.message : String(error)}`, nowMs)
+    return { state: null, needsSave: false }
+  }
+
+  const upgraded = migrate(parsed, nowMs)
+  if (upgraded === null) {
+    preserveUnusableSave(filePath, raw, 'migrate() rejected the shape', nowMs)
+    return { state: null, needsSave: false }
+  }
+  const onDisk = parsed?.version
+  if (typeof onDisk === 'number' && onDisk < STATE_VERSION) keepPreUpgradeCopy(filePath, raw, onDisk, nowMs)
+  return { state: upgraded, needsSave: parsed?.version !== upgraded.version }
+}
+
+/** Atomic write: temp file → fsync → rename. */
+export function writeStateFile(filePath, state) {
+  mkdirSync(dirname(filePath), { recursive: true })
+  const tmp = `${filePath}.tmp`
+  const fd = openSync(tmp, 'w')
+  try {
+    writeSync(fd, JSON.stringify(state, null, 2))
+    fsyncSync(fd)
+  } finally {
+    closeSync(fd)
+  }
+  renameSync(tmp, filePath)
+}

package/store.js

@@ -0,0 +1,96 @@
+// @ts-check
+/**
+ * The pig's save: open it, keep the pig's whole state in memory, and write it
+ * back on a throttle.
+ *
+ * Only IO and lifetime live here — the method table is in store/api.js and the
+ * actual game rules are in core/ (see docs/CONVENTIONS.md).
+ *
+ * @module dsh-piggy/store
+ */
+import { createApi } from './store/api.js'
+import { defaultStatePath, dshHome, moveLegacySaveDir, readStateFile, writeStateFile } from './store/state-file.js'
+
+export { defaultStatePath, dshHome, moveLegacySaveDir }
+
+const SAVE_THROTTLE_MS = 1500
+
+/**
+ * Open (or lazily create on first hatch) the save file.
+ * @param {string} [filePath] - where the save lives.
+ * @param {object} [options] - test seams.
+ * @param {() => number} [options.now] - injectable clock.
+ * @param {Function} [options.setTimer] - injectable scheduler.
+ * @param {Function} [options.clearTimer] - injectable canceller.
+ */
+export function createStore(filePath = defaultStatePath(), options = {}) {
+  const now = options.now ?? (() => Date.now())
+  const setTimer = options.setTimer ?? setTimeout
+  const clearTimer = options.clearTimer ?? clearTimeout
+
+  let dirty = false
+  let timer = null
+  let state = null
+
+  function scheduleSave() {
+    dirty = true
+    if (timer !== null) return
+    timer = setTimer(() => {
+      timer = null
+      try {
+        writeNow()
+      } catch (error) {
+        // A failed write must not break the harness, but it must not be silent
+        // either: the player would keep playing against a save that is not there.
+        console.warn(`[dsh-piggy] save failed: path="${filePath}" reason="${error instanceof Error ? error.message : String(error)}"`)
+      }
+    }, SAVE_THROTTLE_MS)
+    if (typeof timer?.unref === 'function') timer.unref()
+  }
+
+  function writeNow() {
+    if (!dirty || state === null) return
+    writeStateFile(filePath, state)
+    dirty = false
+  }
+
+  /** Run a core mutator, saving when it reports success. */
+  function mutate(fn) {
+    if (state === null) return { ok: false, reason: 'absent' }
+    // A core call that throws halfway used to leave the half-applied state in
+    // memory — and the next save wrote it out. Snapshot first, restore on throw.
+    const before = structuredClone(state)
+    try {
+      const result = fn(state)
+      scheduleSave()
+      return result
+    } catch (error) {
+      state = before
+      return { ok: false, reason: 'error', message: error instanceof Error ? error.message : String(error) }
+    }
+  }
+
+  const opened = readStateFile(filePath, now())
+  state = opened.state
+  dirty = opened.needsSave
+
+  return createApi({
+    filePath,
+    now,
+    getState: () => state,
+    setState: next => { state = next },
+    scheduleSave,
+    mutate,
+    dispose() {
+      if (timer !== null) {
+        clearTimer(timer)
+        timer = null
+      }
+      try {
+        writeNow()
+      } catch (error) {
+        console.warn(`[dsh-piggy] final save failed: path="${filePath}" reason="${error instanceof Error ? error.message : String(error)}"`)
+      }
+    },
+  })
+}