refactor(buddy): replace 43 duplicate ':*' handlers with onUnknownSubcommand

Every command file used to inline the same 5-line buddy.on(':*')
boilerplate with slight variations (some used console.error, some
log.error, exit codes drifted between 1 and ExitCode.FatalError).
This sweep replaces all 43 call sites with onUnknownSubcommand(buddy,
prefix), which:

  - Emits a consistent 'Unknown <prefix> subcommand: …' message
  - Includes a 'Run `buddy <prefix> --help`' hint
  - Exits with code 64 (EX_USAGE per <sysexits.h>) so CI/scripts can
    distinguish 'user typed an unknown subcommand' from real failures
    without parsing stderr

The helper itself was added in the prior commit but had no consumers.

Author: chrisbbreuer

storage/framework/core/buddy/src/commands/_helpers.ts

@@ -29,7 +29,11 @@ import process from 'node:process'
  */
 export function onUnknownSubcommand(buddy: CLI, prefix: string): void {
   buddy.on(`${prefix}:*`, () => {
-    const args = (buddy as { args?: string[] }).args ?? []
+    // @stacksjs/clapp exposes `args` at runtime but the public CLI type doesn't
+    // surface it. Widening through `unknown` is the canonical "I know
+    // better than the type system here" escape hatch and only runs in
+    // the error-path so the cost is irrelevant.
+    const args = (buddy as unknown as { args?: string[] }).args ?? []
     process.stderr.write(
       `Unknown ${prefix} subcommand: ${args.join(' ')}\n`
       + `Run \`buddy ${prefix} --help\` to see available subcommands.\n`,

storage/framework/core/buddy/src/commands/about.ts

@@ -2,6 +2,7 @@ import type { CLI } from '@stacksjs/types'
 import process from 'node:process'
 import { bold, dim, green, intro, log } from '@stacksjs/cli'
 import { storage } from '@stacksjs/storage'
+import { onUnknownSubcommand } from './_helpers'
 
 export function about(buddy: CLI): void {
   buddy
@@ -59,8 +60,5 @@ export function about(buddy: CLI): void {
       }
     })
 
-  buddy.on('about:*', () => {
-    console.error('Invalid command: %s\nSee --help for a list of available commands.', buddy.args.join(' '))
-    process.exit(1)
-  })
+  onUnknownSubcommand(buddy, "about")
 }

storage/framework/core/buddy/src/commands/add.ts

@@ -3,6 +3,7 @@ import process from 'node:process'
 import { runAdd } from '@stacksjs/actions'
 import { log } from '@stacksjs/logging'
 import { ExitCode } from '@stacksjs/types'
+import { onUnknownSubcommand } from './_helpers'
 
 export function add(buddy: CLI): void {
   const descriptions = {
@@ -60,10 +61,7 @@ export function add(buddy: CLI): void {
       await runAdd(options)
     })
 
-  buddy.on('add:*', () => {
-    console.error('Invalid command: %s\nSee --help for a list of available commands.', buddy.args.join(' '))
-    process.exit(1)
-  })
+  onUnknownSubcommand(buddy, "add")
 }
 
 function hasNoOptions(options: AddOptions) {

storage/framework/core/buddy/src/commands/auth.ts

@@ -4,6 +4,7 @@ import { runAction } from '@stacksjs/actions'
 import { intro, log, outro } from '@stacksjs/cli'
 import { Action } from '@stacksjs/enums'
 import { ExitCode } from '@stacksjs/types'
+import { onUnknownSubcommand } from './_helpers'
 
 export function auth(buddy: CLI): void {
   const descriptions = {
@@ -130,8 +131,5 @@ export function auth(buddy: CLI): void {
       process.exit(ExitCode.Success)
     })
 
-  buddy.on('auth:*', () => {
-    console.error('Invalid command: %s\nSee --help for a list of available commands.', buddy.args.join(' '))
-    process.exit(1)
-  })
+  onUnknownSubcommand(buddy, "auth")
 }

storage/framework/core/buddy/src/commands/build.ts

@@ -3,6 +3,7 @@ import process from 'node:process'
 import { intro, log, outro } from '@stacksjs/cli'
 import { Action } from '@stacksjs/enums'
 import { ExitCode } from '@stacksjs/types'
+import { onUnknownSubcommand } from './_helpers'
 
 // Lazy-load @stacksjs/actions — importing it at module level forces every
 // `buddy <anything>` invocation to resolve the actions barrel before
@@ -242,10 +243,7 @@ export function build(buddy: CLI): void {
       await outro('Stacks built successfully', { startTime, useSeconds: true })
     })
 
-  buddy.on('build:*', () => {
-    console.error('Invalid command: %s\nSee --help for a list of available commands.', buddy.args.join(' '))
-    process.exit(1)
-  })
+  onUnknownSubcommand(buddy, "build")
 }
 
 function hasNoOptions(options: BuildOptions) {

storage/framework/core/buddy/src/commands/changelog.ts

@@ -4,6 +4,7 @@ import { runAction } from '@stacksjs/actions'
 import { intro, log, outro } from '@stacksjs/cli'
 import { Action } from '@stacksjs/enums'
 import { ExitCode } from '@stacksjs/types'
+import { onUnknownSubcommand } from './_helpers'
 
 export function changelog(buddy: CLI): void {
   const descriptions = {
@@ -45,9 +46,5 @@ export function changelog(buddy: CLI): void {
       })
     })
 
-  buddy.on('changelog:*', () => {
-    console.log('Invalid command: %s', buddy.args.join(' '))
-    console.log('See --help for a list of available commands.')
-    process.exit(1)
-  })
+  onUnknownSubcommand(buddy, 'changelog')
 }

storage/framework/core/buddy/src/commands/clean.ts

@@ -4,6 +4,7 @@ import { runAction } from '@stacksjs/actions'
 import { intro, log, outro } from '@stacksjs/cli'
 import { Action } from '@stacksjs/enums'
 import { ExitCode } from '@stacksjs/types'
+import { onUnknownSubcommand } from './_helpers'
 
 export function clean(buddy: CLI): void {
   const descriptions = {
@@ -53,8 +54,5 @@ export function clean(buddy: CLI): void {
       process.exit(ExitCode.Success)
     })
 
-  buddy.on('clean:*', () => {
-    console.error('Invalid command: %s\nSee --help for a list of available commands.', buddy.args.join(' '))
-    process.exit(1)
-  })
+  onUnknownSubcommand(buddy, "clean")
 }

storage/framework/core/buddy/src/commands/cloud.ts

@@ -17,6 +17,7 @@ import {
 } from '@stacksjs/cloud'
 import { path as p } from '@stacksjs/path'
 import { ExitCode } from '@stacksjs/types'
+import { onUnknownSubcommand } from './_helpers'
 
 /**
  * Create a temporary IAM role to allow CloudFormation to delete a stuck stack
@@ -742,8 +743,5 @@ export function cloud(buddy: CLI): void {
       process.exit(ExitCode.Success)
     })
 
-  buddy.on('cloud:*', () => {
-    console.error('Invalid command: %s\nSee --help for a list of available commands.', buddy.args.join(' '))
-    process.exit(1)
-  })
+  onUnknownSubcommand(buddy, "cloud")
 }

storage/framework/core/buddy/src/commands/commit.ts

@@ -2,6 +2,7 @@ import type { CLI, FreshOptions } from '@stacksjs/types'
 import process from 'node:process'
 import { runCommit } from '@stacksjs/actions'
 import { log } from '@stacksjs/logging'
+import { onUnknownSubcommand } from './_helpers'
 
 export function commit(buddy: CLI): void {
   const descriptions = {
@@ -19,8 +20,5 @@ export function commit(buddy: CLI): void {
       await runCommit(options)
     })
 
-  buddy.on('commit:*', () => {
-    console.error('Invalid command: %s\nSee --help for a list of available commands.', buddy.args.join(' '))
-    process.exit(1)
-  })
+  onUnknownSubcommand(buddy, "commit")
 }

storage/framework/core/buddy/src/commands/completion.ts

@@ -1,6 +1,7 @@
 import type { CLI } from '@stacksjs/types'
 import process from 'node:process'
 import { log } from '@stacksjs/cli'
+import { onUnknownSubcommand } from './_helpers'
 
 export function completion(buddy: CLI): void {
   const descriptions = {
@@ -41,10 +42,7 @@ export function completion(buddy: CLI): void {
       }
     })
 
-  buddy.on('completion:*', () => {
-    console.error('Invalid command: %s\nSee --help for a list of available commands.', buddy.args.join(' '))
-    process.exit(1)
-  })
+  onUnknownSubcommand(buddy, "completion")
 }
 
 function generateBashCompletion(commands: string[]): string {