@stacksjs/defaults 0.70.58 → 0.70.59

package/app/Commands/README.md

@@ -0,0 +1,84 @@
+# What are Commands
+
+Stacks allows you to easily create & manage CLIs. This is done through the use of commands. Commands—_a framework primitive, built on CAC_—are responsible for defining the signature and behavior of a command-line interface.
+
+> [!TIP]
+> You may ship your CLI as a binary, or you may also use `buddy` to run your commands.
+
+## Get Started
+
+The following command will bootstrap a new action 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
+
+### 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._
+
+```ts
+
+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
+}
+
+```
+
+## 🚜 Contributing
+
+Please review the [Contributing Guide](https://github.com/stacksjs/contributing) for details.
+
+## 🏝 Community
+
+For help, discussion about best practices, or any other conversation that would benefit from being searchable:
+
+[Discussions on GitHub](https://github.com/stacksjs/stacks/discussions)
+
+For casual chit-chat with others using this package:
+
+[Join the Stacks Discord Server](https://discord.gg/stacksjs)
+
+## 📄 License
+
+The MIT License (MIT). Please see [LICENSE](../../LICENSE.md) for more information.
+
+Made with 💙

package/app/Commands.ts

@@ -0,0 +1,38 @@
+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

package/app/Controllers/ComingSoonController.ts

@@ -0,0 +1,9 @@
+import { Controller } from '@stacksjs/server'
+/**
+ * Base Controller class providing Laravel-like functionality
+ */
+export default class ComingSoonController extends Controller {
+  protected index() {
+    return this.success('Coming Soon v2')
+  }
+}

package/app/Controllers/QueryController.ts

@@ -0,0 +1,373 @@
+import { config } from '@stacksjs/config'
+import { db, sql } from '@stacksjs/database'
+import { Controller } from '@stacksjs/server'
+
+export default class QueryController extends Controller {
+  /**
+   * Get query statistics for the dashboard
+   */
+  async getStats() {
+    try {
+      // Get the total number of queries
+      const totalQueries = await db
+        .selectFrom('query_logs')
+        .select(db.fn.count('id').as('count'))
+        .executeTakeFirstOrThrow()
+
+      // Get counts by query type
+      const queryTypeStats = await db
+        .selectFrom('query_logs')
+        .select([
+          sql`json_extract(tags, "$[0]")`.as('type'),
+          db.fn.count('id').as('count'),
+        ])
+        .groupBy(sql`json_extract(tags, "$[0]")`)
+        .execute()
+
+      // Get counts by status
+      const statusStats = await db
+        .selectFrom('query_logs')
+        .select(['status', db.fn.count('id').as('count')])
+        .groupBy('status')
+        .execute()
+
+      // Get average duration by query type
+      const durationStats = await db
+        .selectFrom('query_logs')
+        .select([
+          sql`json_extract(tags, "$[0]")`.as('type'),
+          db.fn.avg('duration').as('avg_duration'),
+        ])
+        .groupBy(sql`json_extract(tags, "$[0]")`)
+        .execute()
+
+      // Get count of slow queries over time (last 24 hours)
+      const slowQueriesTimeline = await db
+        .selectFrom('query_logs')
+        .select([
+          sql`strftime("%Y-%m-%d %H:00:00", executed_at)`.as('hour'),
+          db.fn.count('id').as('count'),
+        ])
+        .where('status', '=', 'slow')
+        .where('executed_at', '>=', sql`datetime("now", "-1 day")` as any)
+        .groupBy(sql`strftime("%Y-%m-%d %H:00:00", executed_at)`)
+        .orderBy('hour')
+        .execute()
+
+      return {
+        totalQueries: totalQueries.count,
+        byType: queryTypeStats,
+        byStatus: statusStats,
+        avgDuration: durationStats,
+        slowQueriesTimeline,
+        // Include system settings for reference
+        settings: {
+          slowThreshold: config.database?.queryLogging?.slowThreshold || 100,
+        },
+      }
+    }
+    catch (error: unknown) {
+      const err = error as Error
+      throw new Error(`Failed to fetch query statistics: ${err.message}`)
+    }
+  }
+
+  /**
+   * Get a paginated list of recent queries
+   */
+  async getRecentQueries({
+    page = 1,
+    perPage = 10,
+    connection = 'all',
+    type = 'all',
+    status = 'all',
+    search = '',
+  }) {
+    try {
+      let query = db
+        .selectFrom('query_logs')
+        .select([
+          'id',
+          'query',
+          'normalized_query',
+          'duration',
+          'connection',
+          'status',
+          'executed_at',
+          'model',
+          'method',
+          'rows_affected',
+          'tags',
+        ])
+        .orderBy('executed_at', 'desc')
+
+      // Apply filters
+      if (connection !== 'all')
+        query = query.where('connection', '=', connection)
+
+      if (status !== 'all')
+        query = query.where('status', '=', status as any)
+
+      if (type !== 'all')
+        query = query.where('tags', 'like', `%"${type}"%`)
+
+      if (search) {
+        query = query.where(eb => eb.or([
+          eb('query', 'like', `%${search}%`),
+          eb('model', 'like', `%${search}%`),
+          eb('method', 'like', `%${search}%`),
+          eb('affected_tables', 'like', `%${search}%`),
+        ]))
+      }
+
+      // Get total count for pagination
+      const countQuery = query.$call(q => q.select(db.fn.count('id').as('count')))
+      const totalResult = await countQuery.executeTakeFirstOrThrow()
+      const total = Number(totalResult.count)
+
+      // Apply pagination
+      const offset = (page - 1) * perPage
+      query = query.limit(perPage).offset(offset)
+
+      // Execute paginated query
+      const results = await query.execute()
+
+      return {
+        data: results,
+        meta: {
+          current_page: page,
+          per_page: perPage,
+          total,
+          last_page: Math.ceil(total / perPage),
+        },
+      }
+    }
+    catch (error: unknown) {
+      const err = error as Error
+      throw new Error(`Failed to fetch recent queries: ${err.message}`)
+    }
+  }
+
+  /**
+   * Get a list of slow queries
+   */
+  async getSlowQueries({
+    page = 1,
+    perPage = 10,
+    threshold = 0,
+    connection = 'all',
+    search = '',
+  }) {
+    try {
+      let slowThreshold = threshold
+      if (slowThreshold < 0)
+        slowThreshold = config.database?.queryLogging?.slowThreshold || 100
+
+      let query = db
+        .selectFrom('query_logs')
+        .select([
+          'id',
+          'query',
+          'normalized_query',
+          'duration',
+          'connection',
+          'status',
+          'executed_at',
+          'model',
+          'method',
+          'rows_affected',
+          'optimization_suggestions',
+          'affected_tables',
+          'indexes_used',
+          'missing_indexes',
+        ])
+        .where('duration', '>=', slowThreshold)
+        .orderBy('duration', 'desc')
+
+      if (connection !== 'all')
+        query = query.where('connection', '=', connection)
+
+      if (search) {
+        query = query.where(eb => eb.or([
+          eb('query', 'like', `%${search}%`),
+          eb('model', 'like', `%${search}%`),
+          eb('method', 'like', `%${search}%`),
+          eb('affected_tables', 'like', `%${search}%`),
+        ]))
+      }
+
+      const countQuery = query.$call(q => q.select(db.fn.count('id').as('count')))
+      const totalResult = await countQuery.executeTakeFirstOrThrow()
+      const total = Number(totalResult.count)
+
+      const offset = (page - 1) * perPage
+      query = query.limit(perPage).offset(offset)
+
+      const results = await query.execute()
+
+      return {
+        data: results,
+        meta: {
+          current_page: page,
+          per_page: perPage,
+          total,
+          last_page: Math.ceil(total / perPage),
+          threshold: slowThreshold,
+        },
+      }
+    }
+    catch (error: unknown) {
+      const err = error as Error
+      throw new Error(`Failed to fetch slow queries: ${err.message}`)
+    }
+  }
+
+  /**
+   * Get a single query by ID
+   */
+  async getQuery(id: number) {
+    try {
+      const query = await db
+        .selectFrom('query_logs')
+        .selectAll()
+        .where('id', '=', id)
+        .executeTakeFirst()
+
+      if (!query)
+        throw new Error('Query not found')
+
+      // Parse JSON fields (safely — data may be corrupted)
+      const safeParse = (val: string | null | undefined, fallback: any = []) => {
+        if (!val) return fallback
+        try { return JSON.parse(val) }
+        catch { return fallback }
+      }
+
+      return {
+        ...query,
+        bindings: safeParse(query.bindings, null),
+        tags: safeParse(query.tags),
+        affected_tables: safeParse(query.affected_tables),
+        indexes_used: safeParse(query.indexes_used),
+        missing_indexes: safeParse(query.missing_indexes),
+        optimization_suggestions: safeParse(query.optimization_suggestions),
+      }
+    }
+    catch (error: any) {
+      throw new Error(`Failed to fetch query: ${error.message}`)
+    }
+  }
+
+  /**
+   * Get query timeline data for charts
+   */
+  async getQueryTimeline({
+    timeframe = 'day', // 'day', 'week', 'month'
+    type = 'all',
+  }) {
+    try {
+      let interval: string
+      let timeConstraint: string
+
+      // Set time grouping format and constraint based on timeframe
+      switch (timeframe) {
+        case 'week':
+          interval = '%Y-%m-%d'
+          timeConstraint = '-7 day'
+          break
+        case 'month':
+          interval = '%Y-%m-%d'
+          timeConstraint = '-30 day'
+          break
+        case 'day':
+        default:
+          interval = '%Y-%m-%d %H:00:00'
+          timeConstraint = '-24 hour'
+          break
+      }
+
+      let query = db
+        .selectFrom('query_logs')
+        .select([
+          sql`strftime("${interval}", executed_at)`.as('time_interval'),
+          db.fn.count('id').as('count'),
+          db.fn.avg('duration').as('avg_duration'),
+        ])
+        .where('executed_at', '>=', sql`datetime("now", "${timeConstraint}")` as any)
+        .groupBy('time_interval')
+        .orderBy('time_interval')
+
+      // Apply type filter if specified
+      if (type !== 'all')
+        query = query.where('tags', 'like', `%"${type}"%`)
+
+      const results = await query.execute()
+
+      return {
+        data: results,
+        meta: {
+          timeframe,
+          type,
+        },
+      }
+    }
+    catch (error: unknown) {
+      const err = error as Error
+      throw new Error(`Failed to fetch query timeline: ${err.message}`)
+    }
+  }
+
+  /**
+   * Get the most frequently run normalized queries
+   */
+  async getFrequentQueries(): Promise<Array<{
+    normalized_query: string
+    count: string | number | bigint
+    avg_duration: string | number
+    max_duration: number | undefined
+  }>> {
+    try {
+      const results = await db
+        .selectFrom('query_logs')
+        .select([
+          'normalized_query',
+          db.fn.count('id').as('count'),
+          db.fn.avg('duration').as('avg_duration'),
+          db.fn.max('duration').as('max_duration'),
+        ])
+        .groupBy('normalized_query')
+        .orderBy('count', 'desc')
+        .limit(10)
+        .execute()
+
+      return results
+    }
+    catch (error: unknown) {
+      const err = error as Error
+      throw new Error(`Failed to fetch frequent queries: ${err.message}`)
+    }
+  }
+
+  /**
+   * Prune old query logs
+   */
+  async pruneQueryLogs() {
+    try {
+      const retentionDays = config.database?.queryLogging?.retention || 7
+
+      const result = await db
+        .deleteFrom('query_logs')
+        .where('executed_at', '<', sql`datetime("now", "-${retentionDays} day")` as any)
+        .executeTakeFirst()
+
+      return {
+        pruned: result.numDeletedRows,
+        retentionDays,
+      }
+    }
+    catch (error: unknown) {
+      const err = error as Error
+      throw new Error(`Failed to prune query logs: ${err.message}`)
+    }
+  }
+}

package/app/Events.ts

@@ -0,0 +1,14 @@
+import type { Events } from '@stacksjs/types'
+
+/**
+ * **Events Configuration**
+ *
+ * This configuration defines all of your events. Because Stacks is fully-typed, you may
+ * hover any of the options below and the definitions will be provided. In case you
+ * have any questions, feel free to reach out via Discord or GitHub Discussions.
+ */
+export default {
+  // eventName: ['Listener1', 'Listener2'] -> listeners default to ./app/actions/*
+  'user:registered': ['SendWelcomeEmail'],
+  'user:created': ['NotifyUser'],
+} satisfies Events

package/app/Gates.ts

@@ -0,0 +1,107 @@
+import type { UserModel } from '@stacksjs/orm'
+
+/**
+ * Authorization Gates Configuration
+ *
+ * Define your application's authorization gates and policy mappings here.
+ * Gates provide a simple way to authorize actions, while policies
+ * organize authorization logic around particular models.
+ *
+ * @see https://stacksjs.org/docs/security/authorization
+ */
+
+/**
+ * Gate definitions
+ *
+ * Simple ability checks that don't require a model.
+ *
+ * @example
+ * // In your code:
+ * import { Gate } from '@stacksjs/auth'
+ *
+ * if (await Gate.allows('edit-settings', user)) {
+ *   // User can edit settings
+ * }
+ */
+export const gates = {
+  /**
+   * Check if user can access admin area
+   */
+  'access-admin': (user: UserModel | null) => {
+    return user?.email?.endsWith('@stacksjs.org') ?? false
+  },
+
+  /**
+   * Check if user can edit application settings
+   */
+  'edit-settings': (user: UserModel | null) => {
+    // Add your logic here
+    return user !== null
+  },
+
+  /**
+   * Check if user can view dashboard
+   */
+  'view-dashboard': (user: UserModel | null) => {
+    return user !== null
+  },
+
+  // Add more gates here...
+  // 'ability-name': (user, ...args) => boolean,
+}
+
+/**
+ * Policy mappings
+ *
+ * Map model names to their policy classes.
+ * Policy files should be in app/Policies/ directory.
+ *
+ * @example
+ * // Simple mapping (uses PostPolicy for Post model)
+ * 'Post': 'PostPolicy',
+ *
+ * // Or with config:
+ * 'Post': {
+ *   policy: 'PostPolicy',
+ *   model: Post,
+ * },
+ */
+export const policies: Record<string, string | { policy: string, model?: string }> = {
+  // 'Post': 'PostPolicy',
+  // 'User': 'UserPolicy',
+  // 'Comment': 'CommentPolicy',
+}
+
+/**
+ * Before callbacks
+ *
+ * Run before any gate/policy check. Return true to allow,
+ * false to deny, or null to continue to the actual check.
+ *
+ * @example
+ * // Super admins bypass all checks
+ * (user) => user?.role === 'super-admin' ? true : null
+ */
+export const before: Array<(user: UserModel | null, ability: string, args: any[]) => boolean | null | Promise<boolean | null>> = [
+  // Example: Super admin bypass
+  // (user, ability) => {
+  //   if (user?.role === 'super-admin') {
+  //     return true // Allow everything for super admins
+  //   }
+  //   return null // Continue to normal checks
+  // },
+]
+
+/**
+ * After callbacks
+ *
+ * Run after gate/policy checks. Can override the result.
+ */
+export const after: Array<(user: UserModel | null, ability: string, result: boolean, args: any[]) => boolean | void | Promise<boolean | void>> = [
+  // Example: Log all authorization checks
+  // (user, ability, result) => {
+  //   console.log(`User ${user?.id} ${result ? 'allowed' : 'denied'} for ${ability}`)
+  // },
+]
+
+export default { gates, policies, before, after }

package/app/Jobs/ExampleJob.ts

@@ -0,0 +1,20 @@
+// import { HttpError } from '@stacksjs/error-handling'
+import { Job } from '@stacksjs/queue'
+import { Every } from '@stacksjs/types'
+
+export default new Job({
+  name: 'Example Job', // optional, defaults to the file name
+  description: 'A demo (cron) job that runs every minute', // optional
+  tries: 3, // optional, defaults to 3 retries, in case of failures
+  backoff: 3, // optional, defaults to 3-second delays between retries
+  rate: Every.Minute, // optional, '* * * * *' in cron syntax
+  backoffConfig: {
+    strategy: 'linear',
+    initialDelay: 5000,
+    factor: 3,
+  },
+  handle: (payload: any) => {
+    return payload
+  },
+  // action: 'SendWelcomeEmail', // instead of handle, you may target an action or `action: () => {`
+})

package/app/Jobs/ExampleTwoJob.ts

@@ -0,0 +1,12 @@
+import { log } from '@stacksjs/cli'
+import { Job } from '@stacksjs/queue'
+import { Every } from '@stacksjs/types'
+
+export default new Job({
+  rate: Every.TwoMinutes, // optional, '*/2 * * * *' in cron syntax
+  handle: () => {
+    log.info('This cron job log this message every two minutes')
+    log.info('Please note, any job may also be dispatched individually, or scheduled via ./app/Schedule')
+  },
+  // action: 'SendWelcomeEmail', // instead of handle, you may target an action or `action: () => {`
+})