tina4-nodejs 3.13.92 → 3.13.95

package/types/core/src/cache.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Multi-backend response cache for GET requests.
+ *
+ * Backends are selected via the TINA4_CACHE_BACKEND env var:
+ *   memory    — in-process LRU cache (default, zero deps)
+ *   file      — JSON files in data/cache/
+ *   redis     — Redis (raw RESP over TCP, or the `redis` package when present)
+ *   valkey    — Valkey (Redis wire protocol — reuses the Redis backend)
+ *   memcached — Memcached (zero-dep text protocol over TCP; SHA-256-hashed keys)
+ *   mongodb   — MongoDB TTL collection (optional `mongodb` driver, loaded dynamically)
+ *   database  — a `tina4_cache` table in any Tina4-supported DB (via @tina4/orm)
+ *
+ * Usage (the KV/module API is ASYNC on Node — Node is async-everywhere):
+ *   import { responseCache, cacheGet, cacheSet, cacheDelete, cacheClear, cacheStats } from "./cache.js";
+ *
+ *   // As middleware — caches GET responses for ttl seconds
+ *   middleware.use(responseCache({ ttl: 60 }));
+ *
+ *   // Direct usage (await — same semantics as the other 3 languages, async transport)
+ *   await cacheSet("key", {"data": "value"}, 120);
+ *   const value = await cacheGet("key");
+ *   await cacheDelete("key");
+ *   await cacheClear();
+ *   const stats = await cacheStats();
+ *
+ * Availability + file-fallback (mirrors the Python master):
+ *   Each network/driver backend reports availability (redis/valkey connect+AUTH+PING,
+ *   memcached VERSION, mongo connect+ping, database connect). When the configured
+ *   backend's service is unreachable (or its driver is missing / credentials are
+ *   wrong), createBackend() logs a warning and falls back to the `file` backend —
+ *   a real, persistent cache, never a silent no-op. The probe is asynchronous, so
+ *   createBackend() returns a Promise.
+ *
+ * Asynchronous, NATIVE network I/O (NO child process):
+ *   The CacheBackend interface is async (get/set/delete/clear/stats return
+ *   Promises). The network backends use native async Node I/O — redis/valkey speak
+ *   RESP over a node:net socket (with AUTH + SELECT db), memcached speaks its text
+ *   protocol over node:net, and mongodb uses the optional `mongodb` driver. No
+ *   execFileSync, no child processes — connections are pooled per backend instance
+ *   so each cache op is a single async round-trip (~sub-ms locally), not a ~30-80ms
+ *   process spawn. Local backends (memory/file/database-sqlite) resolve immediately.
+ *
+ * Environment (LOCKED — matches Python exactly):
+ *   TINA4_CACHE_BACKEND      — memory | file | redis | valkey | memcached | mongodb | database  (default: memory)
+ *   TINA4_CACHE_URL           — connection URL (redis/valkey/memcached/mongo), or a SQL URL for `database`
+ *                               (database falls back to TINA4_DATABASE_URL)
+ *   TINA4_CACHE_TTL           — default TTL in seconds  (default: 60)
+ *   TINA4_CACHE_MAX_ENTRIES   — max entries              (default: 1000)
+ *   TINA4_CACHE_DIR           — file backend directory   (default: data/cache)
+ *   TINA4_CACHE_USERNAME      — credentials when not embedded in the URL
+ *   TINA4_CACHE_PASSWORD      — credentials when not embedded in the URL
+ */
+import type { Middleware } from "./types.js";
+export interface ResponseCacheConfig {
+    /** Default TTL in seconds. 0 = disabled. Default: 60 */
+    ttl?: number;
+    /** Maximum cache entries. Default: 1000 */
+    maxEntries?: number;
+    /** Only cache these status codes. Default: [200] */
+    statusCodes?: number[];
+    /** Cache backend: memory | redis | file. Default: from env or memory */
+    backend?: string;
+    /** Redis URL. Default: from env or redis://localhost:6379 */
+    cacheUrl?: string;
+    /** File cache directory. Default: from env or data/cache */
+    cacheDir?: string;
+}
+interface CacheBackend {
+    get(key: string): Promise<unknown | undefined>;
+    set(key: string, value: unknown, ttl: number): Promise<void>;
+    delete(key: string): Promise<boolean>;
+    clear(): Promise<void>;
+    /**
+     * Evict expired entries and return HOW MANY were actually evicted.
+     *
+     * REQUIRED, not optional. It used to be neither declared nor implemented, so
+     * the module-level sweep() found no backend method and returned a permanent
+     * 0: the one API whose job is reclaiming expired space did nothing and
+     * reported success. Declaring it here makes "every provider can sweep" a
+     * compile-time fact instead of a runtime hope.
+     *
+     * 0 is the HONEST answer on redis/valkey/memcached/mongodb - they expire
+     * entries server-side, so there is nothing left for us to evict. It is the
+     * WRONG answer for memory, file and database, which own their own expiry.
+     */
+    sweep(): Promise<number>;
+    stats(): Promise<{
+        hits: number;
+        misses: number;
+        size: number;
+        backend: string;
+    }>;
+    name(): string;
+    /**
+     * Whether this backend is actually usable (driver present + service
+     * reachable). Local backends (memory/file) are always available; network /
+     * driver backends override this so the factory can fall back to the file
+     * backend. Mirrors the Python master's `is_available()`. Probed asynchronously
+     * (connect/AUTH/PING/VERSION/ping) so no child process is spawned.
+     */
+    isAvailable?(): Promise<boolean>;
+    /** One-time async connect/probe. Resolves once the backend has decided
+     *  availability; createBackend() awaits this before falling back to file. */
+    ready?(): Promise<void>;
+}
+/** Public shape of a unified cache backend (for cross-package reuse). */
+export type { CacheBackend };
+/**
+ * Build a unified cache backend from explicit params or env vars.
+ *
+ * Backends: memory (default) | file | redis | valkey | memcached | mongodb |
+ * database. Unreachable network/driver backends fall back to the file backend.
+ * ASYNC because availability is probed asynchronously (connect/AUTH/PING/ping)
+ * — no child process. Exported so @tina4/orm can route its persistent DB query
+ * cache through the SAME backends (shared cross-instance) without duplicating
+ * the implementation. Callers `await createBackend(...)`.
+ */
+export declare function createBackend(config?: {
+    backend?: string;
+    cacheUrl?: string;
+    cacheDir?: string;
+    maxEntries?: number;
+}): Promise<CacheBackend>;
+export declare function _getResponseBackend(config?: ResponseCacheConfig): Promise<CacheBackend>;
+export declare function responseCache(config?: ResponseCacheConfig): Middleware;
+/**
+ * Clear all cached responses (the responseCache middleware backend).
+ * ASYNC on Node — callers `await clearCache()` — because the backend may be a
+ * network backend (redis/etc.). Resets the backend's namespace; mirrors the
+ * Python ResponseCache.clear_cache() which clears its backend.
+ */
+export declare function clearCache(): Promise<void>;
+/**
+ * Get KV cache stats — reports the same backend that cacheGet/cacheSet/cacheDelete use,
+ * so a value stored via cacheSet() is reflected here. Mirrors cache_stats() in the
+ * Python / PHP / Ruby frameworks. (Identical to cacheBackendStats(), kept for parity naming.)
+ * ASYNC on Node — callers `await cacheStats()`.
+ */
+export declare function cacheStats(): Promise<{
+    hits: number;
+    misses: number;
+    size: number;
+    backend: string;
+}>;
+/** Get a value from the cache by key. Returns undefined on miss. */
+export declare function cacheGet(key: string): Promise<unknown | undefined>;
+/** Store a value in the cache with optional TTL (seconds). */
+export declare function cacheSet(key: string, value: unknown, ttl?: number): Promise<void>;
+/** Delete a key from the cache. Returns true if it existed. */
+export declare function cacheDelete(key: string): Promise<boolean>;
+/** Clear all entries from the cache. */
+export declare function cacheClear(): Promise<void>;
+/** Remove expired entries from the cache. Returns count removed. */
+export declare function sweep(): Promise<number>;
+/** Return cache statistics from the active backend. */
+export declare function cacheBackendStats(): Promise<{
+    hits: number;
+    misses: number;
+    size: number;
+    backend: string;
+}>;
+/** Reset the default backend (for testing). Closes any pooled connection. */
+export declare function _resetBackend(): void;

package/types/core/src/constants.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Tina4 Constants — HTTP status codes and content types.
+ *
+ * Standard constants for use in route handlers across all Tina4 frameworks.
+ *
+ *   import { HTTP_OK, HTTP_CREATED, APPLICATION_JSON } from "@tina4/core";
+ *
+ *   get("/api/users", async (request, response) => {
+ *       return response(users, HTTP_OK);
+ *   });
+ */
+export declare const HTTP_OK = 200;
+export declare const HTTP_CREATED = 201;
+export declare const HTTP_ACCEPTED = 202;
+export declare const HTTP_NO_CONTENT = 204;
+export declare const HTTP_MOVED = 301;
+export declare const HTTP_REDIRECT = 302;
+export declare const HTTP_NOT_MODIFIED = 304;
+export declare const HTTP_BAD_REQUEST = 400;
+export declare const HTTP_UNAUTHORIZED = 401;
+export declare const HTTP_FORBIDDEN = 403;
+export declare const HTTP_NOT_FOUND = 404;
+export declare const HTTP_METHOD_NOT_ALLOWED = 405;
+export declare const HTTP_CONFLICT = 409;
+export declare const HTTP_GONE = 410;
+export declare const HTTP_UNPROCESSABLE = 422;
+export declare const HTTP_TOO_MANY = 429;
+export declare const HTTP_SERVER_ERROR = 500;
+export declare const HTTP_BAD_GATEWAY = 502;
+export declare const HTTP_UNAVAILABLE = 503;
+export declare const APPLICATION_JSON = "application/json";
+export declare const APPLICATION_XML = "application/xml";
+export declare const APPLICATION_FORM = "application/x-www-form-urlencoded";
+export declare const APPLICATION_OCTET = "application/octet-stream";
+export declare const TEXT_HTML = "text/html; charset=utf-8";
+export declare const TEXT_PLAIN = "text/plain; charset=utf-8";
+export declare const TEXT_CSV = "text/csv";
+export declare const TEXT_XML = "text/xml";

package/types/core/src/container.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Lightweight dependency injection container.
+ *
+ * Matches the Python tina4_python.container.Container API.
+ *
+ *   import { Container, container } from "@tina4/core";
+ *
+ *   container.register("mailer", () => new MailService());
+ *   container.singleton("db", () => new Database("sqlite:///app.db"));
+ *
+ *   const mailer = container.get<MailService>("mailer"); // new instance each call
+ *   const db     = container.get<Database>("db");        // same instance every call
+ *
+ * Node.js is single-threaded so no locking is needed.
+ */
+export declare class Container {
+    private transients;
+    private singletons;
+    private instances;
+    /**
+     * Register a transient factory — a new instance is created on every `get()` call.
+     */
+    register(name: string, factory: () => unknown): void;
+    /**
+     * Register a singleton factory — created once on first `get()`, then memoised.
+     */
+    singleton(name: string, factory: () => unknown): void;
+    /**
+     * Resolve a dependency by name.
+     *
+     * Throws an `Error` if the name has not been registered.
+     */
+    get<T = unknown>(name: string): T;
+    /**
+     * Return `true` if *name* has been registered (transient or singleton).
+     */
+    has(name: string): boolean;
+    /**
+     * Clear all registrations and cached instances.
+     */
+    reset(): void;
+}
+/** Default container instance. */
+export declare const container: Container;

package/types/core/src/context/chunker.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Lowercase, strip diacritics, join comma-grouped numbers, split camelCase.
+ *
+ * Applied symmetrically to the indexed `body` and to query tokens so matching
+ * is consistent: a query for `field` reaches `IntegerField`. The trailing
+ * NFKD-normalise + strip-non-ASCII mirrors python's
+ * `unicodedata.normalize("NFKD", ...).encode("ascii", "ignore")`.
+ */
+export declare function fold(text: string): string;
+/**
+ * Fold simple plurals: strip one trailing 's', never from ss/us/is endings
+ * (class, status, axis). QUERY-side only — so `fields` in a question also
+ * reaches `Field` definitions.
+ */
+export declare function lightStem(token: string): string;
+/** Accent-folded lowercase alphanumeric tokens (digits kept). */
+export declare function terms(text: string): string[];
+/**
+ * Chunk source on top-level def/class/decorator boundaries (sentence chunking
+ * shreds code). Segments are packed up to `maxLines`, and every chunk starts
+ * with a `# file: <path>` line so the path's tokens are indexed — 'where is the
+ * router?' should match core/router.ts by name.
+ *
+ * Returns a list of `[index, chunkText]` pairs.
+ */
+export declare function chunkCode(text: string, path?: string, maxLines?: number): Array<[number, string]>;
+/**
+ * Chunk prose/docs into sentence-packed windows of at most `maxWords` words.
+ * Returns a list of `[index, chunkText]` pairs.
+ */
+export declare function chunkText(text: string, maxWords?: number): Array<[number, string]>;

package/types/core/src/context/index.d.ts

@@ -0,0 +1,93 @@
+/** True if this build of node:sqlite supports FTS5. */
+export declare function fts5Supported(): boolean;
+export interface SearchHit {
+    path: string;
+    score: number;
+    snippet: string;
+}
+/**
+ * A SQLite FTS5 index over a project's source + docs.
+ *
+ * - indexPath(file, label?)  upsert one file (delete-by-path, re-chunk, insert)
+ * - indexRoot(root)          walk a tree, index every eligible file
+ * - search(query, k)         [{path, score, snippet}] ranked by bm25() with
+ *                            source-over-tests + definition-first reordering
+ * - reindexFile(changed)     upsert one changed file against the indexed root
+ */
+export declare class Context {
+    path: string;
+    root: string | null;
+    available: boolean;
+    private conn;
+    /**
+     * @param dbPath    on-disk index file (its parent dir is created).
+     * @param fts5Check overrides FTS5 detection (used by tests to exercise the
+     *                  graceful-degradation path); defaults to a real probe.
+     */
+    constructor(dbPath?: string, fts5Check?: () => boolean);
+    /** Whether this Node build's node:sqlite supports FTS5. */
+    static fts5Available(): boolean;
+    private ensureTable;
+    /** Drop and recreate the index (full rebuild starting point). */
+    reset(): void;
+    private static chunksFor;
+    /**
+     * UPSERT one file into the index: delete this path's existing chunks,
+     * re-chunk the current contents, insert. `label` is the stored/citation path
+     * (defaults to `file`) and MUST be stable across calls for the same file so
+     * the delete targets the right rows. Returns rows inserted.
+     */
+    indexPath(file: string, label?: string): number;
+    /**
+     * The per-file filter used by both indexRoot and reindexFile. Directory
+     * skipping is handled separately.
+     */
+    private static eligible;
+    /**
+     * Walk `root`, indexing every eligible file (skips vendor/build/runtime
+     * dirs). Paths are stored RELATIVE to `root` for clean citations. Records
+     * `root` so reindexFile can relabel a changed file consistently. Returns the
+     * total number of chunks inserted.
+     */
+    indexRoot(root: string): number;
+    /**
+     * Re-index a single changed file into the LIVE index — the hook the dev
+     * WebSocket reload trigger (POST /__dev/api/reload) calls so code_search
+     * tracks edits without a rebuild. Resolves `changedPath` against the indexed
+     * root, then: outside root / under a skip-or-dot dir / ineligible → skip (-1);
+     * deleted → drop its chunks (0); otherwise UPSERT (rows). No-op (-1) until
+     * indexRoot has run (nothing to keep fresh yet).
+     */
+    reindexFile(changedPath: string): number;
+    private matchExpr;
+    private static isTestlike;
+    private static defines;
+    /**
+     * Return the top-`k` chunks as `[{path, score, snippet}]`, ranked by `bm25()`
+     * then reordered with two stable, proven passes:
+     *   - source-over-tests: a test that merely mentions a symbol sinks below the
+     *     source that defines it (skipped when the query is about tests);
+     *   - definition-first: a chunk that DEFINES a queried symbol rises above
+     *     chunks that only use it.
+     * Score is a higher-is-better float (sqlite's bm25 sign flipped).
+     */
+    search(query: string, k?: number): SearchHit[];
+    private static snippet;
+    count(): number;
+    isEmpty(): boolean;
+    close(): void;
+}
+export declare const _sharedContexts: Map<string, Context>;
+/**
+ * Get (or create) the process-wide Context at `db` (default
+ * `<cwd>/.tina4/context.db`). If `root` is given and the index is empty, builds
+ * it once. This is what code_search uses so the reload hook can keep the SAME
+ * index fresh.
+ */
+export declare function defaultContext(root?: string, db?: string): Context;
+/**
+ * Return the already-created shared Context for `db` (or undefined). Used by the
+ * reload hook so a file change reindexes an EXISTING index but never creates one
+ * on its own (nothing to keep fresh until code_search runs).
+ */
+export declare function existingContext(db?: string): Context | undefined;

package/types/core/src/devAdmin.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Tina4 Dev Admin — Built-in development dashboard, zero dependencies.
+ *
+ * Auto-registered admin panel for development mode.
+ * Provides API endpoints and a single-page UI at /__dev/ for:
+ *   - Route inspector (all registered routes, methods)
+ *   - Message log (tracked debug messages)
+ *   - Request inspector (captured HTTP requests)
+ *   - System info (Node.js version, V8, memory, uptime, platform)
+ */
+import type { Router } from "./router.js";
+interface LogEntry {
+    id: string;
+    timestamp: string;
+    category: string;
+    level: string;
+    message: string;
+    data?: unknown;
+}
+interface RequestEntry {
+    id: string;
+    timestamp: string;
+    method: string;
+    path: string;
+    status: number;
+    durationMs: number;
+}
+interface RequestStats {
+    total: number;
+    avgMs: number;
+    errors: number;
+    slowestMs: number;
+}
+interface ErrorEntry {
+    id: string;
+    timestamp: string;
+    message: string;
+    stack?: string;
+    resolved: boolean;
+}
+interface QueueJob {
+    id: string;
+    timestamp: string;
+    name: string;
+    status: "pending" | "completed" | "failed" | "reserved";
+    payload?: unknown;
+    result?: unknown;
+    error?: string;
+}
+interface WsConnection {
+    id: string;
+    connectedAt: string;
+    remoteAddress: string;
+    path: string;
+}
+export declare class MessageLog {
+    private static messages;
+    private static maxMessages;
+    static log(category: string, level: string, message: string, data?: unknown): void;
+    static get(category?: string, limit?: number): LogEntry[];
+    static clear(category?: string): void;
+    static count(): Record<string, number>;
+}
+export declare class RequestInspector {
+    private static requests;
+    private static maxRequests;
+    static capture(method: string, path: string, status: number, duration: number): void;
+    static get(limit?: number): RequestEntry[];
+    static stats(): RequestStats;
+    static clear(): void;
+}
+export declare class ErrorTracker {
+    private static errors;
+    private static maxErrors;
+    private static registered;
+    /**
+     * Capture an error with dedup (matches PHP/Ruby/Python signature).
+     * Duplicate errors (same message) increment count and update last_seen.
+     */
+    static capture(errorType: string, message: string, traceback?: string, file?: string, line?: number): void;
+    /** Legacy alias for capture (backward compatibility). */
+    static track(message: string, stack?: string): void;
+    static get(): ErrorEntry[];
+    static resolve(id: string): boolean;
+    static clearResolved(): void;
+    /** Remove ALL tracked errors. */
+    static clearAll(): void;
+    /** Health summary — are there unresolved errors? */
+    static health(): {
+        healthy: boolean;
+        total: number;
+        unresolved: number;
+        resolved: number;
+    };
+    /** Count of unresolved errors. */
+    static unresolvedCount(): number;
+    /** Reset all state (for testing). */
+    static reset(): void;
+    /**
+     * Register global error handlers to feed the tracker.
+     * Safe to call multiple times — only registers once.
+     */
+    static register(): void;
+}
+export declare class DevMailboxStore {
+    private static mailbox;
+    static inbox(folder?: string, limit?: number, offset?: number): import("./messenger.js").EmailMessage[];
+    static read(id: string): import("./messenger.js").EmailMessage | null;
+    static seed(count?: number): void;
+    static clear(folder?: string): void;
+    static unreadCount(): number;
+    static count(folder?: string): {
+        inbox: number;
+        outbox: number;
+        total: number;
+    };
+}
+export declare class DevQueue {
+    private static jobs;
+    static stats(): {
+        pending: number;
+        completed: number;
+        failed: number;
+        reserved: number;
+        jobs: QueueJob[];
+    };
+    static add(name: string, payload?: unknown): QueueJob;
+    static retryFailed(): number;
+    static purgeCompleted(): number;
+    static replay(id: string): QueueJob | undefined;
+}
+export declare class WsTracker {
+    private static connections;
+    static add(remoteAddress: string, path: string): string;
+    static remove(id: string): boolean;
+    static list(): WsConnection[];
+}
+export declare class DevAdmin {
+    /**
+     * Check whether dev mode is enabled.
+     */
+    static isEnabled(): boolean;
+    /**
+     * Register all /__dev routes on the given router.
+     */
+    static register(router: Router): void;
+    /**
+     * Returns the dev toolbar HTML to inject into HTML pages.
+     */
+    static renderToolbarHtml(ctx: {
+        version: string;
+        method: string;
+        path: string;
+        matchedPattern: string;
+        requestId: string;
+        routeCount: number;
+    }): string;
+}
+/**
+ * Return the base URL for the co-located Rust agent server.
+ *
+ * Mirrors Python's `_supervisor_base_url()` in
+ * `tina4_python/dev_admin/__init__.py`. Resolution order:
+ *   1. `TINA4_SUPERVISOR_URL` — explicit full URL.
+ *   2. `TINA4_AGENT_PORT` — explicit port on 127.0.0.1.
+ *   3. `PORT` + 2000 — auto-derived (matches `tina4 serve` agent port).
+ *   4. Fallback `http://127.0.0.1:9145` — matches standalone `tina4 agent`.
+ */
+export declare function supervisorBaseUrl(): string;
+/**
+ * Resolve a CodeMirror-friendly language id from a file path's basename.
+ *
+ * - `Dockerfile` / `Dockerfile.dev` / `Dockerfile.prod` (no extension) → "dockerfile"
+ * - `.env.example` (two-part) and `.env` → "env"
+ * - otherwise the file extension is looked up in DEV_ADMIN_LANG_MAP
+ * - anything unknown → "text"
+ */
+export declare function devAdminLanguage(rel: string): string;
+export {};

package/types/core/src/devMailbox.d.ts

@@ -0,0 +1,54 @@
+import type { SendResult, EmailMessage } from "./messenger.js";
+export declare class DevMailbox {
+    private mailboxDir;
+    constructor(mailboxDir?: string);
+    /**
+     * Ensure a folder directory exists.
+     */
+    private ensureFolder;
+    /**
+     * Capture an email to the dev mailbox instead of sending it.
+     *
+     * The parameter order MATCHES Messenger.send() on purpose. It did not before:
+     * send()'s 5th positional was `text` and capture()'s was `cc`, so the same call
+     * meant different things depending on which door it came through -- that mismatch
+     * IS nodejs#42.
+     *
+     * BREAKING: `text` is now the 5th positional. A caller passing cc positionally
+     * must move it. Aligning the two signatures is the fix; leaving them apart would
+     * preserve the bug.
+     */
+    capture(to: string | string[], subject: string, body: string, html?: boolean, text?: string, cc?: string | string[], bcc?: string | string[], replyTo?: string, attachments?: string[], from?: string): SendResult;
+    /**
+     * List messages from a folder (default: inbox).
+     */
+    inbox(limit?: number, offset?: number, folder?: string): EmailMessage[];
+    /**
+     * Read a single message by ID. Searches all folders.
+     */
+    read(msgId: string): EmailMessage | null;
+    /**
+     * Count unread messages in the inbox.
+     */
+    unreadCount(): number;
+    /**
+     * Delete a message by ID. Removes from all folders.
+     */
+    delete(msgId: string): boolean;
+    /**
+     * Clear all messages from a folder, or all folders if none specified.
+     */
+    clear(folder?: string): void;
+    /**
+     * Seed the mailbox with sample messages for development.
+     */
+    seed(count?: number): void;
+    /**
+     * Count messages in a folder, or all folders if none specified.
+     */
+    count(folder?: string): {
+        inbox: number;
+        outbox: number;
+        total: number;
+    };
+}