@stacksjs/defaults 0.72.78 → 0.72.79

package/app/Actions/Dashboard/Email/CapturedMailIndexAction.ts

@@ -10,12 +10,18 @@ export default new Action({
 
   async handle() {
     try {
-      const messages = await listCapturedMail()
+      // `problems` carries the captures that could not be parsed. They are
+      // reported rather than thrown so one stale file cannot 503 the inbox,
+      // and reported rather than dropped so the operator can still see that
+      // something in the capture directory needs attention.
+      const { messages, problems } = await listCapturedMail()
       return {
         captureDriver: 'log',
         activeDriver: process.env.MAIL_MAILER || 'log',
         total: messages.length,
         messages,
+        unreadable: problems.length,
+        problems,
       }
     }
     catch (error) {

package/app/Actions/Dashboard/Email/captured-mail.test.ts

@@ -24,7 +24,7 @@ afterEach(async () => {
 describe('captured dashboard mail', () => {
   it('returns an empty list when the capture directory does not exist', async () => {
     const root = await temporaryDirectory()
-    expect(await listCapturedMail(join(root, 'missing'))).toEqual([])
+    expect(await listCapturedMail(join(root, 'missing'))).toEqual({ messages: [], problems: [] })
   })
 
   it('lists and reads a valid disk capture', async () => {
@@ -41,7 +41,8 @@ describe('captured dashboard mail', () => {
 `
     await writeFile(join(directory, filename), html)
 
-    const messages = await listCapturedMail(directory)
+    const { messages, problems } = await listCapturedMail(directory)
+    expect(problems).toEqual([])
     expect(messages).toHaveLength(1)
     expect(messages[0]).toMatchObject({
       id: `disk:${filename}`,
@@ -62,10 +63,59 @@ describe('captured dashboard mail', () => {
     expect(message?.text).toBe('')
   })
 
-  it('rejects malformed capture files instead of fabricating metadata', async () => {
+  it('reports a malformed capture instead of fabricating metadata for it', async () => {
     const directory = await temporaryDirectory()
     await writeFile(join(directory, 'broken.html'), '<p>No capture header</p>')
-    await expect(listCapturedMail(directory)).rejects.toThrow('missing its log-driver header')
+
+    const { messages, problems } = await listCapturedMail(directory)
+    expect(messages).toEqual([])
+    expect(problems).toEqual([
+      { capture: 'broken.html', reason: expect.stringContaining('missing its log-driver header') },
+    ])
+  })
+
+  it('still lists the readable captures when one file alongside them is broken', async () => {
+    // The bug this pins: `storage/logs/mail` held 29 captures, one of them
+    // written before the header format settled, and the single bad file made
+    // the whole endpoint 503 - the dashboard inbox showed nothing at all.
+    const directory = await temporaryDirectory()
+    const good = '2026-07-29T12-00-00-000Z-Welcome.html'
+    await writeFile(join(directory, good), `<!--
+  Captured by @stacksjs/email log driver at 2026-07-29T12:00:00.000Z
+  From:    Stacks <hello@example.com>
+  To:      Chris <chris@example.com>
+  Subject: Welcome
+-->
+<main><p>Your account is ready.</p></main>
+`)
+    await writeFile(join(directory, 'legacy-no-header.html'), '<p>Written before the header existed</p>')
+    await writeFile(join(directory, 'headers-missing-subject.html'), `<!--
+  Captured by @stacksjs/email log driver at 2026-07-29T12:00:00.000Z
+  From:    Stacks <hello@example.com>
+  To:      Chris <chris@example.com>
+-->
+<main><p>No subject line.</p></main>
+`)
+
+    const { messages, problems } = await listCapturedMail(directory)
+
+    expect(messages).toHaveLength(1)
+    expect(messages[0]?.id).toBe(`disk:${good}`)
+    expect(problems.map(problem => problem.capture)).toEqual([
+      'headers-missing-subject.html',
+      'legacy-no-header.html',
+    ])
+    expect(problems[0]?.reason).toContain('missing required message headers')
+    expect(problems[1]?.reason).toContain('missing its log-driver header')
+  })
+
+  it('still throws when a broken capture is the one being asked for by id', async () => {
+    // Listing skips it; fetching it by id must not answer with an empty
+    // result, because there the broken file IS what the caller asked about.
+    const directory = await temporaryDirectory()
+    await writeFile(join(directory, 'broken.html'), '<p>No capture header</p>')
+    await expect(showCapturedMail('disk:broken.html', directory))
+      .rejects.toThrow('missing its log-driver header')
   })
 
   it('rejects disk ids that could escape the capture directory', async () => {

package/app/Actions/Dashboard/Email/captured-mail.ts

@@ -25,6 +25,17 @@ export interface CapturedMailMessage extends CapturedMailSummary {
   text: string
 }
 
+export interface CapturedMailProblem {
+  /** The capture that could not be read: a disk filename, or `mem:<index>`. */
+  capture: string
+  reason: string
+}
+
+export interface CapturedMailListing {
+  messages: CapturedMailSummary[]
+  problems: CapturedMailProblem[]
+}
+
 function capturedMailDirectory(): string {
   return process.env.LOG_MAIL_DIR || logsPath('mail')
 }
@@ -65,6 +76,10 @@ function validTimestamp(value: string, source: string): string {
   return new Date(time).toISOString()
 }
 
+function reasonFor(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
 function headerValue(header: string, label: string): string {
   const match = header.match(new RegExp(`^\\s*${label}:\\s*(.*)$`, 'im'))
   return match?.[1]?.trim() || ''
@@ -123,48 +138,69 @@ async function diskMessage(name: string, directory: string): Promise<CapturedMai
   }
 }
 
+type CapturedLogEmail = ReturnType<typeof LogEmailDriver.captured>[number]
+
+function memoryMessage(email: CapturedLogEmail, index: number): CapturedMailMessage {
+  if (!(email.sentAt instanceof Date) || !Number.isFinite(email.sentAt.getTime()))
+    throw new TypeError('Captured in-memory email contains an invalid timestamp.')
+  if (typeof email.subject !== 'string' || !email.subject.trim())
+    throw new TypeError('Captured in-memory email is missing its subject.')
+
+  const html = email.rendered?.html ?? email.html ?? ''
+  const text = email.rendered?.text ?? email.text ?? ''
+  if (typeof html !== 'string' || typeof text !== 'string')
+    throw new TypeError('Captured in-memory email bodies must be strings.')
+
+  const from = formatAddress(email.from)
+  const to = formatAddress(email.to)
+  if (!from || !to)
+    throw new TypeError('Captured in-memory email is missing its sender or recipient.')
+
+  const sentAt = email.sentAt.toISOString()
+  return {
+    id: `mem:${email.sentAt.getTime()}:${index}`,
+    source: 'memory',
+    from,
+    to,
+    cc: formatAddress(email.cc),
+    bcc: formatAddress(email.bcc),
+    subject: email.subject,
+    preview: previewFor(html || text),
+    sentAt,
+    hasHtml: Boolean(html),
+    hasText: Boolean(text),
+    size: Buffer.byteLength(html, 'utf8') + Buffer.byteLength(text, 'utf8'),
+    html,
+    text,
+  }
+}
+
 function memoryMessages(): CapturedMailMessage[] {
-  return LogEmailDriver.captured().map((email, index) => {
-    if (!(email.sentAt instanceof Date) || !Number.isFinite(email.sentAt.getTime()))
-      throw new TypeError('Captured in-memory email contains an invalid timestamp.')
-    if (typeof email.subject !== 'string' || !email.subject.trim())
-      throw new TypeError('Captured in-memory email is missing its subject.')
-
-    const html = email.rendered?.html ?? email.html ?? ''
-    const text = email.rendered?.text ?? email.text ?? ''
-    if (typeof html !== 'string' || typeof text !== 'string')
-      throw new TypeError('Captured in-memory email bodies must be strings.')
-
-    const from = formatAddress(email.from)
-    const to = formatAddress(email.to)
-    if (!from || !to)
-      throw new TypeError('Captured in-memory email is missing its sender or recipient.')
-
-    const sentAt = email.sentAt.toISOString()
-    return {
-      id: `mem:${email.sentAt.getTime()}:${index}`,
-      source: 'memory',
-      from,
-      to,
-      cc: formatAddress(email.cc),
-      bcc: formatAddress(email.bcc),
-      subject: email.subject,
-      preview: previewFor(html || text),
-      sentAt,
-      hasHtml: Boolean(html),
-      hasText: Boolean(text),
-      size: Buffer.byteLength(html, 'utf8') + Buffer.byteLength(text, 'utf8'),
-      html,
-      text,
-    }
-  })
+  return LogEmailDriver.captured().map(memoryMessage)
 }
 
 function dedupeKey(message: CapturedMailSummary): string {
   return `${message.sentAt}|${message.from}|${message.to}|${message.subject}`
 }
 
-export async function listCapturedMail(directory = capturedMailDirectory()): Promise<CapturedMailSummary[]> {
+/**
+ * List every capture the log mail driver has taken.
+ *
+ * One unreadable capture must not take down the listing. A stale or
+ * hand-edited file in the capture directory is an ordinary condition, and
+ * failing the whole request over it returned a 503 that hid every other
+ * captured email - on a real directory of 29 files, a single one written
+ * before the header format settled was enough to empty the inbox.
+ *
+ * Skipping it silently would be the other wrong answer, so the capture is
+ * reported in `problems` and the dashboard says what it could not read.
+ * Nothing is fabricated for it, which is what the strict parse was for.
+ *
+ * `showCapturedMail` still throws for a capture the caller asked for by id:
+ * there the broken file IS the answer, so the reason belongs in the response
+ * rather than behind an empty result.
+ */
+export async function listCapturedMail(directory = capturedMailDirectory()): Promise<CapturedMailListing> {
   let names: string[]
   try {
     names = await readdir(directory)
@@ -176,12 +212,33 @@ export async function listCapturedMail(directory = capturedMailDirectory()): Pro
       throw error
   }
 
+  const problems: CapturedMailProblem[] = []
+
   const disk = await Promise.all(
-    names.filter(name => name.endsWith('.html')).map(name => diskMessage(name, directory)),
+    names.filter(name => name.endsWith('.html')).map(async (name) => {
+      try {
+        return await diskMessage(name, directory)
+      }
+      catch (error) {
+        problems.push({ capture: name, reason: reasonFor(error) })
+        return null
+      }
+    }),
   )
+
+  const memory: CapturedMailMessage[] = []
+  LogEmailDriver.captured().forEach((email, index) => {
+    try {
+      memory.push(memoryMessage(email, index))
+    }
+    catch (error) {
+      problems.push({ capture: `mem:${index}`, reason: reasonFor(error) })
+    }
+  })
+
   const seen = new Set<string>()
   const messages: CapturedMailSummary[] = []
-  for (const message of [...disk.filter((entry): entry is CapturedMailMessage => entry !== null), ...memoryMessages()]) {
+  for (const message of [...disk.filter((entry): entry is CapturedMailMessage => entry !== null), ...memory]) {
     const key = dedupeKey(message)
     if (seen.has(key))
       continue
@@ -202,9 +259,14 @@ export async function listCapturedMail(directory = capturedMailDirectory()): Pro
     })
   }
 
-  return messages.sort((left, right) =>
-    new Date(right.sentAt).getTime() - new Date(left.sentAt).getTime(),
-  )
+  return {
+    messages: messages.sort((left, right) =>
+      new Date(right.sentAt).getTime() - new Date(left.sentAt).getTime(),
+    ),
+    // Settled in filename order rather than whichever read rejected first, so
+    // the same directory always produces the same response.
+    problems: problems.sort((left, right) => left.capture.localeCompare(right.capture)),
+  }
 }
 
 export async function showCapturedMail(id: string, directory = capturedMailDirectory()): Promise<CapturedMailMessage | null> {

package/functions/captured-mail.ts

@@ -20,11 +20,20 @@ export interface CapturedMailMessage extends CapturedMailSummary {
   text: string
 }
 
+export interface CapturedMailProblem {
+  /** The capture that could not be read: a disk filename, or `mem:<index>`. */
+  capture: string
+  reason: string
+}
+
 export interface CapturedMailIndex {
   captureDriver: 'log'
   activeDriver: string
   total: number
   messages: CapturedMailSummary[]
+  /** How many captures were skipped because they could not be parsed. */
+  unreadable: number
+  problems: CapturedMailProblem[]
 }
 
 export async function fetchCapturedMail(): Promise<CapturedMailIndex> {

package/ide/vscode/package.json

@@ -2,7 +2,7 @@
   "publisher": "Stacks",
   "name": "vscode-stacks",
   "displayName": "Stacks",
-  "version": "0.72.78",
+  "version": "0.72.79",
   "description": "A modern Stacks development environment.",
   "license": "MIT",
   "funding": "https://github.com/sponsors/chrisbbreuer",

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/defaults",
   "type": "module",
   "sideEffects": false,
-  "version": "0.72.78",
+  "version": "0.72.79",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/stacksjs/stacks.git",
@@ -51,7 +51,7 @@
   "dependencies": {
     "@iconify-json/f7": "^1.2.2",
     "@iconify-json/hugeicons": "^1.2.27",
-    "@stacksjs/mobile": "^0.72.78",
+    "@stacksjs/mobile": "^0.72.79",
     "@stacksjs/sanitizer": "^0.2.113"
   },
   "scripts": {

package/resources/components/Dashboard/Email/CapturedMailDashboard.stx

@@ -1,5 +1,5 @@
 <script client>
-import type { CapturedMailMessage, CapturedMailSummary } from '../../../../functions/captured-mail'
+import type { CapturedMailMessage, CapturedMailProblem, CapturedMailSummary } from '../../../../functions/captured-mail'
 import { fetchCapturedMail, fetchCapturedMailMessage } from '../../../../functions/captured-mail'
 import { pushToast } from '../../../../functions/toasts'
 
@@ -7,12 +7,22 @@ const messages = state<CapturedMailSummary[]>([])
 const selectedId = state('')
 const selectedMessage = state<CapturedMailMessage | null>(null)
 const activeDriver = state('')
+const unreadable = state<CapturedMailProblem[]>([])
 const loading = state(true)
 const detailLoading = state(false)
 const error = state('')
 const detailError = state('')
 let selectionVersion = 0
 
+// The thrown reason already names the file, and the row prints it in mono
+// right before this, so the prefix would read the filename out twice.
+function problemReason(problem: CapturedMailProblem): string {
+  const prefix = `Captured mail file ${problem.capture} is `
+  return problem.reason.startsWith(prefix)
+    ? problem.reason.slice(prefix.length)
+    : problem.reason
+}
+
 function eventValue<T>(value: T | CustomEvent<T>): T {
   return value instanceof CustomEvent ? value.detail : value
 }
@@ -50,6 +60,9 @@ async function loadCapturedMail(): Promise<void> {
     const result = await fetchCapturedMail()
     messages.set(result.messages)
     activeDriver.set(result.activeDriver)
+    // A capture the server could not parse is skipped rather than failing the
+    // whole listing, so it has to be said out loud here or it disappears.
+    unreadable.set(result.problems ?? [])
 
     const current = result.messages.find(message => message.id === selectedId())
     const next = current || result.messages[0]
@@ -67,6 +80,7 @@ async function loadCapturedMail(): Promise<void> {
     const message = cause instanceof Error ? cause.message : 'Captured mail could not be loaded.'
     error.set(message)
     messages.set([])
+    unreadable.set([])
     selectedId.set('')
     selectedMessage.set(null)
     pushToast('error', 'Could not load captured mail', { detail: message })
@@ -92,6 +106,19 @@ onMount(() => {
         <p class="mt-1 text-gray-500 text-sm dark:text-neutral-400">
           Outbound messages recorded by the local log driver. Active mailer: {{ activeDriver() || 'log' }}.
         </p>
+        <div :if="unreadable().length > 0" class="mt-2 flex gap-2 items-start px-3 py-2 bg-amber-50 border border-amber-200 rounded-md text-amber-800 text-xs dark:bg-amber-900/20 dark:border-amber-800/40 dark:text-amber-200">
+          <span class="mt-0.5 h-3.5 w-3.5 shrink-0 i-hugeicons-alert-02"></span>
+          <div>
+            <p class="font-medium">
+              {{ unreadable().length }} capture{{ unreadable().length === 1 ? '' : 's' }} could not be read and {{ unreadable().length === 1 ? 'was' : 'were' }} left out of this list.
+            </p>
+            <ul class="mt-1 space-y-0.5">
+              <template :for="problem in unreadable()">
+                <li class="break-all"><span class="font-mono">{{ problem.capture }}</span> is {{ problemReason(problem) }}</li>
+              </template>
+            </ul>
+          </div>
+        </div>
       </div>
       <Button variant="secondary" :loading="loading()" @click="loadCapturedMail">
         <span :if="!loading()" class="h-4 w-4 i-hugeicons-refresh"></span>