create-mantiq 0.5.7 → 0.5.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-mantiq",
-  "version": "0.5.7",
+  "version": "0.5.8",
   "description": "Scaffold a new MantiqJS application",
   "type": "module",
   "license": "MIT",

package/skeleton/app/Models/User.ts

@@ -1,28 +1,7 @@
 import { Model } from '@mantiq/database'
-import type { Authenticatable } from '@mantiq/auth'
-import { applyHasApiTokens } from '@mantiq/auth'
+import { AuthenticatableModel } from '@mantiq/auth'
 
-export class User extends Model implements Authenticatable {
-  static override table = 'users'
+export class User extends AuthenticatableModel(Model) {
   static override fillable = ['name', 'email', 'password']
-  static override guarded = ['id']
   static override hidden = ['password', 'remember_token']
-  static override timestamps = true
-
-  getAuthIdentifierName(): string { return 'id' }
-  getAuthIdentifier(): number { return this.getAttribute('id') as number }
-  getAuthPasswordName(): string { return 'password' }
-  getAuthPassword(): string { return this.getAttribute('password') as string }
-  getRememberToken(): string | null { return (this.getAttribute('remember_token') as string) ?? null }
-  setRememberToken(token: string | null): void { this.setAttribute('remember_token', token) }
-  getRememberTokenName(): string { return 'remember_token' }
-
-  // Token methods: createToken(), tokens(), currentAccessToken(), tokenCan(), tokenCant()
-  declare createToken: (name: string, abilities?: string[], expiresAt?: Date) => Promise<{ accessToken: any; plainTextToken: string }>
-  declare tokens: () => any
-  declare currentAccessToken: () => any
-  declare tokenCan: (ability: string) => boolean
-  declare tokenCant: (ability: string) => boolean
 }
-
-applyHasApiTokens(User)

package/skeleton/app/Providers/DatabaseServiceProvider.ts

@@ -1,27 +1,17 @@
 import { ServiceProvider, config } from '@mantiq/core'
-import { DatabaseManager, setupModels, setManager, Migrator } from '@mantiq/database'
-import { applyHasApiTokens, PersonalAccessToken } from '@mantiq/auth'
-import { User } from '../Models/User.ts'
+import { DatabaseManager, setupModels, setManager } from '@mantiq/database'
 
 export class DatabaseServiceProvider extends ServiceProvider {
   override register(): void {
     this.app.singleton(DatabaseManager, () => {
-      const dbConfig = config('database')
-      const manager = new DatabaseManager(dbConfig)
-
+      const manager = new DatabaseManager(config('database'))
       setManager(manager)
       setupModels(manager)
-
       return manager
     })
   }
 
   override async boot(): Promise<void> {
-    // Resolve the manager (triggers creation via the singleton factory)
-    const manager = this.app.make(DatabaseManager)
-
-    // Set up PersonalAccessToken connection and apply HasApiTokens mixin
-    PersonalAccessToken.setConnection(manager.connection())
-    applyHasApiTokens(User)
+    this.app.make(DatabaseManager)
   }
 }

package/skeleton/config/app.ts

@@ -1,14 +1,108 @@
 import { env } from '@mantiq/core'
 
 export default {
+
+  /*
+  |--------------------------------------------------------------------------
+  | Application Name
+  |--------------------------------------------------------------------------
+  |
+  | This value is the name of your application. It is used when the
+  | framework needs to place the application's name in a notification,
+  | log entry, or any other location as required by the application.
+  |
+  */
   name: env('APP_NAME', 'MantiqJS'),
+
+  /*
+  |--------------------------------------------------------------------------
+  | Application Environment
+  |--------------------------------------------------------------------------
+  |
+  | This value determines the "environment" your application is running in.
+  | This may influence how you configure various services the application
+  | uses. Set this in your ".env" file.
+  |
+  | Supported: 'production', 'local', 'staging', 'testing'
+  |
+  */
   env: env('APP_ENV', 'production'),
+
+  /*
+  |--------------------------------------------------------------------------
+  | Application Debug Mode
+  |--------------------------------------------------------------------------
+  |
+  | When your application is in debug mode, detailed error messages with
+  | stack traces will be shown on every error. If disabled, a simple
+  | generic error page is shown. Also controls the heartbeat debug widget.
+  |
+  | WARNING: Never enable debug mode in production.
+  |
+  */
   debug: env('APP_DEBUG', false),
+
+  /*
+  |--------------------------------------------------------------------------
+  | Encryption Key
+  |--------------------------------------------------------------------------
+  |
+  | This key is used by the encryption service and should be set to a
+  | random, 32-character string. You should do this before deploying.
+  |
+  | Generate with: bun mantiq key:generate
+  |
+  */
   key: env('APP_KEY', ''),
+
+  /*
+  |--------------------------------------------------------------------------
+  | Application URL
+  |--------------------------------------------------------------------------
+  |
+  | This URL is used by the framework to generate URLs, configure CORS
+  | origin, and properly redirect. You should set this to the root of
+  | your application so that it is used when running CLI commands.
+  |
+  */
   url: env('APP_URL', 'http://localhost:3000'),
+
+  /*
+  |--------------------------------------------------------------------------
+  | Application Port
+  |--------------------------------------------------------------------------
+  |
+  | The port the HTTP server will listen on.
+  |
+  */
   port: Number(env('APP_PORT', '3000')),
+
+  /*
+  |--------------------------------------------------------------------------
+  | Base Path
+  |--------------------------------------------------------------------------
+  |
+  | The absolute path to the project root directory. Used for resolving
+  | config files, routes, migrations, and other project resources.
+  |
+  */
   basePath: import.meta.dir + '/..',
 
-  // Global middleware applied to every request
-  middleware: ['cors', 'encrypt.cookies', 'session', 'csrf'],
+  /*
+  |--------------------------------------------------------------------------
+  | Middleware Groups
+  |--------------------------------------------------------------------------
+  |
+  | Middleware groups are applied automatically based on the route file:
+  |   routes/web.ts → 'web' group (stateful: sessions, CSRF, cookies)
+  |   routes/api.ts → 'api' group (stateless: rate-limited, no sessions)
+  |
+  | Available aliases: cors, encrypt.cookies, session, csrf, throttle,
+  |   auth, guest, trim, static, heartbeat
+  |
+  */
+  middlewareGroups: {
+    web: ['cors', 'encrypt.cookies', 'session', 'csrf'],
+    api: ['cors', 'throttle'],
+  },
 }

package/skeleton/config/auth.ts

@@ -1,15 +1,50 @@
 import { User } from '../app/Models/User.ts'
 
 export default {
+
+  /*
+  |--------------------------------------------------------------------------
+  | Authentication Defaults
+  |--------------------------------------------------------------------------
+  |
+  | This option controls the default authentication "guard" for your
+  | application. You may change this to any of the guards defined below.
+  |
+  */
   defaults: {
     guard: 'web',
   },
 
+  /*
+  |--------------------------------------------------------------------------
+  | Authentication Guards
+  |--------------------------------------------------------------------------
+  |
+  | Guards define how users are authenticated for each request. The "web"
+  | guard uses session cookies (for browsers and SPAs). The "api" guard
+  | uses Sanctum-style bearer tokens (for mobile apps and third-party).
+  |
+  | Supported drivers: 'session', 'token'
+  |
+  | Token format: Authorization: Bearer {id}|{plaintext}
+  |
+  */
   guards: {
     web: { driver: 'session', provider: 'users' },
     api: { driver: 'token', provider: 'users' },
   },
 
+  /*
+  |--------------------------------------------------------------------------
+  | User Providers
+  |--------------------------------------------------------------------------
+  |
+  | Providers define how users are retrieved from your database. The
+  | "database" driver queries the model specified below.
+  |
+  | Supported drivers: 'database'
+  |
+  */
   providers: {
     users: { driver: 'database', model: User },
   },

package/skeleton/config/cache.ts

@@ -0,0 +1,61 @@
+import { env } from '@mantiq/core'
+
+export default {
+
+  /*
+  |--------------------------------------------------------------------------
+  | Default Cache Store
+  |--------------------------------------------------------------------------
+  |
+  | This option controls the default cache connection that gets used
+  | while using this caching library. You may use any of the stores
+  | defined in the "stores" object below.
+  |
+  | Supported: 'memory', 'file', 'redis', 'memcached', 'null'
+  |
+  */
+  default: env('CACHE_STORE', 'memory'),
+
+  /*
+  |--------------------------------------------------------------------------
+  | Cache Key Prefix
+  |--------------------------------------------------------------------------
+  |
+  | When utilizing a RAM-based store such as Redis or Memcached, there
+  | might be other applications using the same cache. To avoid collisions,
+  | you may prefix every cache key.
+  |
+  */
+  prefix: env('CACHE_PREFIX', 'mantiq_cache_'),
+
+  /*
+  |--------------------------------------------------------------------------
+  | Cache Stores
+  |--------------------------------------------------------------------------
+  |
+  | Here you may define all of the cache "stores" for your application
+  | as well as their drivers. You may even define multiple stores for
+  | the same driver to group types of items stored in your caches.
+  |
+  */
+  stores: {
+    memory: {},
+
+    file: {
+      path: 'storage/cache',
+    },
+
+    redis: {
+      url: env('REDIS_URL', ''),
+      host: env('REDIS_HOST', '127.0.0.1'),
+      port: Number(env('REDIS_PORT', '6379')),
+      password: env('REDIS_PASSWORD', ''),
+      db: Number(env('REDIS_CACHE_DB', '1')),
+    },
+
+    memcached: {
+      host: env('MEMCACHED_HOST', '127.0.0.1'),
+      port: Number(env('MEMCACHED_PORT', '11211')),
+    },
+  },
+}

package/skeleton/config/cors.ts

@@ -0,0 +1,77 @@
+import { env } from '@mantiq/core'
+
+export default {
+
+  /*
+  |--------------------------------------------------------------------------
+  | Allowed Origins
+  |--------------------------------------------------------------------------
+  |
+  | The origin(s) that are allowed to make cross-origin requests. Defaults
+  | to the APP_URL for same-origin SPA requests. Use '*' for public APIs,
+  | or an array for multiple specific origins.
+  |
+  */
+  origin: env('CORS_ORIGIN', env('APP_URL', 'http://localhost:3000')),
+
+  /*
+  |--------------------------------------------------------------------------
+  | Allowed HTTP Methods
+  |--------------------------------------------------------------------------
+  |
+  | The HTTP methods that are allowed in CORS requests.
+  |
+  */
+  methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
+
+  /*
+  |--------------------------------------------------------------------------
+  | Allowed Headers
+  |--------------------------------------------------------------------------
+  |
+  | The HTTP headers that the client is allowed to send in CORS requests.
+  | X-XSRF-TOKEN is required for CSRF protection in SPA applications.
+  |
+  */
+  allowedHeaders: [
+    'Content-Type',
+    'Authorization',
+    'X-Requested-With',
+    'X-CSRF-TOKEN',
+    'X-XSRF-TOKEN',
+    'X-Mantiq',
+  ],
+
+  /*
+  |--------------------------------------------------------------------------
+  | Exposed Headers
+  |--------------------------------------------------------------------------
+  |
+  | Headers that the browser is allowed to read from the response.
+  |
+  */
+  exposedHeaders: ['X-Heartbeat'],
+
+  /*
+  |--------------------------------------------------------------------------
+  | Credentials
+  |--------------------------------------------------------------------------
+  |
+  | Whether to include credentials (cookies, Authorization header) in
+  | cross-origin requests. Must be true for session-based SPA auth.
+  | When true, origin cannot be '*'.
+  |
+  */
+  credentials: true,
+
+  /*
+  |--------------------------------------------------------------------------
+  | Preflight Max Age
+  |--------------------------------------------------------------------------
+  |
+  | How long (in seconds) the browser should cache the preflight response.
+  | Reduces the number of OPTIONS requests for repeated CORS calls.
+  |
+  */
+  maxAge: 7200,
+}

package/skeleton/config/database.ts

@@ -1,12 +1,68 @@
 import { env } from '@mantiq/core'
 
 export default {
+
+  /*
+  |--------------------------------------------------------------------------
+  | Default Database Connection
+  |--------------------------------------------------------------------------
+  |
+  | The database connection used by default for all database operations.
+  | This corresponds to one of the connections defined below. You can
+  | switch connections at runtime with db().connection('name').
+  |
+  */
   default: env('DB_CONNECTION', 'sqlite'),
 
+  /*
+  |--------------------------------------------------------------------------
+  | Database Connections
+  |--------------------------------------------------------------------------
+  |
+  | Here are each of the database connections set up for your application.
+  | SQLite is pre-configured and requires no external services. Add
+  | additional connections for PostgreSQL, MySQL, or MongoDB as needed.
+  |
+  | Supported drivers: 'sqlite', 'postgres', 'mysql', 'mssql', 'mongodb'
+  |
+  */
   connections: {
     sqlite: {
       driver: 'sqlite' as const,
       database: env('DB_DATABASE', import.meta.dir + '/../database/database.sqlite'),
     },
+
+    // postgres: {
+    //   driver: 'postgres' as const,
+    //   host: env('DB_HOST', '127.0.0.1'),
+    //   port: Number(env('DB_PORT', '5432')),
+    //   database: env('DB_DATABASE', 'mantiq'),
+    //   username: env('DB_USERNAME', 'postgres'),
+    //   password: env('DB_PASSWORD', ''),
+    // },
+
+    // mysql: {
+    //   driver: 'mysql' as const,
+    //   host: env('DB_HOST', '127.0.0.1'),
+    //   port: Number(env('DB_PORT', '3306')),
+    //   database: env('DB_DATABASE', 'mantiq'),
+    //   username: env('DB_USERNAME', 'root'),
+    //   password: env('DB_PASSWORD', ''),
+    // },
+
+    // mssql: {
+    //   driver: 'mssql' as const,
+    //   host: env('DB_HOST', '127.0.0.1'),
+    //   port: Number(env('DB_PORT', '1433')),
+    //   database: env('DB_DATABASE', 'mantiq'),
+    //   username: env('DB_USERNAME', 'sa'),
+    //   password: env('DB_PASSWORD', ''),
+    // },
+
+    // mongodb: {
+    //   driver: 'mongodb' as const,
+    //   url: env('MONGODB_URL', 'mongodb://127.0.0.1:27017'),
+    //   database: env('DB_DATABASE', 'mantiq'),
+    // },
   },
 }

package/skeleton/config/filesystem.ts

@@ -1,17 +1,58 @@
 import { env } from '@mantiq/core'
 
 export default {
+
+  /*
+  |--------------------------------------------------------------------------
+  | Default Filesystem Disk
+  |--------------------------------------------------------------------------
+  |
+  | The default filesystem disk used by the storage() helper and all
+  | file operations. You may use any of the disks defined below.
+  |
+  */
   default: env('FILESYSTEM_DISK', 'local'),
 
+  /*
+  |--------------------------------------------------------------------------
+  | Filesystem Disks
+  |--------------------------------------------------------------------------
+  |
+  | Here you may configure as many filesystem "disks" as you wish. Each
+  | disk represents a particular storage driver and location.
+  |
+  | Supported drivers: 'local', 's3', 'gcs', 'r2', 'azure', 'ftp', 'sftp'
+  |
+  */
   disks: {
+    // Private storage — not web-accessible (uploads, temp files, exports)
     local: {
       driver: 'local' as const,
       root: import.meta.dir + '/../storage/app',
     },
+
+    // Public storage — web-accessible via /storage URL
+    // Run: bun mantiq storage:link
     public: {
       driver: 'local' as const,
       root: import.meta.dir + '/../storage/app/public',
       visibility: 'public' as const,
     },
+
+    // s3: {
+    //   driver: 's3' as const,
+    //   bucket: env('AWS_BUCKET', ''),
+    //   region: env('AWS_REGION', 'us-east-1'),
+    //   accessKeyId: env('AWS_ACCESS_KEY_ID', ''),
+    //   secretAccessKey: env('AWS_SECRET_ACCESS_KEY', ''),
+    // },
+
+    // r2: {
+    //   driver: 'r2' as const,
+    //   accountId: env('CLOUDFLARE_ACCOUNT_ID', ''),
+    //   bucket: env('R2_BUCKET', ''),
+    //   accessKeyId: env('R2_ACCESS_KEY_ID', ''),
+    //   secretAccessKey: env('R2_SECRET_ACCESS_KEY', ''),
+    // },
   },
 }

package/skeleton/config/hashing.ts

@@ -0,0 +1,47 @@
+import { env } from '@mantiq/core'
+
+export default {
+
+  /*
+  |--------------------------------------------------------------------------
+  | Default Hash Driver
+  |--------------------------------------------------------------------------
+  |
+  | This option controls the default hash driver used for hashing
+  | passwords and other values. Bcrypt is the recommended default.
+  |
+  | Supported: 'bcrypt', 'argon2'
+  |
+  */
+  driver: env('HASH_DRIVER', 'bcrypt'),
+
+  /*
+  |--------------------------------------------------------------------------
+  | Bcrypt Options
+  |--------------------------------------------------------------------------
+  |
+  | Here you may configure the round count used by the Bcrypt hashing
+  | algorithm. Higher rounds increase security but also increase the
+  | time required to hash a value (10-12 recommended).
+  |
+  */
+  bcrypt: {
+    rounds: Number(env('BCRYPT_ROUNDS', '10')),
+  },
+
+  /*
+  |--------------------------------------------------------------------------
+  | Argon2 Options
+  |--------------------------------------------------------------------------
+  |
+  | Here you may configure the memory cost, time cost, and parallelism
+  | used by the Argon2 hashing algorithm. These values control the
+  | difficulty of producing a valid hash.
+  |
+  */
+  argon2: {
+    memory: 65536,   // Memory cost in KiB (64 MB)
+    time: 4,         // Number of iterations
+    parallelism: 1,  // Degree of parallelism
+  },
+}

package/skeleton/config/heartbeat.ts

@@ -1,23 +1,62 @@
 export default {
+
+  /*
+  |--------------------------------------------------------------------------
+  | Heartbeat Enabled
+  |--------------------------------------------------------------------------
+  |
+  | Master switch for the APM & observability system. When disabled, no
+  | telemetry is recorded and the dashboard is inaccessible.
+  |
+  */
   enabled: true,
 
+  /*
+  |--------------------------------------------------------------------------
+  | Telemetry Storage
+  |--------------------------------------------------------------------------
+  |
+  | Where Heartbeat stores request traces, queries, exceptions, and other
+  | telemetry data. SQLite is zero-config. Retention controls how long
+  | entries are kept before automatic pruning.
+  |
+  */
   storage: {
     driver: 'sqlite' as const,
     path: 'storage/heartbeat/heartbeat.sqlite',
-    retention: 86400,   // 24 hours
-    pruneInterval: 300,  // 5 minutes
+    retention: 86400,    // Seconds to keep entries (86400 = 24 hours)
+    pruneInterval: 300,  // Seconds between prune runs (300 = 5 minutes)
   },
 
+  /*
+  |--------------------------------------------------------------------------
+  | Queue Configuration
+  |--------------------------------------------------------------------------
+  |
+  | Controls how telemetry data is flushed to storage. Use 'sync' for
+  | immediate writes (simpler) or a queue connection for async (faster).
+  |
+  */
   queue: {
     connection: 'sync',
     queue: 'heartbeat',
-    batchSize: 50,
-    flushInterval: 1000,
+    batchSize: 50,       // Entries to flush per batch
+    flushInterval: 1000, // Milliseconds between flushes
   },
 
+  /*
+  |--------------------------------------------------------------------------
+  | Watchers
+  |--------------------------------------------------------------------------
+  |
+  | Each watcher monitors a specific aspect of your application. Disable
+  | individual watchers to reduce telemetry volume or ignore specific
+  | classes/routes via the ignore arrays.
+  |
+  */
   watchers: {
-    request:   { enabled: true, slow_threshold: 1000, ignore: [] },
-    query:     { enabled: true, slow_threshold: 100, detect_n_plus_one: true },
+    request:   { enabled: true, slow_threshold: 1000, ignore: [] },  // ms
+    query:     { enabled: true, slow_threshold: 100, detect_n_plus_one: true },  // ms
     exception: { enabled: true, ignore: [] },
     cache:     { enabled: true },
     job:       { enabled: true },
@@ -27,16 +66,44 @@ export default {
     schedule:  { enabled: true },
   },
 
+  /*
+  |--------------------------------------------------------------------------
+  | Distributed Tracing
+  |--------------------------------------------------------------------------
+  |
+  | When enabled, Heartbeat generates trace IDs and propagates them across
+  | service boundaries via HTTP headers for end-to-end request tracking.
+  |
+  */
   tracing: {
     enabled: true,
     propagate: true,
   },
 
+  /*
+  |--------------------------------------------------------------------------
+  | Sampling
+  |--------------------------------------------------------------------------
+  |
+  | In high-traffic environments, record only a fraction of requests to
+  | reduce storage and performance overhead. Errors are always recorded
+  | regardless of the sampling rate.
+  |
+  */
   sampling: {
-    rate: 1.0,
+    rate: 1.0,                  // 1.0 = 100%, 0.1 = 10%
     always_sample_errors: true,
   },
 
+  /*
+  |--------------------------------------------------------------------------
+  | Dashboard
+  |--------------------------------------------------------------------------
+  |
+  | The built-in web dashboard for viewing recorded telemetry. Protect it
+  | with middleware in production (e.g., ['auth'] to require login).
+  |
+  */
   dashboard: {
     enabled: true,
     path: '/_heartbeat',