@stacksjs/defaults 0.72.77 → 0.72.79

package/ai/skills/stacks-buddy/SKILL.md

@@ -17,8 +17,8 @@ The complete CLI runtime for the Stacks framework with 50+ commands, lazy-loaded
 - Lazy command registry: `storage/framework/core/buddy/src/lazy-commands.ts`
 - Config system: `storage/framework/core/buddy/src/config.ts`
 - Shell entry: `buddy` (shell script at project root that invokes `bun run ./storage/framework/core/buddy/src/cli.ts`)
-- Application commands: `app/Commands/`
-- Command registry: `app/Commands.ts`
+- Application commands: `app/Commands/` (auto-discovered; no registration step)
+- Optional registry: `app/Commands.ts`
 - Make templates: `storage/framework/defaults/`
 
 ## CLI Aliases
@@ -250,7 +250,7 @@ buddy make:certificate        # generate SSL certificate (alias: make:cert)
 buddy make:command [name]     # create CLI command in app/Commands/
   --signature [sig]           # CLI command name
   --description [desc]        # command description
-  --no-register               # skip registering in Commands.ts
+  --register                  # also add an entry to app/Commands.ts (optional)
 buddy make:component [name]   # create STX component
 buddy make:database [name]    # create database
 buddy make:factory [name]     # create model factory (stub)
@@ -622,34 +622,63 @@ buddy stacks                 # Stacks framework commands (registered as 'stack'
 
 ## Adding Custom Commands
 
-### Method 1: Commands.ts Registry (preferred)
+### Method 1: Drop a file in `app/Commands/` (preferred)
+
+Every `.ts` file there is a command - no registration, no generated file.
+Nested directories work too (`app/Commands/Archive/Run.ts`).
 
 ```typescript
-// app/Commands.ts
-export default {
-  'inspire': 'Inspire',                              // simple: maps to app/Commands/Inspire.ts
-  'deploy-hooks': { file: 'DeployHooks', enabled: true, aliases: ['dh'] },  // with options
-  'disabled-cmd': { file: 'Disabled', enabled: false }, // disabled command
-}
+// app/Commands/Inspire.ts
+import { defineCommand } from '@stacksjs/cli'
+
+// Declarative: `options` is inferred from the flags declared above it.
+export default defineCommand({
+  name: 'inspire',
+  description: 'Display inspirational quote',
+  aliases: ['insp'],
+  options: {
+    '--two, -t': { description: 'Show two quotes', default: false },
+  },
+  handle(options) {
+    console.log(randomQuote())
+    if (options.two)
+      console.log(randomQuote())
+  },
+})
 ```
 
 ```typescript
-// app/Commands/Inspire.ts
-import type { CLI } from '@stacksjs/cli'
+// Imperative, for a file that registers several commands or uses cli.on()
+import { defineCommand } from '@stacksjs/cli'
 
-export default function (buddy: CLI) {
-  buddy
-    .command('inspire', 'Display inspirational quote')
-    .option('-t, --two', 'Show two quotes')
-    .action(async (options: { two?: boolean }) => {
-      console.log(randomQuote())
-      if (options.two) console.log(randomQuote())
-    })
-}
+export default defineCommand((buddy) => {
+  buddy.command('inspire', 'Display inspirational quote').action(() => {})
+  buddy.command('inspire:two', 'Two quotes').action(() => {})
+})
 ```
 
-### Method 2: Auto-discovery (fallback)
-If `app/Commands.ts` does not exist, all `.ts` files in `app/Commands/` are auto-discovered and loaded. Each must export a default function that receives the CLI instance.
+A command file can also configure itself with named exports:
+
+```typescript
+export const aliases = ['emails', 'mail'] // extra aliases
+export const enabled = false              // keep the file, hide the command
+```
+
+### Method 2: `app/Commands.ts` (optional overlay)
+
+Only worth keeping to control listing order, or to alias/disable a command
+without editing its file. Files it does not mention still load.
+
+```typescript
+// app/Commands.ts
+import { defineCommands } from '@stacksjs/cli'
+
+export default defineCommands({
+  'inspire': 'Inspire',                                                    // maps to app/Commands/Inspire.ts
+  'deploy-hooks': { file: 'DeployHooks', enabled: true, aliases: ['dh'] }, // with options
+  'disabled-cmd': { file: 'Disabled', enabled: false },                    // disabled command
+})
+```
 
 ### Method 3: buddy.config.ts
 ```typescript

package/ai/skills/stacks-cli/SKILL.md

@@ -14,40 +14,92 @@ The `@stacksjs/cli` package provides the foundation for building CLI commands, u
 - Core package: `storage/framework/core/cli/src/`
 - CLI configuration: `config/cli.ts`
 - Application commands: `app/Commands/`
-- Command registry: `app/Commands.ts`
+- Optional registry: `app/Commands.ts` (not needed - see below)
 
 ## Creating Commands
 
-### Simple Command
+Every `.ts` file in `app/Commands/` is a command. There is no registration step
+and no generated registry file: drop the file in and it is live, nested
+directories included (`app/Commands/Archive/Run.ts`).
+
+### Declarative form (preferred)
+
+`defineCommand()` infers the handler's `options` from the flags declared above
+it, so there is no hand-written options interface to drift out of step.
+
 ```typescript
 // app/Commands/Greet.ts
-export default {
-  name: 'greet',
+import { defineCommand, log } from '@stacksjs/cli'
+
+export default defineCommand({
+  name: 'greet <who>',
   description: 'Greet a user',
-  alias: 'g',
+  aliases: ['g'],
   options: {
-    name: { alias: 'n', description: 'Name to greet', default: 'World' },
-    loud: { alias: 'l', description: 'Shout the greeting', type: 'boolean' }
+    '--loud, -l': { description: 'Shout the greeting', default: false },
+    '--title <title>': 'Prefix the name',
+    '--times <n>': { description: 'How often', default: 1, type: [Number] },
   },
-  handle: async ({ options }) => {
-    const greeting = `Hello, ${options.name}!`
-    console.log(options.loud ? greeting.toUpperCase() : greeting)
-  }
-}
+  handle(options, who) {
+    // options.loud   -> boolean
+    // options.title  -> string | undefined
+    // options.times  -> number
+    const greeting = `Hello, ${options.title ?? ''}${who}!`
+
+    for (let i = 0; i < options.times; i++)
+      log.info(options.loud ? greeting.toUpperCase() : greeting)
+  },
+})
 ```
 
-### Register in app/Commands.ts
+Flag to property: `--dry-run` -> `dryRun`, `--two, -t` -> `two`, `--no-cache`
+-> `cache`. Value type: `<x>` -> `string`, `[x]` -> `string | true`, `<x...>`
+-> `string[]`, no argument -> `boolean`. A `default` makes the property always
+present; a `type: [Number]` makes it a `number`.
+
+### Imperative form
+
+For a file that registers several commands or needs `cli.on()`:
+
 ```typescript
-export default {
-  'greet': 'Greet',
-  'inspire': 'Inspire',
-}
+import { defineCommand, log } from '@stacksjs/cli'
+
+export default defineCommand((cli) => {
+  cli.command('inspire', 'Inspire yourself').alias('insp').action(() => {})
+  cli.command('inspire:two', 'Two quotes').action(() => {})
+
+  cli.on('inspire:*', () => log.error('Invalid command'))
+})
+```
+
+### Per-file configuration
+
+Named exports beside the default one, so a command owns its own configuration:
+
+```typescript
+export const aliases = ['emails', 'mail'] // extra aliases
+export const enabled = false              // keep the file, hide the command
+```
+
+### The optional registry (`app/Commands.ts`)
+
+Only worth keeping when you want to control the order commands are listed in,
+or to alias/disable a command without editing its file. A command file the
+registry never mentions still loads.
+
+```typescript
+import { defineCommands } from '@stacksjs/cli'
+
+export default defineCommands({
+  'send-emails <type>': { file: 'SendEmails', aliases: ['emails'] },
+  'legacy': { file: 'Legacy', enabled: false },
+})
 ```
 
-### Three Registration Methods
-1. **app/Commands.ts** — name → file mapping
+### Registration Methods
+1. **Drop a file in `app/Commands/`** — auto-discovered, nothing else to do
 2. **Event listeners** — CLI events in `app/Listeners/Console.ts`
-3. **Inline** — direct command definitions
+3. **`app/Commands.ts`** — optional, for ordering / aliases / disabling
 
 ## CLI Event Listeners
 
@@ -104,7 +156,7 @@ buddy build:cli                    # build CLI binary
 
 ## Gotchas
 - Application commands go in `app/Commands/`, framework commands in `storage/framework/core/buddy/src/commands/`
-- Commands are auto-discovered from `app/Commands.ts` registry
+- Commands are auto-discovered from `app/Commands/`; `app/Commands.ts` is optional and additive
 - CLI events support wildcards (`*`) and default handlers (`!`)
 - The buddy CLI lazy-loads commands — not all load at startup
 - Output formatting uses ANSI colors from `@stacksjs/utils`

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/app/Actions/Dashboard/Infrastructure/CommandIndexAction.ts

@@ -1,16 +1,11 @@
 import { Action } from '@stacksjs/actions'
+import { resolveCommands } from '@stacksjs/cli'
 import { existsSync, readFileSync, statSync } from 'node:fs'
 import { join, relative } from 'node:path'
 import process from 'node:process'
 import { parseCommandSource } from '../Source/source-inventory'
 import { dashboardOperationalError } from '../dashboard-response'
 
-interface CommandConfig {
-  file: string
-  enabled?: boolean
-  aliases?: string[]
-}
-
 export default new Action({
   name: 'CommandIndexAction',
   description: 'Lists commands registered by the application.',
@@ -18,23 +13,27 @@ export default new Action({
   async handle() {
     try {
       const projectRoot = process.cwd()
-      const registryPath = join(projectRoot, 'app/Commands.ts')
-      const registryModule = await import(registryPath)
-      const registry = (registryModule.default || {}) as Record<string, string | CommandConfig>
-      const items = Object.entries(registry).flatMap(([signature, value]) => {
-        const config = typeof value === 'string'
-          ? { file: value, enabled: true, aliases: [] }
-          : { enabled: true, aliases: [], ...value }
-        const file = join(projectRoot, 'app/Commands', `${config.file}.ts`)
-        if (!existsSync(file))
+      const commandsDir = join(projectRoot, 'app/Commands')
+
+      // Every file under app/Commands is a command; app/Commands.ts is an
+      // optional overlay. Listing only registry entries used to hide any
+      // command the project never bothered to register - which, now that
+      // registering is unnecessary, would have been most of them.
+      const commands = await resolveCommands({
+        commandsDir,
+        registryPath: join(projectRoot, 'app/Commands.ts'),
+      })
+
+      const items = commands.flatMap((command) => {
+        if (!existsSync(command.path))
           return []
 
         return [parseCommandSource(
-          readFileSync(file, 'utf8'),
-          relative(projectRoot, file),
-          signature,
-          config.aliases,
-          statSync(file).mtime.toISOString(),
+          readFileSync(command.path, 'utf8'),
+          relative(projectRoot, command.path),
+          command.signature ?? command.file,
+          command.aliases,
+          statSync(command.path).mtime.toISOString(),
         )]
       })
 
@@ -44,7 +43,7 @@ export default new Action({
           total: items.length,
           aliases: items.reduce((sum, item) => sum + (item.aliases?.length || 0), 0),
           options: items.reduce((sum, item) => sum + (item.options?.length || 0), 0),
-          registered: Object.keys(registry).length,
+          registered: commands.filter(command => command.source === 'registry').length,
         },
       }
     }

package/app/Commands/Inspire.ts

@@ -1,16 +1,17 @@
-import type { CLI } from '@stacksjs/types'
 // triggered via `$your-cli inspire` and `buddy inspire`
 import process from 'node:process'
-import { log, quotes } from '@stacksjs/cli'
+import { defineCommand, log, quotes } from '@stacksjs/cli'
 import { ExitCode } from '@stacksjs/types'
 
-// for enhanced type-safety & autocompletion,
-// you may want to define the options' interface
+// Every file in this directory is a command - there is nothing to register.
+// `defineCommand` types the CLI it hands you; the declarative form
+// (`defineCommand({ name, options, handle })`) additionally infers the
+// handler's options from the flags it declares.
 interface InspireOptions {
   two: boolean
 }
 
-export default function (cli: CLI) {
+export default defineCommand((cli) => {
   cli
     .command('inspire', 'Inspire yourself with a random quote')
     .option('--two, -t', 'Inspire yourself with two random quotes', {
@@ -53,5 +54,5 @@ export default function (cli: CLI) {
     process.exit(1)
   })
 
-  return cli // TODO: this may not be needed
-}
+  return cli
+})

package/app/Commands/README.md

@@ -7,60 +7,71 @@ Stacks allows you to easily create & manage CLIs. This is done through the use o
 
 ## Get Started
 
-The following command will bootstrap a new action file in the `app/Commands` directory.
+The following command will bootstrap a new command file in the `app/Commands` directory.
 
 ```sh
 buddy make:command SendEmails
 ```
 
-Because commands are automatically registered, you can use them in your CLI immediately.
-
-```sh
+Every `.ts` file in this directory is a command. There is no registration step and no generated
+registry file - drop the file in and it is live, nested directories included
+(`app/Commands/Archive/Run.ts`).
 
 ### Example
 
-A simple example of a command that prints a random quote to the console. _For a closer look, take a peak at the [Inspire.ts](./Inspire.ts) command._
+`defineCommand()` infers the handler's `options` from the flags declared above it, so there is no
+hand-written options interface to keep in step.
+
+```ts
+import { defineCommand, log } from '@stacksjs/cli'
+
+export default defineCommand({
+  name: 'send-emails <type>',
+  description: 'Send the queued emails of one type',
+  aliases: ['emails'],
+  options: {
+    '--dry-run': { description: 'Report what would be sent, send nothing', default: false },
+    '--limit <n>': { description: 'Stop after this many', default: 100, type: [Number] },
+  },
+  async handle(options, type) {
+    // options.dryRun -> boolean, options.limit -> number, type -> string
+    log.info(`Sending ${options.limit} ${type} emails${options.dryRun ? ' (dry run)' : ''}`)
+  },
+})
+```
+
+For a file that registers several commands, or needs `cli.on()`, take the CLI directly - it is typed
+either way:
+
+```ts
+import { defineCommand, log } from '@stacksjs/cli'
+
+export default defineCommand((cli) => {
+  cli.command('inspire', 'Inspire yourself with a random quote').alias('insp').action(() => {})
+  cli.command('inspire:two', 'Inspire yourself with two random quotes').action(() => {})
+
+  cli.on('inspire:*', () => log.error('Invalid command.'))
+})
+```
+
+### Configuring a command
+
+Named exports beside the default one, so a command owns its own configuration:
 
 ```ts
+export const aliases = ['emails', 'mail'] // extra aliases
+export const enabled = false              // keep the file, hide the command
+```
 
-interface InspireOptions {
-  two: boolean
-}
-
-export default function (cli: CLI) {
-  cli
-    .command('inspire', 'Inspire yourself with a random quote')
-    .option('--two, -t', 'Inspire yourself with two random quotes', { default: false })
-    .alias('insp')
-    .action((options: InspireOptions) => {
-      if (options.two)
-        // @ts-expect-error - this is safe because we hard-coded the quotes
-        quotes.random(2).map((quote, index) => log.info(`${index + 1}. ${quote}`))
-      else
-        log.info(quotes.random())
-
-      log.success('Have a great day!')
-      process.exit(ExitCode.Success)
-    })
-
-  cli
-    .command('inspire:two', 'Inspire yourself with two random quotes')
-    .action(() => {
-      // @ts-expect-error - this is safe because we hard-coded the quotes
-      quotes.random(2).map((quote, index) => log.info(`${index + 1}. ${quote}`))
-
-      log.success('Have a great day!')
-      process.exit(ExitCode.Success)
-    })
-
-  cli.on('inspire:*', () => {
-    log.error('Invalid command: %s\nSee --help for a list of available commands.', cli.args.join(' '))
-    process.exit(1)
-  })
-
-  return cli
-}
+`app/Commands.ts` is optional. Keep one only to control the order commands are listed in, or to
+alias or disable a command without editing its file - a command it never mentions still loads.
+
+```ts
+import { defineCommands } from '@stacksjs/cli'
 
+export default defineCommands({
+  'send-emails <type>': { file: 'SendEmails', aliases: ['emails'] },
+})
 ```
 
 ## 🚜 Contributing

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.77",
+  "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.77",
+  "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.77",
+    "@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>

package/app/Commands.ts

@@ -1,38 +0,0 @@
-export interface CommandConfig {
-  /** The command file name (without .ts extension) */
-  file: string
-  /** Whether the command is enabled */
-  enabled?: boolean
-  /** Command aliases */
-  aliases?: string[]
-}
-
-export type CommandRegistry = Record<string, string | CommandConfig>
-
-/**
- * The application's command registry.
- *
- * Commands listed here will be auto-loaded by the CLI.
- * You can use a simple string (file name) or a config object for more control.
- *
- * @example
- * // Simple registration
- * 'inspire': 'Inspire',
- *
- * // With config
- * 'send-emails': {
- *   file: 'SendEmails',
- *   enabled: true,
- *   aliases: ['emails', 'mail'],
- * },
- */
-export default {
-  'inspire': 'Inspire',
-  // Add more commands here
-  // 'my-command': 'MyCommand',
-  // 'send-emails': {
-  //   file: 'SendEmails',
-  //   enabled: true,
-  //   aliases: ['emails'],
-  // },
-} satisfies CommandRegistry