dsh-instruction-memory 1.3.3 → 1.4.0

package/lib/index.js

@@ -26,12 +26,21 @@
  */
 
 import { copyFile, mkdir, readdir, readFile, rename, stat, unlink, writeFile } from 'node:fs/promises'
-import { watch } from 'node:fs'
+import { readFileSync, watch } from 'node:fs'
 import { randomUUID } from 'node:crypto'
 import { isIP } from 'node:net'
 import { homedir, hostname } from 'node:os'
 import { basename, dirname, isAbsolute, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import {
+  FEEDBACK_ENV,
+  FEEDBACK_LIMITS,
+  buildFeedbackMessage,
+  feedbackCooldownMs,
+  feedbackConfigFrom,
+  normalizeFeedback,
+  sendSmtpMail,
+} from './mailer.js'
 
 export const name = 'instruction-memory'
 
@@ -121,6 +130,31 @@ const BACKUP_FILE_SUFFIX = '.bak'
  */
 const SECTION_ORDER = 950
 const API_PREFIX = '/instruction-memory/api'
+/**
+ * Feedback mail: the optional config file next to the store. Kept OUT of
+ * the repository on purpose — the operator's SMTP credentials must never be
+ * committed, and a published package must work with the environment variables
+ * alone.
+ */
+const FEEDBACK_CONFIG_FILE_NAME = 'feedback.json'
+
+/**
+ * The plugin version reported in a feedback mail. Read from the package rather
+ * than duplicated here: a hard-coded copy would drift from package.json on the
+ * first release and quietly mislabel every report.
+ *
+ * `../package.json` resolves inside an installed package because npm always
+ * ships package.json next to lib/. A broken install must not take the plugin
+ * down, so an unreadable manifest degrades to '未知'.
+ */
+const PLUGIN_VERSION = (() => {
+  try {
+    const manifest = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+    return typeof manifest.version === 'string' && manifest.version !== '' ? manifest.version : '未知'
+  } catch {
+    return '未知'
+  }
+})()
 
 /**
  * Resolve this plugin's data file under the harness home.
@@ -204,6 +238,10 @@ export const LIMITS = Object.freeze({
   minBudget: MIN_BUDGET,
   maxBudget: MAX_BUDGET,
   maxHistory: MAX_HISTORY,
+  /** Feedback form ceilings, enforced by lib/mailer.js and mirrored in the panel. */
+  maxFeedbackTitle: FEEDBACK_LIMITS.maxTitle,
+  maxFeedbackBody: FEEDBACK_LIMITS.maxBody,
+  maxFeedbackContact: FEEDBACK_LIMITS.maxContact,
 })
 
 /** How long a crashed holder's `memory.json.lock` may block writes before it is stolen. */
@@ -2436,6 +2474,9 @@ export function apply(ctx) {
         maxHistory: MAX_HISTORY,
         maxBackupDir: MAX_BACKUP_DIR,
         maxBodyChars: MAX_BODY_CHARS,
+        maxFeedbackTitle: FEEDBACK_LIMITS.maxTitle,
+        maxFeedbackBody: FEEDBACK_LIMITS.maxBody,
+        maxFeedbackContact: FEEDBACK_LIMITS.maxContact,
       },
     }
   }
@@ -3590,6 +3631,145 @@ export function apply(ctx) {
     return settle('导入完成：' + parts.join('；'), saved)
   })
 
+  /* ---------------- feedback mail ---------------- */
+
+  /**
+   * Wall-clock of the last accepted send. Anti-spam, not a security boundary:
+   * the route is reachable from every same-origin page of the host, and on a
+   * non-loopback bind from the whole LAN. One message per cooldown is enough
+   * for a human reporting a problem and stops a double submit from sending two
+   * mails. The recipient is fixed by configuration, so the route can never be
+   * used to mail a third party.
+   */
+  let feedbackLastSentAt = 0
+
+  /**
+   * Where the optional config file lives. `DSH_INSTRUCTION_MEMORY_FEEDBACK_CONFIG`
+   * wins; otherwise the file sits next to the store (`<DSH_HOME>/instruction-memory/
+   * feedback.json`), outside the repository and outside the published package.
+   */
+  const feedbackConfigPath = () => {
+    const configured = typeof process.env[FEEDBACK_ENV.config] === 'string'
+      ? process.env[FEEDBACK_ENV.config].trim()
+      : ''
+    return configured !== '' ? configured : join(dirname(resolveStorePath()), FEEDBACK_CONFIG_FILE_NAME)
+  }
+
+  /**
+   * Read the optional config file. A missing file is normal (environment-only
+   * setups); an unreadable or malformed one is reported instead of being
+   * silently ignored, because silently falling back to the environment is how a
+   * typo sends mail from the wrong account.
+   */
+  const readFeedbackConfigFile = async (path) => {
+    let text
+    try {
+      text = await readFile(path, 'utf8')
+    } catch (err) {
+      if (err !== null && typeof err === 'object' && err.code === 'ENOENT') return null
+      throw new Error('无法读取反馈配置文件 ' + path + '：' + describeError(err))
+    }
+    try {
+      return JSON.parse(text)
+    } catch (err) {
+      throw new Error('反馈配置文件不是有效的 JSON（' + path + '）：' + describeError(err))
+    }
+  }
+
+  /**
+   * The environment block of a report. Versions and platform come from the Host
+   * (authoritative); locale / time zone / user agent are presentation facts the
+   * panel reports, sanitised again inside the mailer before they reach a header
+   * or the body. Instruction content is deliberately absent.
+   */
+  const feedbackEnvironment = (args) => {
+    const field = (value) => (typeof value === 'string' ? value : '')
+    return {
+      pluginVersion: PLUGIN_VERSION,
+      dshVersion: field(process.env.DSH_VERSION) || field(process.env.DSH_RUNTIME_VERSION),
+      node: process.version,
+      platform: process.platform,
+      arch: process.arch,
+      locale: field(args.locale),
+      timezone: field(args.timezone),
+      userAgent: field(args.userAgent),
+    }
+  }
+
+  /**
+   * `send-feedback` handler. Deliberately returns a small `{ ok, message }`
+   * envelope instead of the usual snapshot one: a send changes no persisted
+   * state, and handing the panel back its own snapshot would make the form
+   * absorb (and re-sync) the whole panel for nothing.
+   */
+  const sendFeedback = async (args) => {
+    const normalized = normalizeFeedback(args)
+    if (!normalized.ok) return { ok: false, message: normalized.message }
+
+    const cooldown = feedbackCooldownMs(process.env)
+    const now = Date.now()
+    if (cooldown > 0 && feedbackLastSentAt > 0 && now - feedbackLastSentAt < cooldown) {
+      const waitSeconds = Math.max(1, Math.ceil((cooldown - (now - feedbackLastSentAt)) / 1000))
+      return { ok: false, message: '反馈发送过于频繁，请 ' + waitSeconds + ' 秒后再试' }
+    }
+
+    const configPath = feedbackConfigPath()
+    let file = null
+    try {
+      file = await readFeedbackConfigFile(configPath)
+    } catch (err) {
+      logInfo('feedback config unusable: ' + describeError(err))
+      return { ok: false, message: describeError(err) }
+    }
+    const readiness = feedbackConfigFrom({ env: process.env, file, configPath })
+    if (!readiness.ok) {
+      logDebug('feedback not configured: ' + readiness.message)
+      return { ok: false, message: readiness.message }
+    }
+
+    const feedback = normalized.value
+    const message = buildFeedbackMessage({
+      feedback,
+      environment: feedbackEnvironment(args),
+      from: readiness.config.from,
+      to: readiness.config.to,
+      now: new Date(),
+    })
+
+    // SMTP servers sometimes echo the mailbox inside a rejection ("550 no such
+    // user <addr>"). The panel never needs to show the maintainer's address
+    // back, so both UI text and the log keep it masked.
+    const maskAddresses = (text) => {
+      let out = String(text)
+      for (const address of [readiness.config.to, readiness.config.from]) {
+        if (address !== '') out = out.split(address).join('[邮箱已隐藏]')
+      }
+      return out
+    }
+
+    try {
+      const sent = await sendSmtpMail({
+        smtp: readiness.config.smtp,
+        from: readiness.config.from,
+        to: readiness.config.to,
+        subject: message.subject,
+        text: message.text,
+        messageId: message.messageId,
+        replyTo: message.replyTo,
+      })
+      feedbackLastSentAt = Date.now()
+      logInfo('feedback sent: type=' + feedback.type + ' id=' + sent.messageId)
+      return { ok: true, message: '反馈邮件已发送，感谢你的反馈！', messageId: sent.messageId }
+    } catch (err) {
+      // The failure reason is the only actionable thing a maintainer can act
+      // on; it never contains the password (see mailer.js), and the configured
+      // mailboxes are masked, so logging it is safe and makes reports debuggable.
+      const reason = maskAddresses(describeError(err))
+      logInfo('feedback send failed: ' + reason)
+      return { ok: false, message: '反馈发送失败：' + reason + '（详细原因已写入宿主日志）' }
+    }
+  }
+
   const dispatch = async (method, args) => {
     await boot
     switch (method) {
@@ -3663,6 +3843,8 @@ export function apply(ctx) {
         return importData(
           args !== null && typeof args === 'object' ? args.payload : null,
           args !== null && typeof args === 'object' ? args.baseRev : undefined)
+      case 'send-feedback':
+        return sendFeedback(args)
       case 'batch':
         return batchEntries(
           args !== null && typeof args === 'object' ? args.op : null,