millas 0.2.12-beta-1 → 0.2.13

package/src/container/MillasConfig.js

@@ -25,6 +25,11 @@ const AppInitializer = require("./AppInitializer");
 class MillasConfig {
     constructor() {
         this._config = {
+            // Absolute path to the project root — passed to all providers
+            // so they never need to call process.cwd() at runtime.
+            // Set via .configure(__dirname) in bootstrap/app.js.
+            basePath: null,
+
             // Service providers
             providers: [],
 
@@ -35,13 +40,14 @@ class MillasConfig {
             middleware: [],
 
             // Core service toggles
+            logging:  true,
             database: true,
-            cache: true,
-            storage: true,
-            mail: true,
-            queue: true,
-            events: true,
-            logging: true,
+            auth:     true,   // AuthServiceProvider — always on by default
+            cache:    true,
+            storage:  true,
+            mail:     true,
+            queue:    true,
+            events:   true,
 
             // Admin panel — null means disabled, {} or options object means enabled
             admin: null,
@@ -57,6 +63,22 @@ class MillasConfig {
 
     // ── Chainable config methods ───────────────────────────────────────────────
 
+    /**
+     * Set the application base path. Must be the first call.
+     * Pass __dirname from bootstrap/app.js — Laravel style.
+     *
+     *   Millas.configure(__dirname)
+     *
+     * All providers use this to locate config files, models, and routes
+     * without relying on process.cwd() at runtime.
+     *
+     * @param {string} basePath — absolute path to the project root
+     */
+    configure(basePath) {
+        this._config.basePath = basePath;
+        return this;
+    }
+
     /**
      * Register application service providers.
      *
@@ -93,8 +115,15 @@ class MillasConfig {
     /**
      * Enable the admin panel.
      *
+     * AuthServiceProvider and AdminServiceProvider are registered
+     * automatically — no need to add them to .providers([]).
+     *
      *   .withAdmin()
      *   .withAdmin({ prefix: '/cms', title: 'My CMS' })
+     *
+     * First-time setup:
+     *   millas migrate          # creates users + admin_log + sessions tables
+     *   millas createsuperuser  # creates your first admin user
      */
     withAdmin(options = {}) {
         this._config.admin = options;

package/src/core/admin.js

@@ -0,0 +1,5 @@
+// ── Admin ─────────────────────────────────────────────────────────
+const {Admin, AdminResource, AdminField, AdminFilter, AdminHooks, AdminInline} = require('../admin');
+module.exports = {
+    Admin, AdminResource, AdminField, AdminFilter, AdminHooks, AdminInline
+}

package/src/core/db.js

@@ -2,7 +2,8 @@ const {
     Model,
     fields
 } = require("../orm");
+const { migrations } = require("../orm/migration/operations");
 
 module.exports = {
-    Model, fields
+    Model, fields,migrations
 }

package/src/core/foundation.js

@@ -41,7 +41,6 @@ const { CacheServiceProvider, StorageServiceProvider } = require('../providers/C
 // ── Storage ───────────────────────────────────────────────────────
 const Storage     = require('../storage/Storage');
 const LocalDriver = require('../storage/drivers/LocalDriver');
-
 module.exports = {
   // ── Millas HTTP layer ──────────────────────────────────────────
   MillasRequest, MillasResponse, ResponseDispatcher, RequestContext,
@@ -56,12 +55,5 @@ module.exports = {
   Cache, MemoryDriver, FileDriver, NullDriver, CacheServiceProvider,
   // Storage
   Storage, LocalDriver, StorageServiceProvider,
-};
-
-// ── Admin ─────────────────────────────────────────────────────────
-const { Admin, AdminResource, AdminField, AdminFilter } = require('../admin');
-const AdminServiceProvider = require('../providers/AdminServiceProvider');
-
-Object.assign(module.exports, {
-  Admin, AdminResource, AdminField, AdminFilter, AdminServiceProvider,
-});
+  Log: require('../logger').Log,
+};

package/src/core/lang.js

@@ -0,0 +1 @@
+module.exports = require('../i18n')

package/src/errors/HttpError.js

@@ -3,27 +3,43 @@
 /**
  * HttpError
  *
- * A structured error that carries an HTTP status code.
- * Thrown by Controller.abort() and the validation system.
- * Caught automatically by the Router's global error handler.
+ * A structured HTTP error with a status code, message, and optional
+ * field-level error map. Thrown by abort(), notFound(), forbidden() etc.
+ * and caught by the framework's error handler for consistent responses.
  *
- * Usage:
- *   throw new HttpError(404, 'User not found')
- *   throw new HttpError(422, 'Validation failed', { email: ['email is required'] })
+ *   throw new HttpError(404, 'User not found');
+ *   throw new HttpError(422, 'Validation failed', { email: ['Required'] });
  */
 class HttpError extends Error {
   /**
-   * @param {number} status   HTTP status code
-   * @param {string} message  Human-readable message
-   * @param {object} errors   Optional field-level errors (for validation)
+   * @param {number} status   — HTTP status code
+   * @param {string} [message]
+   * @param {object|null} [errors]  — field-level errors { field: [msg, ...] }
    */
-  constructor(status = 500, message = 'Internal Server Error', errors = null) {
-    super(message);
-    this.name       = 'HttpError';
-    this.status     = status;
-    this.statusCode = status;
-    this.errors     = errors;
+  constructor(status, message, errors = null) {
+    super(message || HttpError.defaultMessage(status));
+    this.name    = 'HttpError';
+    this.status  = status;
+    this.errors  = errors || null;
+  }
+
+  static defaultMessage(status) {
+    const messages = {
+      400: 'Bad Request',
+      401: 'Unauthorized',
+      403: 'Forbidden',
+      404: 'Not Found',
+      405: 'Method Not Allowed',
+      409: 'Conflict',
+      410: 'Gone',
+      422: 'Unprocessable Entity',
+      429: 'Too Many Requests',
+      500: 'Internal Server Error',
+      502: 'Bad Gateway',
+      503: 'Service Unavailable',
+    };
+    return messages[status] || 'Error';
   }
 }
 
-module.exports = HttpError;
+module.exports = HttpError;

package/src/facades/AI.js

@@ -0,0 +1,411 @@
+'use strict';
+
+const { createFacade } = require('./Facade');
+
+// ── Service & types re-exported for application use ───────────────────────────
+const AIService           = require('../ai/AIManager');
+const { AIManager, PendingRequest } = require('../ai/AIManager');
+const {
+  AIMessage, AIResponse, AIStreamEvent,
+  Tool, ToolBuilder, Thread, Prompt, Schema,
+  AIError, AIRateLimitError, AIStructuredOutputError, AIProviderError,
+} = require('../ai/types');
+const {
+  PendingImage, AIImageResponse,
+  PendingAudio, AIAudioResponse,
+  PendingTranscription, AITranscriptionResponse,
+  PendingReranking, AIRerankResponse,
+} = require('../ai/media');
+const { ConversationThread, AI_MIGRATIONS } = require('../ai/conversation');
+const { AIFile, PendingFile, AIFilesAPI, AIVectorStore, AIStoresAPI } = require('../ai/files');
+const { WebSearch, WebFetch, FileSearch } = require('../ai/provider_tools');
+
+/**
+ * AI facade — multi-provider LLM client for Millas.
+ *
+ * Resolved from the DI container as 'ai'.
+ * Auto-configured from config/ai.js or environment variables.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * SUPPORTED PROVIDERS
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   Provider    | Text | Image | TTS | STT | Embed | Rerank
+ *   ────────────┼──────┼───────┼─────┼─────┼───────┼───────
+ *   anthropic   |  ✓   |       |     |     |       |
+ *   openai      |  ✓   |   ✓   |  ✓  |  ✓  |   ✓   |
+ *   gemini      |  ✓   |   ✓   |     |     |   ✓   |
+ *   groq        |  ✓   |       |     |  ✓  |       |
+ *   mistral     |  ✓   |       |     |  ✓  |   ✓   |
+ *   xai         |  ✓   |   ✓   |     |     |       |
+ *   deepseek    |  ✓   |       |     |     |       |
+ *   azure       |  ✓   |       |  ✓  |  ✓  |   ✓   |
+ *   cohere      |  ✓   |       |     |     |   ✓   |   ✓
+ *   ollama      |  ✓   |       |     |     |   ✓   |
+ *   elevenlabs  |      |       |  ✓  |  ✓  |       |
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * CONFIGURATION (config/ai.js)
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   module.exports = {
+ *     default: 'anthropic',
+ *     audioProvider:  'elevenlabs',   // default provider for TTS/STT
+ *     rerankProvider: 'cohere',       // default provider for reranking
+ *     providers: {
+ *       anthropic:  { apiKey: process.env.ANTHROPIC_API_KEY,  model: 'claude-sonnet-4-20250514' },
+ *       openai:     { apiKey: process.env.OPENAI_API_KEY,     model: 'gpt-4o', embeddingModel: 'text-embedding-3-small' },
+ *       gemini:     { apiKey: process.env.GEMINI_API_KEY,     model: 'gemini-2.0-flash' },
+ *       groq:       { apiKey: process.env.GROQ_API_KEY,       model: 'llama-3.1-70b-versatile' },
+ *       mistral:    { apiKey: process.env.MISTRAL_API_KEY,    model: 'mistral-large-latest' },
+ *       xai:        { apiKey: process.env.XAI_API_KEY,        model: 'grok-2' },
+ *       deepseek:   { apiKey: process.env.DEEPSEEK_API_KEY,   model: 'deepseek-chat' },
+ *       cohere:     { apiKey: process.env.COHERE_API_KEY },
+ *       elevenlabs: { apiKey: process.env.ELEVENLABS_API_KEY },
+ *       ollama:     { baseUrl: 'http://localhost:11434',       model: 'llama3.2' },
+ *       azure:      { apiKey: process.env.AZURE_OPENAI_KEY, endpoint: process.env.AZURE_OPENAI_ENDPOINT, deployment: 'gpt-4o', apiVersion: '2024-02-01' },
+ *     },
+ *   };
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * TEXT GENERATION
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   // Simplest call
+ *   const res = await AI.text('What is the capital of Kenya?');
+ *   console.log(res.text);           // 'Nairobi'
+ *   console.log(res.totalTokens);    // 42
+ *
+ *   // Full builder
+ *   const res = await AI
+ *     .using('openai')
+ *     .model('gpt-4o')
+ *     .system('You are concise.')
+ *     .temperature(0.7)
+ *     .maxTokens(500)
+ *     .retry(3, 1000)
+ *     .fallback(['anthropic', { provider: 'gemini', model: 'gemini-2.0-flash' }])
+ *     .cache(600)
+ *     .tokenBudget(10000)
+ *     .generate('Explain recursion in one paragraph.');
+ *
+ *   // Extended thinking (Anthropic claude-3-7+)
+ *   const res = await AI
+ *     .using('anthropic')
+ *     .think(16000)
+ *     .generate('Prove there are infinitely many primes.');
+ *
+ *   console.log(res.thinking);  // internal reasoning chain
+ *   console.log(res.text);      // final answer
+ *
+ *   // Per-provider options
+ *   await AI.providerOptions({
+ *     openai:    { reasoning: { effort: 'low' }, frequency_penalty: 0.5 },
+ *     anthropic: { thinking: { budget_tokens: 1024 } },
+ *   }).generate('...');
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * STREAMING
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   // Event-based
+ *   for await (const event of AI.stream('Tell me a story')) {
+ *     if (event.type === 'delta')    process.stdout.write(event.data.text);
+ *     if (event.type === 'thinking') console.log('[thinking]', event.data.text);
+ *     if (event.type === 'tool_call') console.log('Tool called:', event.data.name);
+ *     if (event.type === 'complete') console.log('Tokens:', event.data.totalTokens);
+ *   }
+ *
+ *   // Token callback shorthand
+ *   const res = await AI
+ *     .onToken(chunk => expressRes.write(chunk))
+ *     .generate('Write a poem about Kenya');
+ *
+ *   // SSE endpoint
+ *   app.get('/chat', async (req, res) => {
+ *     res.setHeader('Content-Type', 'text/event-stream');
+ *     for await (const event of AI.stream(req.query.q)) {
+ *       if (event.type === 'delta')
+ *         res.write('data: ' + JSON.stringify({ text: event.data.text }) + '\n\n');
+ *       if (event.type === 'complete')
+ *         res.write('data: [DONE]\n\n');
+ *     }
+ *     res.end();
+ *   });
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * STRUCTURED OUTPUT
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   const res = await AI
+ *     .structured(Schema.define({
+ *       sentiment:  { type: 'string', enum: ['positive', 'negative', 'neutral'] },
+ *       confidence: { type: 'number', min: 0, max: 1 },
+ *       summary:    { type: 'string' },
+ *       keywords:   { type: 'array'  },
+ *     }))
+ *     .generate('Analyse: "Great product, fast shipping!"');
+ *
+ *   res.parsed.sentiment;    // 'positive'
+ *   res.parsed.confidence;   // 0.97
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * TOOL CALLING & AGENTS
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   const weatherTool = Tool.define('get_weather')
+ *     .description('Get real-time weather for a city')
+ *     .parameters({
+ *       type: 'object',
+ *       properties: {
+ *         city:  { type: 'string' },
+ *         units: { type: 'string', enum: ['celsius', 'fahrenheit'] },
+ *       },
+ *       required: ['city'],
+ *     })
+ *     .handle(async ({ city, units = 'celsius' }) => WeatherAPI.get(city, units))
+ *     .build();
+ *
+ *   // Agentic loop — tool calls handled automatically
+ *   const res = await AI
+ *     .tools([weatherTool, calendarTool])
+ *     .agent('Book a meeting for a sunny day in Nairobi next week');
+ *
+ *   // Provider-native tools (executed by the AI provider, not your app)
+ *   await AI.tools([new WebSearch().max(5)]).generate('What happened in AI today?');
+ *   await AI.tools([new WebFetch().allow(['docs.example.com'])]).generate('Summarise https://...');
+ *   await AI.tools([new FileSearch({ stores: ['vs_abc'] })]).generate('Find docs about...');
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * CONVERSATIONS (DB-persisted)
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   // Start a new conversation
+ *   const thread = await AI.conversation.forUser(user.id, 'SalesCoach').create('Q3 Review');
+ *   await thread.addUser('Analyse this transcript...');
+ *   const res = await AI.withThread(thread).generate();
+ *   await thread.addAssistant(res.text);
+ *
+ *   const conversationId = thread.id;  // store for later
+ *
+ *   // Continue an existing conversation
+ *   const thread = await AI.conversation.continue(conversationId);
+ *   await thread.addUser('Tell me more about that.');
+ *   const res = await AI.withThread(thread).generate();
+ *
+ *   // List a user's conversations
+ *   const history = await ConversationThread.list(user.id, 'SalesCoach', 20);
+ *
+ *   // In-memory thread (no DB)
+ *   const thread = AI.thread('You are helpful.').limit(20).summariseWith(async (old) => {
+ *     return (await AI.text('Summarise: ' + old.map(m=>m.content).join('\n'))).text;
+ *   });
+ *   thread.addUser('Hello!');
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * IMAGE GENERATION
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   const img = await AI.image('A donut on a counter')
+ *     .landscape()           // or .portrait() or .square()
+ *     .quality('high')       // 'high' | 'standard' | 'low'
+ *     .using('openai')
+ *     .generate();
+ *
+ *   await img.store('images/donut.png');
+ *   const buffer = img.buffer;  // raw Buffer
+ *
+ *   // With reference images
+ *   const img = await AI.image('Update this to an impressionist style')
+ *     .attachments([AI.files.fromStorage('photo.jpg')])
+ *     .generate();
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * AUDIO — TEXT TO SPEECH
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   const audio = await AI.speak('Welcome to Millas!')
+ *     .female()                          // or .male() or .voice('voice-id')
+ *     .instructions('Speak like a news anchor')
+ *     .using('elevenlabs')
+ *     .generate();
+ *
+ *   await audio.store('audio/welcome.mp3');
+ *   const buffer = audio.buffer;
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * AUDIO — SPEECH TO TEXT (TRANSCRIPTION)
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   // From file path
+ *   const t = await AI.transcribe.fromPath('/recordings/call.mp3')
+ *     .diarize()              // include who said what
+ *     .language('en')
+ *     .generate();
+ *
+ *   console.log(t.text);     // full transcript
+ *   console.log(t.speakers); // per-speaker segments
+ *
+ *   // From storage
+ *   const t = await AI.transcribe.fromStorage('uploads/meeting.mp3').generate();
+ *
+ *   // From buffer
+ *   const t = await AI.transcribe.fromBuffer(audioBuffer, 'audio.mp3').generate();
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * EMBEDDINGS
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   // Single text
+ *   const [vector] = await AI.using('openai').embed('Napa Valley has great wine.');
+ *
+ *   // Batch
+ *   const vectors = await AI.embed(['text one', 'text two'], null, 'openai');
+ *
+ *   // Local (Ollama)
+ *   const [vector] = await AI.using('ollama').embed('Hello world');
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * RERANKING
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   const result = await AI
+ *     .rerank(['Django is a Python framework.', 'Laravel is PHP.', 'React is JS.'])
+ *     .limit(2)
+ *     .using('cohere')
+ *     .rerank('PHP frameworks');
+ *
+ *   result.first.document;  // 'Laravel is PHP.'
+ *   result.first.score;     // 0.95
+ *   for (const r of result) console.log(r.score, r.document);
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * FILE STORAGE
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   // Upload a file to the provider
+ *   const file = await AI.files.fromPath('/reports/q3.pdf').put();
+ *   const file = await AI.files.fromStorage('uploads/report.pdf').put();
+ *   const file = await AI.files.fromUrl('https://example.com/doc.pdf').put();
+ *
+ *   console.log(file.id);   // 'file-abc123'
+ *
+ *   // Use a stored file in a prompt
+ *   const res = await AI
+ *     .withMessage([
+ *       { type: 'text',     text: 'Summarise this document.' },
+ *       { type: 'file_ref', fileId: file.id },
+ *     ])
+ *     .generate();
+ *
+ *   // Retrieve or delete
+ *   const meta = await AI.files.fromId('file-abc').get();
+ *   await AI.files.fromId('file-abc').delete();
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * VECTOR STORES (RAG)
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   // Create a store
+ *   const store = await AI.stores.create('Knowledge Base');
+ *
+ *   // Add files
+ *   await store.add(AI.files.fromPath('/docs/manual.pdf'));
+ *   await store.add('file-abc123', { author: 'Alice', year: 2025 });
+ *
+ *   // Use it in a prompt with FileSearch tool
+ *   await AI
+ *     .tools([new FileSearch({ stores: [store.id] })])
+ *     .generate('Find docs about authentication');
+ *
+ *   // Remove a file
+ *   await store.remove('file-abc123', { deleteFile: true });
+ *
+ *   // Retrieve or delete the store
+ *   const store = await AI.stores.get('vs_abc123');
+ *   await AI.stores.delete('vs_abc123');
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * MIDDLEWARE
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   const logUsage = async (req, next) => {
+ *     const start = Date.now();
+ *     const res   = await next(req);
+ *     Log.info(`AI [${req.provider}] ${Date.now()-start}ms — ${res.totalTokens} tokens`);
+ *     return res;
+ *   };
+ *
+ *   await AI.use(logUsage).generate('...');
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * PROMPT TEMPLATES
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   const prompt = AI.prompt('Translate "{{text}}" to {{language}}.')
+ *     .with({ text: 'Hello', language: 'Swahili' });
+ *
+ *   await AI.text(prompt.toString());
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * TESTING
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   AI.swap({
+ *     text:   async () => new AIResponse({ text: 'Mocked', provider: 'mock', model: 'mock' }),
+ *     stream: async function*() { yield AIStreamEvent.delta('Mocked'); },
+ *   });
+ *   AI.restore();
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * @see src/ai/AIManager.js
+ * @see src/ai/drivers.js
+ * @see src/ai/types.js
+ * @see src/ai/media.js
+ * @see src/ai/conversation.js
+ * @see src/ai/files.js
+ * @see src/ai/provider_tools.js
+ */
+class AI extends createFacade('ai') {}
+
+module.exports = {
+  AI,
+  // Manager
+  AIManager,
+  PendingRequest,
+  // Core types
+  AIMessage,
+  AIResponse,
+  AIStreamEvent,
+  // Tool system
+  Tool,
+  ToolBuilder,
+  // Provider-native tools
+  WebSearch,
+  WebFetch,
+  FileSearch,
+  // Memory
+  Thread,
+  ConversationThread,
+  AI_MIGRATIONS,
+  // Templating & schema
+  Prompt,
+  Schema,
+  // Media
+  PendingImage,  AIImageResponse,
+  PendingAudio,  AIAudioResponse,
+  PendingTranscription, AITranscriptionResponse,
+  PendingReranking,     AIRerankResponse,
+  // Files & vector stores
+  AIFile,
+  PendingFile,
+  AIFilesAPI,
+  AIVectorStore,
+  AIStoresAPI,
+  // Errors
+  AIError,
+  AIRateLimitError,
+  AIStructuredOutputError,
+  AIProviderError,
+};

package/src/facades/Hash.js

@@ -0,0 +1,67 @@
+'use strict';
+
+const { createFacade }              = require('./Facade');
+const { HashManager, BcryptDriver } = require('../hashing/Hash');
+
+/**
+ * Hash facade — Laravel-style hashing.
+ *
+ * Resolved from the DI container as 'hash'.
+ * Falls back to the exported singleton if used before the container boots
+ * (e.g. in migrations or standalone scripts).
+ *
+ * @class
+ *
+ * ── Core ─────────────────────────────────────────────────────────────────────
+ * @property {function(string, object=): Promise<string>}   make
+ *   Hash a plain-text value.
+ *   Options: { rounds: 14 } — overrides the configured rounds for this call.
+ *
+ * @property {function(string, string): Promise<boolean>}   check
+ *   Verify a plain-text value against a stored hash.
+ *   Returns false (never throws) if either argument is falsy.
+ *
+ * @property {function(string): boolean}                    needsRehash
+ *   Returns true if the hash was made with different rounds than currently
+ *   configured. Use after login to silently upgrade stored hashes:
+ *     if (Hash.needsRehash(user.password)) {
+ *       user.password = await Hash.make(plaintext);
+ *       await user.save();
+ *     }
+ *
+ * ── Introspection ─────────────────────────────────────────────────────────────
+ * @property {function(string): { alg: string, rounds: number }}  info
+ *   Return metadata about a stored hash.
+ *   Example: Hash.info(hash) → { alg: 'bcrypt', rounds: 12 }
+ *
+ * @property {function(string): boolean}                          isHashed
+ *   Return true if the value looks like a bcrypt hash.
+ *   Guards against accidentally double-hashing:
+ *     if (!Hash.isHashed(value)) value = await Hash.make(value);
+ *
+ * ── Driver access ─────────────────────────────────────────────────────────────
+ * @property {function(string=): BcryptDriver}   driver
+ *   Get a specific driver instance:
+ *     Hash.driver('bcrypt').make('secret', { rounds: 14 });
+ *
+ * ── Configuration ─────────────────────────────────────────────────────────────
+ * @property {function(number): HashManager}   setRounds
+ *   Change the bcrypt rounds at runtime. Busts the driver cache.
+ *   Useful in tests:  Hash.setRounds(4);
+ *
+ * @property {function(): number}              getRounds
+ *   Return the currently configured bcrypt rounds.
+ *
+ * ── Testing ───────────────────────────────────────────────────────────────────
+ * @property {function(object): void}   swap
+ *   Swap the underlying instance for a fake:
+ *     Hash.swap({ make: async () => 'hashed', check: async () => true });
+ *
+ * @property {function(): void}         restore
+ *   Restore the real implementation after a swap.
+ *
+ * @see src/hashing/Hash.js
+ */
+class Hash extends createFacade('hash') {}
+
+module.exports = Hash