@stacksjs/defaults 0.72.76 → 0.72.78

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/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/ide/vscode/package.json

@@ -2,7 +2,7 @@
   "publisher": "Stacks",
   "name": "vscode-stacks",
   "displayName": "Stacks",
-  "version": "0.72.76",
+  "version": "0.72.78",
   "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.76",
+  "version": "0.72.78",
   "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.76",
+    "@stacksjs/mobile": "^0.72.78",
     "@stacksjs/sanitizer": "^0.2.113"
   },
   "scripts": {

package/project/buddy

@@ -6,7 +6,6 @@ PANTRY_LOCAL_BIN="${ROOT_DIR}/pantry/.bin"
 PANTRY_DIR="${ROOT_DIR}/pantry"
 USER_LOCAL_BIN="${HOME}/.local/bin"
 PANTRY_INSTALLER="${ROOT_DIR}/storage/framework/scripts/pantry-install"
-PANTRY_SETUP_DONE="${PANTRY_DIR}/.postsetup-done"
 PANTRY_BOOTSTRAP_TIMEOUT_SECONDS="${PANTRY_BOOTSTRAP_TIMEOUT_SECONDS:-600}"
 PANTRY_DEPENDENCIES_TIMEOUT_SECONDS="${PANTRY_DEPENDENCIES_TIMEOUT_SECONDS:-1200}"
 
@@ -16,9 +15,13 @@ PANTRY_DEPENDENCIES_TIMEOUT_SECONDS="${PANTRY_DEPENDENCIES_TIMEOUT_SECONDS:-1200
 #   1. `storage/framework/core/buddy/src/cli.ts`  — userland override (legacy
 #      "framework lives in the project" layout). Kept FIRST so projects that
 #      have published buddy via `buddy publish:core buddy` still win.
-#   2. `node_modules/@stacksjs/buddy/src/cli.ts`  — installed package, TS source
+#   2. `<deps>/@stacksjs/buddy/src/cli.ts`  — installed package, TS source
 #      (workspace symlink or a real npm install with `src/` shipped).
-#   3. `node_modules/@stacksjs/buddy/dist/cli.js` — published JS-only build.
+#   3. `<deps>/@stacksjs/buddy/dist/cli.js` — published JS-only build.
+#
+# `<deps>` is node_modules or pantry: an app installed with pantry has no
+# node_modules at all, so a node_modules-only list finds nothing and the shim
+# refuses to run the CLI that is sitting right there in ./pantry.
 #
 # If none of these are present the script bails with a clear message instead
 # of `bun` exploding on a missing file.
@@ -27,6 +30,8 @@ resolve_buddy_entry() {
     "${ROOT_DIR}/storage/framework/core/buddy/src/cli.ts" \
     "${ROOT_DIR}/node_modules/@stacksjs/buddy/src/cli.ts" \
     "${ROOT_DIR}/node_modules/@stacksjs/buddy/dist/cli.js" \
+    "${PANTRY_DIR}/@stacksjs/buddy/src/cli.ts" \
+    "${PANTRY_DIR}/@stacksjs/buddy/dist/cli.js" \
   ; do
     if [ -f "${candidate}" ]; then
       echo "${candidate}"
@@ -38,8 +43,8 @@ resolve_buddy_entry() {
 
 if ! BUDDY_ENTRY=$(resolve_buddy_entry); then
   echo "buddy: could not locate CLI entrypoint." >&2
-  echo "  Tried: storage/framework/core/buddy/src/cli.ts, node_modules/@stacksjs/buddy/{src/cli.ts,dist/cli.js}." >&2
-  echo "  Run \`bun install\` or \`buddy publish:core buddy\` to make the CLI available." >&2
+  echo "  Tried: storage/framework/core/buddy/src/cli.ts, {node_modules,pantry}/@stacksjs/buddy/{src/cli.ts,dist/cli.js}." >&2
+  echo "  Run \`bun install\` (or \`pantry install\`), or \`buddy publish:core buddy\`, to make the CLI available." >&2
   exit 1
 fi
 
@@ -106,17 +111,26 @@ run_buddy() {
   # preload not found "@stacksjs/env/plugin.js"`, then Cannot-find-module for
   # every other import). In that case omit the flag and let bun/import/default
   # resolve the dist.
+  # The probe has to look wherever this project actually installs: pantry-only
+  # apps have no node_modules, so a node_modules-only probe reports "no src"
+  # for a vendored checkout and drops the flag — and then every import resolves
+  # to a ./dist the vendored source has never built.
   CONDITIONS=""
-  if [ -d "${ROOT_DIR}/storage/framework/core" ] && [ -f "${ROOT_DIR}/node_modules/@stacksjs/env/src/index.ts" ]; then
+  if [ -d "${ROOT_DIR}/storage/framework/core" ] \
+    && { [ -f "${ROOT_DIR}/node_modules/@stacksjs/env/src/index.ts" ] || [ -f "${PANTRY_DIR}/@stacksjs/env/src/index.ts" ]; }; then
     CONDITIONS="--conditions development"
   fi
 
   # Installed dependencies are authoritative; Pantry is a fallback for tools
   # the app does not install. Keeping node_modules first prevents a stale local
   # Pantry snapshot from changing migrations, builds, or production commands.
-  # Only add Pantry after setup completed so a partial bootstrap cannot affect
-  # module resolution.
-  if [ -f "${PANTRY_SETUP_DONE}" ]; then
+  #
+  # Add Pantry only once it holds packages. An empty (or absent) directory on
+  # NODE_PATH is what a half-finished bootstrap leaves behind, and pointing at
+  # it buys nothing; a directory with packages in it is the whole module root
+  # for a pantry-installed app, and leaving it off is what makes `buddy` die on
+  # `Cannot find module '@stacksjs/env'` from a preload.
+  if [ -d "${PANTRY_DIR}" ] && [ -n "$(ls -A "${PANTRY_DIR}" 2>/dev/null)" ]; then
     exec env PATH="${PANTRY_LOCAL_BIN}:${USER_LOCAL_BIN}:${PATH}" NODE_PATH="${ROOT_DIR}/node_modules:${PANTRY_DIR}${NODE_PATH:+:${NODE_PATH}}" "${BUN_CMD}" ${CONDITIONS} "${BUDDY_ENTRY}" "$@"
   fi
   exec env PATH="${PANTRY_LOCAL_BIN}:${USER_LOCAL_BIN}:${PATH}" "${BUN_CMD}" ${CONDITIONS} "${BUDDY_ENTRY}" "$@"

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