gina 0.3.2 → 0.3.3

package/llms.txt

@@ -42,6 +42,35 @@ framework/v${version}/
 
 ---
 
+## Vendored dependencies (`core/deps/`)
+
+| Package | Version | Notes |
+|---|---|---|
+| `optimist` | 0.6.1 | CLI arg parsing. Uses `minimist ~1.2.8` and `wordwrap ~1.0.0`. |
+| `busboy` | 1.6.0 | Multipart form parsing. Requires `streamsearch` (vendored alongside). |
+| `streamsearch` | 1.1.0 | Boyer-Moore-Horspool stream searching. Dependency of `busboy`. |
+| `swig-client` | custom | Client-side Swig for browser template rendering. |
+
+### Swig — `@rhinostone/swig` (npm dependency)
+
+Maintained fork of the abandoned swig 1.4.2 template engine. Published to npm as `@rhinostone/swig@1.4.4` (npm org: `rhinostone`, maintainer: `beemaster`). Repo: `https://github.com/gina-io/swig`. Declared in `framework/v*/package.json` — installed via `npm install` inside the framework directory. Requires `npm install` after clone, merge, or worktree switch (the framework `node_modules/` is gitignored).
+
+Previously vendored at `core/deps/swig-1.4.2/` — removed in the migration to the npm dep. CVE-2023-25345 parse-time blocklist (`__proto__`/`constructor`/`prototype`) is patched in the fork's `parser.js` and `tags/set.js`. The path traversal boundary check in `controller.render-swig.js` is Gina's own code and is unaffected by this migration.
+
+---
+
+## TypeScript declarations & explicit exports
+
+**TypeScript declarations** — `types/index.d.ts`, `types/globals.d.ts`, `types/gna.d.ts`. Covers `SuperController`, `EntitySuper`, all global helpers, `PathObject`, `uuid`, `ApiError`, config file interfaces (`RoutingConfig`, `ConnectorsConfig`, `AppConfig`, `SettingsConfig`, `ManifestConfig`, `WatchersConfig`, `CronsConfig`), `GinaRequest`/`GinaResponse`, and the `Gna` lifecycle module. `package.json` has `"types": "./types/index.d.ts"` and `"typesVersions"` for `gina/gna`.
+
+**Explicit exports** — `require('gina/gna')` returns an object with all global helpers as named properties:
+```javascript
+const { getContext, _, onCompleteCall, uuid, SuperController } = require('gina/gna');
+```
+Uses lazy getters — symbols resolve at access time (after framework boot). The globals are still injected as before; this adds an importable path for IDE navigation and static analysis. Entry point: `gna.js` at package root.
+
+---
+
 ## Global helpers (injected by gna.js — no require needed)
 
 ```javascript
@@ -57,6 +86,20 @@ setEnvVar(key, val, protect) // Write env variable
 onCompleteCall(emitter)          // Wraps an EventEmitter .onComplete(cb) into a native Promise — lib/async/src/main.js, also available as global and via lib.async
 ```
 
+## Bare-module require — `require('lib/<name>')`
+
+Bundle entities, controllers, and middleware can `require()` framework libraries as bare modules from any depth:
+
+```javascript
+var uuid    = require('lib/uuid');     // → framework/v<version>/lib/uuid/
+var merge   = require('lib/merge');    // → framework/v<version>/lib/merge/
+var routing = require('lib/routing');  // → framework/v<version>/lib/routing/
+```
+
+`gna.js` injects the framework path into `process.env.NODE_PATH` and calls `require('module').Module._initPaths()` at bootstrap. This mirrors the frontend RequireJS path alias convention and removes the need for relative paths like `require('../../../../framework/v<version>/lib/uuid')`.
+
+Every `lib/<name>/` directory must have a `package.json` with `"main": "src/main"` (see `lib/merge/package.json` for the canonical pattern).
+
 ---
 
 ## Controller pattern
@@ -363,6 +406,31 @@ Counters are live — no restart required. `activeSessions` is bounded by ≥ 0.
 
 ---
 
+## OpenAPI spec generation
+
+`gina bundle:openapi <bundle> @<project>` reads `routing.json` and emits an OpenAPI 3.1.0 `openapi.json` in the bundle's `config/` directory. No manual spec writing required.
+
+Mapping from routing.json to OpenAPI:
+
+| routing.json field | OpenAPI equivalent |
+| --- | --- |
+| `url` (`:param` syntax) | `paths` (`{param}` syntax) |
+| `method` | HTTP operations under each path |
+| `param.control` | `operationId` |
+| `namespace` | `tags` |
+| `requirements` (regex) | `parameters[].schema.pattern` |
+| `requirements` (pipe-separated) | `parameters[].schema.enum` |
+| `_comment` | operation `description` |
+| `_sample` | `x-sample-url` extension |
+| `param.title` | operation `summary` |
+| `middleware` | `x-middleware` extension |
+| `cache` | `Cache-Control` response header docs |
+| `param.code` + `param.path` (redirects) | 3xx response with `Location` header |
+
+To enrich the generated spec, add `_comment` (description) and `_sample` (example URL) fields to your routes. The `namespace` field groups operations into tags.
+
+---
+
 ## Project config files
 
 | File | Location | Purpose |
@@ -420,6 +488,9 @@ gina bundle:add <bundle> @<project>     # Scaffold a new bundle (overwrites exis
 gina bundle:add <bundle> @<project> --import  # Register existing bundle (preserves src)
 gina bundle:remove <bundle> @<project>  # Remove a bundle
 gina bundle:list @<project>             # List bundles
+gina bundle:openapi <bundle> @<project> # Generate OpenAPI 3.1.0 spec from routing.json
+gina bundle:oas <bundle> @<project>     # Alias for bundle:openapi
+gina bundle:openapi @<project> --output=/path/to/spec.json  # Custom output path
 gina view:add <bundle> @<project>       # Add HTML templates to a bundle
 gina tail --follow                      # Follow logs
 gina framework:set --env=dev            # Set framework setting
@@ -433,8 +504,6 @@ gina-init                               # Bootstrap ~/.gina/ from env vars (cont
 
 **CLI stubs — commands that appear in docs or help.txt but are NOT implemented (handler files are empty or missing):**
 
-- `port:set` — empty handler; use `port:reset --start-port-from=<N>` to re-allocate all ports
-- `framework:get` — empty handler; use `env:get` to read settings
 - `bundle:status` / `bundle:rename` / `bundle:copy` — comments-only handler files
 - `project:status` / `project:move` / `project:backup` / `project:restore` — empty or missing
 - `protocol:remove` — no handler file (also has a typo "remouve" in help.txt)
@@ -525,7 +594,8 @@ Dev-mode query instrumentation captures every database query tied to the current
 - **`origin` tagging** — `infos.bundle` (set on `Entity.prototype.bundle` at registration). **`connector` tagging** — hardcoded string per connector.
 - **Cross-bundle propagation** — when bundle A calls B via `self.query()`, B's queries travel back as `__ginaQueries` in the JSON response (embedded by `render-json.js`). A's `query()` callback extracts, merges into its own `local._queryLog`, and deletes the field before data reaches the controller action.
 - **Index reporting (Couchbase)** — `extractIndexes(profile)` walks `meta.profile.executionTimings` tree (`~child`/`~children` recursion) to find `IndexScan3`/`PrimaryScan3`/`ExpressionScan`/`KeyScan` operators and extract index names. Two extraction paths: `meta.profile` (fast, SDK v3) and EXPLAIN fallback (SDK v4 — C++ binding doesn't surface `meta.profile`). `_explainCache` Map caches per unique statement. `USE KEYS` queries detected via `ExpressionScan`/`KeyScan` operators. Enabled by `queryOptions.profile = 'timings'` in dev mode for SDK v3+. Three visual states: green (secondary), amber (primary scan), red (no index). Grey N/A badge for unsupported connectors.
-- **Index reporting (SQL connectors — #QI1)** — `sql-parser.js` provides `parseCreateIndexes(src)` (parses `CREATE [UNIQUE] INDEX` statements → `{ tableName: [{ name, primary }] }` map) and `extractTargetTable(queryString)` (extracts primary table from SELECT/INSERT/UPDATE/DELETE). Each SQL connector reads an optional `indexes.sql` from the bundle's `sql/` directory at init time, builds an in-memory `_knownIndexes` map. QI resolves `_queryEntry.indexes` per query: `null` when no `indexes.sql` (N/A badge), `[]` when file exists but no index covers the table (red badge), `[{name, primary}]` when matched (green badge). No EXPLAIN round-trip — index knowledge comes from the project's own schema definitions.
+- **Index reporting (SQL connectors — #QI1 Phase A)** — `sql-parser.js` provides `parseCreateIndexes(src)` (parses `CREATE [UNIQUE] INDEX` statements → `{ tableName: [{ name, primary }] }` map) and `extractTargetTable(queryString)` (extracts primary table from SELECT/INSERT/UPDATE/DELETE). Each SQL connector reads an optional `indexes.sql` from the bundle's `sql/` directory at init time, builds an in-memory `_knownIndexes` map. QI resolves `_queryEntry.indexes` per query: `null` when no `indexes.sql` (N/A badge), `[]` when file exists but no index covers the table (red badge), `[{name, primary}]` when matched (green badge).
+- **Live index introspection (#QI1 Phase B)** — `/_gina/indexes` endpoint (dev-mode only, both `server.js` and `server.isaac.js`) queries actual databases for their indexes. Emits `process.emit('inspector#indexes', callback)` — each SQL connector registers a listener inside its constructor closure and responds with live index data. MySQL queries `INFORMATION_SCHEMA.STATISTICS`, PostgreSQL queries `pg_indexes`, SQLite uses `sqlite_master` + `PRAGMA index_list`. Collector pattern with 2-second timeout. `_liveIntrospected` flag prevents re-querying. Inspector SPA calls the endpoint lazily (only when N/A badges are present), caches result, and re-renders Query tab with resolved indexes. Eliminates the need for manual `indexes.sql` files.
 - **Inspector UI** — split trigger badge (`entity` | `method`), SQL syntax highlighting, params table (`$1`/`$2` → value), free-text search bar with 200ms debounce, per-card weight color-coding (`bm-stat-*`), filter persistence (lang/connector/bundle in localStorage), pagination (20 cards default, "Show all" button).
 
 **UX enhancements:**
@@ -541,6 +611,25 @@ Dev-mode query instrumentation captures every database query tied to the current
 
 ---
 
+## Client-side plugins (`core/asset/plugin/`)
+
+**Source:** `src/vendor/gina/` — AMD modules bundled into `dist/vendor/gina/js/gina.min.js` via RequireJS + Closure Compiler.
+
+**Popin** (`src/vendor/gina/popin/main.js`) — client-side dialog/modal component. Manages popup lifecycle (register, load, open, close, destroy), XHR content loading, event wiring, and `<dialog>` element support.
+
+- **Performance:** `_nextId()` counter replaces `crypto.randomUUID()`; `querySelectorAll` replaces `getElementsByAttribute`/`getElementsByTagName` for DOM scanning; `classList` API replaces `className` string manipulation; cached `RegExp` for click handlers; DOM-injected `<script>`/`<link>` elements replace XHR+`eval()` for asset loading; per-load XHR creation prevents concurrent state sharing; `popinBind` dedup guard avoids redundant binding.
+- **`popinDestroy(name)`** — full teardown: closes if open, removes DOM element, removes all event listeners (loaded/ready/open/close), cleans up `instance.$popins` and `registeredPopins`, resets `activePopinId`, fires `destroy` event.
+- **`$popin.$headers`** — tracks injected `<script>` and `<link>` element IDs. Cleaned up in `popinClose`.
+- **`ginaToolbar` integration** — 13 refs; `popinClose` is the only `restore()` call site. `update()` calls sync XHR overlay data to the Inspector.
+
+**Events** (`src/vendor/gina/utils/events.js`) — core event system with XHR lifecycle management (`setupXhr`, `handleXhr`). Bundled into `gina.min.js`.
+
+**Binding** (`src/vendor/gina/helpers/binding.js`) — processes binding descriptor arrays (call/handler/payload). AMD module.
+
+**Unit tests:** `test/core/popin.test.js` (37 tests — perf optimizations, DOM injection, dedup guard, per-load XHR, popinDestroy, registeredPopins, events.js regex/typo, binding.js precedence, dist verification).
+
+---
+
 ## Home directory (~/.gina/)
 
 ```
@@ -576,7 +665,7 @@ Dev-mode query instrumentation captures every database query tied to the current
 15. **Sidebar icon key = `sidebar_label.toLowerCase()`** — `Root.js` `NAV_ICONS` map in the Docusaurus site uses the **lowercase** value of the page's `sidebar_label` frontmatter as the map key. If an icon doesn't render, verify the key matches exactly (e.g. `sidebar_label: Security` → key `'security'`).
 16. **Post-merge state check required after every `git merge --ff-only`** — `post_install.js` does NOT run on a git pull/merge; it only runs on `npm install`. When the version changes (especially a `shortVersion` bump like `0.2 → 0.3`), three state stores go stale simultaneously: `~/.gina/main.json` (`def_framework`, `frameworks["${shortVersion}"]`, all metadata keys), `~/.gina/${shortVersion}/settings.json` (missing entirely), and `gina.db` `kv_store` (`main` + `settings/${shortVersion}` keys). Running `npm install` from inside the repo also fails (symlink error — `node_modules/.bin/` does not exist in the worktree layout); patch the state files directly instead. See `.claude/git.md § Post-merge state check` for the full checklist.
 17. **Merge frequency** — merge `dev/wip` → `develop` after every feature/fix (frequent is good). Exception: hold at version boundaries (`0.3.x → 0.4.x`, `0.x → 1.x`) until the full release is prepared, because `git mv framework/v*/` during merge is a live deployment of the globally-installed CLI. See `.claude/architecture/git-workflow.md` for the full decision framework.
-18. **CLI stubs** — several CLI commands appear in help.txt or docs but have empty/missing handler files and do NOT work: `port:set`, `framework:get`, `bundle:status/rename/copy`, `project:status/move/backup/restore`, `protocol:remove`, `minion:kill/list`, `framework:update`, `gina --status/-t`. Never suggest these to users. Workarounds: `port:reset --start-port-from=<N>` for port re-allocation, `env:get` for reading settings. Full inventory in `.claude/cli-reference.md`.
+18. **CLI stubs** — several CLI commands appear in help.txt or docs but have empty/missing handler files and do NOT work: `bundle:status/rename/copy`, `project:status/move/backup/restore`, `protocol:remove`, `minion:kill/list`, `framework:update`, `gina --status/-t`. Never suggest these to users. Full inventory in `.claude/cli-reference.md`. Note: `port:set`, `framework:get`, and `bundle:openapi` were implemented in `0.3.3-alpha.2`.
 19. **`namespace` is required to target a namespace controller** — omitting `"namespace": "content"` from a routing rule makes the router look in `controller.js` instead of `controller.content.js`. The error surface is "control not found: `list`" pointing at `controller.js`, which is confusing. Always set `namespace` when your action lives in a namespace controller file.
 20. **URL params need `"id": ":id"` in `param` to reach `req.params`** — declaring `"url": "/notes/:id"` is not enough. You must also add `"id": ":id"` inside the `param` block so the router binds the segment to `req.params.id`. `requirements` are optional (any non-empty segment is accepted when omitted); the `param` binding is not.
 21. **`throwError(res, code, stringMsg)` preserves the status code** — calling `self.throwError(res, 404, 'Not found')` sends 404. Previously the string-message branch unconditionally replaced `code` with `res.status || 500`. Fixed in `core/controller/controller.js`. If you previously worked around this by wrapping your message in `new Error(...)`, that still works unchanged.
@@ -603,4 +692,5 @@ Dev-mode query instrumentation captures every database query tied to the current
 39. **`getAssets()` warns on inline `<script>` tags** — `server.js:811` regex matches all `<script>...</script>` tags in the rendered HTML, including inline ones. Inline scripts have no `src` attribute, so the `urlArr` match at line 927 returns `null`, causing `urlArr.length` to throw into the catch block that prints `"Problem with this asset"`. Fix: skip `<script>` tags without `\ssrc\s*=` after the tag detection block. The `\s` before `src` prevents false matches on `data-src`. Inline scripts are not external assets — they have no URL to catalog.
 40. **`queryParams` vs `queryOptions` at `conn._cluster.query()`** — the Couchbase connector's `conn._cluster.query()` must receive the full `queryOptions` object (which includes `parameters: queryParams`, `profile`, `scanConsistency`, `adhoc`), NOT the raw `queryParams` array. Passing `queryParams` silently drops all non-parameter options because the SDK only reads named properties from the options object. This bug existed at lines 892 and 934 for years, invisibly disabling `profile: 'timings'`, `scanConsistency`, and `adhoc: false` on every SDK v3+ query.
 41. **Option B is the active dispatch path in the Couchbase connector** — `register()` in `readSource()` has two paths: Option A (`self._isRegisteredFromProto === true`) and Option B (`!self._isRegisteredFromProto`). Option B is always active for all connector-generated entity methods. When adding debug logging or QI instrumentation to the query execution path, place it in Option B — Option A is dead code.
+42. **Validator touched-field-only error display** — the validator runs a global validation pass on every field blur to determine submit button state (`isFormValid`). The global pass must NOT display errors for untouched fields — only for `event.target.name` (the field the user actually touched). Two call sites in `validator/src/main.js`: ~line 3337 (within the `isFormValid && gResult.error` block) and ~line 4865 (same pattern in the second validation path). The global pass still correctly disables/enables the submit button.
 42. **Docker `node_modules` isolation** — Docker containers using `node_modules` anonymous volumes have their own copy of all npm packages. Edits to `node_modules/` on the host are invisible inside the container. To debug SDK-level behaviour, either `docker exec` and edit inside the container, or add logging to the framework connector code (which IS bind-mounted) rather than the SDK itself.

package/package.json

@@ -1,112 +1,118 @@
 {
-    "name": "gina",
-    "version": "0.3.2",
-    "description": "Node.js MVC framework with built-in HTTP/2, multi-bundle architecture, and scope-based data isolation — no Express dependency",
-    "keywords": [
-        "nodejs",
-        "framework",
-        "mvc",
-        "http2",
-        "rest-api",
-        "full-stack",
-        "server-side-rendering",
-        "event-driven",
-        "multi-bundle",
-        "couchbase",
-        "mongodb",
-        "typescript",
-        "gina",
-        "ginajs"
-    ],
-    "homepage": "https://gina.io",
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/gina-io/gina.git"
+  "name": "gina",
+  "version": "0.3.3",
+  "description": "Node.js MVC framework with built-in HTTP/2, multi-bundle architecture, and scope-based data isolation — no Express dependency",
+  "keywords": [
+    "nodejs",
+    "framework",
+    "mvc",
+    "http2",
+    "rest-api",
+    "full-stack",
+    "server-side-rendering",
+    "event-driven",
+    "multi-bundle",
+    "couchbase",
+    "mongodb",
+    "typescript",
+    "gina",
+    "ginajs"
+  ],
+  "homepage": "https://gina.io",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gina-io/gina.git"
+  },
+  "bugs": {
+    "url": "https://github.com/gina-io/gina/issues",
+    "email": "bugs@gina.io"
+  },
+  "author": {
+    "name": "Martin-Luther ETOUMAN",
+    "email": "martin-luther.etouman@gina.io"
+  },
+  "contributors": [
+    {
+      "name": "Martin-Luther ETOUMAN",
+      "email": "martin-luther.etouman@gina.io"
     },
-    "bugs": {
-        "url": "https://github.com/gina-io/gina/issues",
-        "email": "bugs@gina.io"
-    },
-    "author": {
-        "name": "Martin-Luther ETOUMAN",
-        "email": "martin-luther.etouman@gina.io"
-    },
-    "contributors": [
-        {
-            "name": "Martin-Luther ETOUMAN",
-            "email": "martin-luther.etouman@gina.io"
-        },
-        {
-            "name": "Fabrice DELANEAU",
-            "email": "fabrice.delaneau@gina.io",
-            "url": "https://fdelaneau.com"
-        }
-    ],
-    "copyright": "Copyright (c) 2009-2026 Rhinostone <contact@gina.io>",
-    "engine": {
-        "node": ">= 22 <26"
+    {
+      "name": "Fabrice DELANEAU",
+      "email": "fabrice.delaneau@gina.io",
+      "url": "https://fdelaneau.com"
+    }
+  ],
+  "copyright": "Copyright (c) 2009-2026 Rhinostone <contact@gina.io>",
+  "engine": {
+    "node": ">= 22 <26"
+  },
+  "config": {
+    "optionalPrefix": "~/.npm-global",
+    "prefix": "~/.npm-global",
+    "globalMode": true
+  },
+  "bin": {
+    "gina": "bin/gina",
+    "gina-container": "bin/gina-container",
+    "gina-init": "bin/gina-init"
+  },
+  "main": "./framework/v0.3.3/core/gna",
+  "types": "./types/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "gna": ["./types/gna.d.ts"]
+    }
+  },
+  "scripts": {
+    "test": "node --test test*.test.js",
+    "prepare": "node script/prepare_version.js",
+    "postpublish": "node script/post_publish.js",
+    "preinstall": "node script/pre_install.js",
+    "postinstall": "node script/post_install.js"
+  },
+  "license": "MIT",
+  "readmeFilename": "README.md",
+  "dependencies": {
+    "engine.io": "^6.0.0"
+  },
+  "devDependencies": {
+    "engine.io-client": "^6.6.3",
+    "requirejs": "^2.3.7"
+  },
+  "peerDependencies": {
+    "@anthropic-ai/sdk": ">=0.27.0",
+    "@scylladb/scylla-driver": ">=1.0.0",
+    "couchbase": ">=3.0.0",
+    "ioredis": ">=5.0.0",
+    "mongodb": ">=5.0.0",
+    "mysql2": ">=2.0.0",
+    "openai": ">=4.0.0",
+    "pg": ">=8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "couchbase": {
+      "optional": true
     },
-    "config": {
-        "optionalPrefix": "~/.npm-global",
-        "prefix": "~/.npm-global",
-        "globalMode": true
+    "ioredis": {
+      "optional": true
     },
-    "bin": {
-        "gina": "bin/gina",
-        "gina-container": "bin/gina-container",
-        "gina-init": "bin/gina-init"
+    "mysql2": {
+      "optional": true
     },
-    "main": "./framework/v0.3.2/core/gna",
-    "scripts": {
-        "test": "node --test test*.test.js",
-        "prepare": "node script/prepare_version.js",
-        "postpublish": "node script/post_publish.js",
-        "preinstall": "node script/pre_install.js",
-        "postinstall": "node script/post_install.js"
+    "pg": {
+      "optional": true
     },
-    "license": "MIT",
-    "readmeFilename": "README.md",
-    "dependencies": {
-        "engine.io": "^6.0.0"
+    "mongodb": {
+      "optional": true
     },
-    "devDependencies": {
-        "engine.io-client": "^6.6.3",
-        "requirejs": "^2.3.7"
+    "@scylladb/scylla-driver": {
+      "optional": true
     },
-    "peerDependencies": {
-        "@anthropic-ai/sdk": ">=0.27.0",
-        "@scylladb/scylla-driver": ">=1.0.0",
-        "couchbase": ">=3.0.0",
-        "ioredis": ">=5.0.0",
-        "mongodb": ">=5.0.0",
-        "mysql2": ">=2.0.0",
-        "openai": ">=4.0.0",
-        "pg": ">=8.0.0"
+    "openai": {
+      "optional": true
     },
-    "peerDependenciesMeta": {
-        "couchbase": {
-            "optional": true
-        },
-        "ioredis": {
-            "optional": true
-        },
-        "mysql2": {
-            "optional": true
-        },
-        "pg": {
-            "optional": true
-        },
-        "mongodb": {
-            "optional": true
-        },
-        "@scylladb/scylla-driver": {
-            "optional": true
-        },
-        "openai": {
-            "optional": true
-        },
-        "@anthropic-ai/sdk": {
-            "optional": true
-        }
+    "@anthropic-ai/sdk": {
+      "optional": true
     }
+  }
 }

package/types/globals.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Gina Framework — Global type augmentations
+ *
+ * These symbols are injected on the `global` scope at framework boot time.
+ * No import required — they are available everywhere in a running Gina app.
+ *
+ * @packageDocumentation
+ */
+
+import { EventEmitter } from 'events';
+
+// ─── PathObject ──────────────────────────────────────────────────────────────
+
+/**
+ * Array-like result returned by `_().toArray()`.
+ */
+interface PathArray extends Array<string> {
+    first(): string;
+    index(i: number): string;
+    last(): string;
+}
+
+/**
+ * Object returned by `_(path)` when the path is resolvable.
+ * Provides file-system helpers with both sync and async (EventEmitter) APIs.
+ */
+interface PathObject {
+    /** Resolved absolute path */
+    readonly path: string;
+    /** Alias for `.path` */
+    readonly value: string;
+    /** Basename of the path */
+    readonly key: string;
+    /** Platform path separator */
+    readonly sep: string;
+    /** First segment of the path */
+    readonly start: string;
+
+    toString(): string;
+    toArray(): PathArray;
+
+    existsSync(): boolean;
+    exists(callback: (exists: boolean) => void): void;
+    isDirectory(): boolean;
+    isSymlinkSync(): boolean;
+    getSymlinkSourceSync(): string;
+    isWritableSync(): boolean;
+    isWritable(callback: (writable: boolean) => void): void;
+    hasFile(search: string, callback: (err: Error | null, found: boolean) => void): void;
+
+    mkdirSync(): void;
+    mkdir(): EventEmitter & { onComplete(cb: (err: Error | null) => void): void };
+    cp(target: string, options?: object): EventEmitter & { onComplete(cb: (err: Error | null) => void): void };
+    mv(target: string): EventEmitter & { onComplete(cb: (err: Error | null) => void): void };
+    rm(): EventEmitter & { onComplete(cb: (err: Error | null) => void): void };
+    rmSync(): void;
+}
+
+// ─── OnCompletable ───────────────────────────────────────────────────────────
+
+/** Any object that exposes `.onComplete(cb)` — the pattern used by entity methods and PathObject ops. */
+interface OnCompletable {
+    onComplete(cb: (err: any, result?: any) => void): void;
+}
+
+// ─── ApiError ────────────────────────────────────────────────────────────────
+
+interface ApiErrorConstructor {
+    new (errorMessage: string, fieldName?: string, errorStatus?: number): ApiError;
+    (errorMessage: string, fieldName?: string, errorStatus?: number): ApiError;
+}
+
+interface ApiError extends Error {
+    status: number;
+    error: string;
+    fields: Record<string, string>;
+    flash: Record<string, string>;
+}
+
+// ─── Locale types ────────────────────────────────────────────────────────────
+
+interface Country {
+    isoShort: string;
+    isoLong: string;
+    countryName: string;
+    officialStateName: string;
+}
+
+interface LocaleResult {
+    getCountries(code?: string): Country[];
+}
+
+// ─── uuid ────────────────────────────────────────────────────────────────────
+
+interface UuidFunction {
+    /**
+     * Generate a random base-62 ID.
+     * @param size - Number of characters (default: 4)
+     */
+    (size?: number): string;
+
+    /**
+     * Create a generator for a custom alphabet.
+     * @param alphabet - Characters to use
+     * @param defaultSize - Default output length
+     * @returns A generator function `(size?) => string`
+     */
+    customAlphabet(alphabet: string, defaultSize?: number): (size?: number) => string;
+}
+
+// ─── JSON augmentations ──────────────────────────────────────────────────────
+
+interface JSON {
+    /** Deep-clone any JSON-safe value */
+    clone<T>(obj: T): T;
+    /** Escape special characters in a string for safe embedding */
+    escape(str: string): string;
+}
+
+// ─── Global declarations ─────────────────────────────────────────────────────
+
+declare global {
+
+    // -- Path helpers --
+
+    /**
+     * Resolve a path string. Returns a `PathObject` when called as a constructor
+     * or the resolved path string when `force` is `true`.
+     */
+    function _(path: string, force: true): string;
+    function _(path: string, force?: boolean): PathObject;
+
+    function setPath(name: string, path: string): void;
+    function getPath(name: string): string | object;
+    function setPaths(paths: Record<string, string>): void;
+    function getPaths(): Record<string, string>;
+
+    /**
+     * Wrap an `.onComplete(cb)` emitter into a native Promise.
+     * Enables `await onCompleteCall(_(path).mkdir())`.
+     */
+    function onCompleteCall<T = any>(emitter: OnCompletable): Promise<T>;
+
+    // -- Context helpers --
+
+    function setContext(name: string, obj: any, force?: boolean): void;
+    function getContext(name: string): any;
+    function getContext(): Record<string, any>;
+    function resetContext(): void;
+    function getConfig(bundle?: string, confName?: string): any;
+    function getLib(bundle: string, lib?: string): any;
+    function whisper(dictionary: object, replaceable: string, rule?: RegExp): string | object;
+    function define(name: string, value: any): void;
+    function getDefined(): Array<{ name: string; value: any }>;
+
+    // -- Model helpers --
+
+    function getModel(bundle?: string, model?: string): any;
+    function getModelEntity(bundle: string, model: string, entityClassName: string, conn: any): any;
+
+    // -- JSON helper --
+
+    /** Load a JSON file with comment stripping. */
+    function requireJSON(filename: string): any;
+
+    // -- Task helper --
+
+    function run(cmdline: string, opt?: object, cb?: (err: Error | null, result?: any) => void): EventEmitter & OnCompletable;
+
+    // -- Env helpers --
+
+    function isWin32(): boolean;
+    function getEnvVar(key: string): any;
+    function getEnvVars(): Record<string, any>;
+    function setEnvVar(key: string, val: any, isProtected?: boolean): void;
+    function getUserHome(): string;
+    function getLogDir(): string;
+    function getRunDir(): string;
+    function getTmpDir(): string;
+    function parseTimeout(value: string | number): number | null;
+
+    // -- i18n stub --
+
+    function __(str: string): void;
+
+    // -- ApiError --
+
+    var ApiError: ApiErrorConstructor;
+
+    // -- Array augmentation --
+
+    interface Array<T> {
+        clone(): T[];
+    }
+
+    // -- String augmentation --
+
+    interface String {
+        ltrim(): string;
+        rtrim(): string;
+        gtrim(): string;
+    }
+}
+
+export { PathObject, PathArray, OnCompletable, ApiError, ApiErrorConstructor, UuidFunction, Country, LocaleResult };

package/types/gna.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Gina Framework — Explicit exports
+ *
+ * Type declarations for `require('gina/gna')`.
+ * Provides named imports for all global helpers, enabling IDE navigation
+ * and static analysis without relying on global scope injection.
+ *
+ * Usage:
+ *   const { getContext, _, onCompleteCall, uuid } = require('gina/gna');
+ */
+
+import type { UuidFunction } from './globals';
+import type { SuperController, EntitySuper } from './index';
+
+interface GinaExports {
+    // Context helpers
+    setContext: typeof globalThis.setContext;
+    getContext: typeof globalThis.getContext;
+    resetContext: typeof globalThis.resetContext;
+    getConfig: typeof globalThis.getConfig;
+    getLib: typeof globalThis.getLib;
+    whisper: typeof globalThis.whisper;
+    define: typeof globalThis.define;
+    getDefined: typeof globalThis.getDefined;
+
+    // Path helpers
+    _: typeof globalThis._;
+    setPath: typeof globalThis.setPath;
+    getPath: typeof globalThis.getPath;
+    setPaths: typeof globalThis.setPaths;
+    getPaths: typeof globalThis.getPaths;
+    onCompleteCall: typeof globalThis.onCompleteCall;
+
+    // Model helpers
+    getModel: typeof globalThis.getModel;
+    getModelEntity: typeof globalThis.getModelEntity;
+
+    // JSON helper
+    requireJSON: typeof globalThis.requireJSON;
+
+    // Task helper
+    run: typeof globalThis.run;
+
+    // Env helpers
+    getUserHome: typeof globalThis.getUserHome;
+    getEnvVar: typeof globalThis.getEnvVar;
+    getEnvVars: typeof globalThis.getEnvVars;
+    setEnvVar: typeof globalThis.setEnvVar;
+    getLogDir: typeof globalThis.getLogDir;
+    getRunDir: typeof globalThis.getRunDir;
+    getTmpDir: typeof globalThis.getTmpDir;
+    parseTimeout: typeof globalThis.parseTimeout;
+    isWin32: typeof globalThis.isWin32;
+
+    // Classes
+    SuperController: typeof SuperController;
+    EntitySuper: typeof EntitySuper;
+
+    // uuid
+    uuid: UuidFunction;
+
+    // ApiError
+    ApiError: typeof globalThis.ApiError;
+}
+
+declare const ginaExports: GinaExports;
+export = ginaExports;