gina 0.1.6-alpha.99 → 0.1.7

package/.claudeignore

@@ -0,0 +1,68 @@
+# .claudeignore — files excluded from Claude Code's context
+# Rule of thumb: if it can't be read usefully or has nothing to do with the
+# framework's own logic, exclude it.
+
+# ── Dependencies ─────────────────────────────────────────────────────────────
+node_modules/
+
+# Nested node_modules inside vendored deps (swig's alone has ~4300 JS files)
+framework/**/node_modules/
+
+# ── Vendored dep non-essential files ─────────────────────────────────────────
+# Keep the main lib source (we patch it for CVEs), exclude tests/examples/bench
+framework/**/core/deps/swig-1.4.2/tests/
+framework/**/core/deps/swig-1.4.2/examples/
+framework/**/core/deps/swig-1.4.2/dist/
+framework/**/core/deps/busboy-1.6.0/bench/
+framework/**/core/deps/busboy-1.6.0/test/
+
+# ── Build output & minified assets ───────────────────────────────────────────
+framework/**/core/asset/plugin/dist/
+framework/**/core/asset/plugin/build/
+**/*.min.js
+**/*.min.css
+**/*.gz
+**/*.br
+**/*.map
+
+# External jQuery copies inside the asset plugin (not framework code)
+framework/**/core/asset/plugin/src/vendor/jquery/
+framework/**/core/asset/plugin/src/vendor/gina/toolbar/js/jquery*.js
+
+# ── Lock files ────────────────────────────────────────────────────────────────
+package-lock.json
+**/package-lock.json
+
+# ── Locale compiled data ──────────────────────────────────────────────────────
+# src/ has 5 files (the make script) — keep; dist/ is compiled output — exclude
+framework/**/core/locales/dist/
+
+# ── Test workspace ────────────────────────────────────────────────────────────
+# Generated test project bootstrapped by `gina project:add` — not framework code
+framework/**/test/workspace/
+
+# ── Runtime / generated directories ──────────────────────────────────────────
+logs/
+**/logs/
+tmp/
+cache/
+services/
+
+# ── Binary & image assets ─────────────────────────────────────────────────────
+resources/img/
+**/*.png
+**/*.ico
+**/*.jpg
+**/*.jpeg
+**/*.gif
+**/*.svg
+**/*.afdesign
+
+# ── Changelog management ──────────────────────────────────────────────────────
+# Individual .yaml entries are tiny but provide zero code insight
+.changes/
+CHANGELOG.md
+
+# ── Static reference data ─────────────────────────────────────────────────────
+# doc/doc.json is a static CLI reference — useful to read manually, not as context
+doc/

package/CHANGELOG.md

@@ -0,0 +1,83 @@
+# Changelog
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
+and is generated by [Changie](https://github.com/miniscruff/changie).
+
+
+## 0.1.7 - 2026-03-20
+### Added
+* Cache: sliding-window expiration and absolute ceiling (maxAge) for HTML and JSON response caches
+* Added gina cache:stats <bundle> @<project> CLI command. Fetches and prints a grouped table of in-memory cache entries from a running bundle. Requires the bundle to be running.
+* Cached routes now emit `Cache-Control` headers synchronised with the server-side TTL. A new optional `visibility` field (`"public" | "private"`, default `"private"`) in the per-route cache config controls the directive sent to browsers and CDNs. The hit path uses the remaining TTL so downstream caches do not over-serve stale content.
+* Per-route outgoing query timeout: add "queryTimeout": <ms> to any routing.json rule and self.query() will use it as the request timeout budget when options.requestTimeout is not explicitly set. The hardcoded 10 s default still applies when neither is set.
+### Changed
+* Cache FS writes in the JSON renderer are now asynchronous (fs.promises.writeFile), avoiding event-loop blocking on cache misses.
+* routing.json queryTimeout field now accepts human-readable strings ("30s", "500ms", "2m", "1h") in addition to integer milliseconds (30000). The value is normalised to ms at parse time so req.routing.queryTimeout is always a number.
+* app.json proxy target field "timeout" renamed to "requestTimeout" — unambiguous name for the per-request outgoing timeout. Update any app.json proxy target that declares a "timeout" to use "requestTimeout" instead. self.query() call sites that passed options.timeout must also be updated to options.requestTimeout.
+* self.query() options field "timeout" renamed to "requestTimeout" — consistent with app.json::proxy.<service>.requestTimeout. The internal pipeline (both HTTP/1 and HTTP/2 handlers) and the defaultOptions fallback now use requestTimeout throughout
+* Entity methods and Couchbase N1QL methods now return a native Promise (Option B). await entity.method(args) works directly without util.promisify. .onComplete(cb) remains fully backward-compatible. Removes the _isRegisteredFromProto guard that was silently dropping queries when a callback-path call preceded a Promise-path call on the same entity.
+### Fixed
+* Sub-second TTL and maxAge values (e.g. ttl: 0.5) now work correctly in the cache. Previously, fractional seconds were truncated to zero, causing immediate eviction.
+* Completed sub-second maxAge fix (#C1): both renderers were pre-truncating maxAge with ~~ before passing it to lib/cache, bypassing the Math.round fix. Removed ~~ from render-swig.js and render-json.js. Also fixed Cache-Status header calculation in server.isaac.js.
+* Cache keys now include the bundle name ("static:{bundle}:{url}" and "data:{bundle}:{url}") to prevent silent cache collisions when two bundles serve the same URL path on the same server instance.
+* Cache entries are now capped via LRU eviction. Cache(options) accepts a `maxEntries` option (default 0 = unlimited); when reached, the least-recently-accessed entry is evicted before each insert. The shared server cache defaults to 1000 entries, configurable via `server.cache.maxEntries` in env.json. The routing cache is capped at 5000 entries (FIFO).
+* Fixed handler files returning 404 when a catch-all root statics mapping (empty key) was defined: staticResources is now sorted by descending path length so specific prefixes like /handlers/ are matched before / in the prefix-regex loop
+* CORS preflight (OPTIONS) requests are now handled before routing: the server responds with HTTP 204 and the correct Access-Control-Allow-Origin header immediately, instead of forwarding to the controller action which returned an error without CORS headers. CORS response headers are now also included on all HTTP/2 JSON responses.
+* self.query() queryTimeout fallback now fires correctly: moved the req.routing.queryTimeout check to before the merge with defaultOptions, which was silently overwriting timeout with the "10s" framework default before the check could run
+* controller.render-swig.js: isRenderingCustomError now detected from both userData and localOptions (set by renderCustomError() in controller.js). Adds null-guard on userData. localOptions is now resolved before the flag check.
+### Security
+* Removed dead framework version v0.1.1-alpha.1 from the repository. Its package.json declared sanitize-html ^2.5.0 (CVE-2021-26539, CVE-2021-26540 — XSS, high severity) and busboy ^0.2.14 (dicer ReDoS). Neither version nor its dependencies were in use.
+
+## 0.1.6 - 2026-03-08
+### Added
+* Added JSDoc across core/controller/, core/model/, and helpers/: constructor @class/@constructor/@extends, @inner on private helpers, complete @param/@returns on all public methods, @global on the _ path helper, @module on controller/index.js
+* Added JSDoc to lib/ runtime libraries: @module on all 13 files; @class/@constructor on Cache, Collection, ConfigUtil, Domain, Inherits, Merge, ModelUtil, Proc, SessionStore, Shell, Url, Validator; complete @param/@returns on all public methods; fixed @contructor typos and empty @returns stubs
+* Added JSDoc to all lib/cmd/ command handlers (63 files) covering bundle, env, framework, minion, port, project, protocol, scope, view groups plus CmdHelper and the cmd dispatcher
+* Added JSDoc to core/config.js, core/gna.js, core/server.js, core/server.isaac.js, and core/server.express.js
+* post_publish now auto-increments the alpha version, renames the framework directory, updates ~/.gina config, and commits after each npm publish
+* Added unit tests for V8 arm64 regression (const vs var object rest), routing cleanup, _isDebugLog gate, _debugLog format, and ANSI color codes in startup debug traces
+* Added gina-container foreground bundle launcher for Docker/K8s containers (bin/gina-container)
+### Changed
+* Replaced synchronous fs I/O in render-swig.js (readFileSync, openSync/writeSync/closeSync), server.isaac.js (execSync for brotli/gzip), and config.js (readdirSync) with async equivalents (fs.promises, child_process.exec)
+* Extracted try-catch config resolution block from Router::route() into module-level resolveRouteConfig() for V8 JIT optimization (#P25)
+* Replaced string += in setOptions() routing param loop with Array.push()+join() for V8 optimization (#P26)
+### Fixed
+* Fixed HTTP/2 client requests crashing on retry when a request body was present, and corrected misleading undefined method/path in HTTP/2 stream error logs.
+* Fixed HTTP/2 session cache growing without bound; sessions are now capped at 50 with FIFO eviction and properly removed on error, close, and goaway events
+* Fixed query#complete listener accumulation: removeAllListeners() is now called before each once() registration in both HTTP/1 and HTTP/2 onComplete paths
+* Fixed shared module-level EventEmitter in path helper: mkdir, cp, mv and rm now each create a per-call emitter, eliminating orphaned listener accumulation and cross-call event interference
+* Fixed _maxListeners growing unbounded in entity.js: capped at 100 via Math.min to ensure Node's memory leak warning still fires if trigger accumulation goes beyond the realistic method count ceiling
+* Fixed undrained http.IncomingMessage on 4xx in downloadFromURL: res.destroy() is now called before rejecting the Promise, releasing the TCP connection immediately instead of waiting for remote timeout
+* Fixed HTTP/2 response chunk string concatenation: chunks are now collected as Buffers and assembled with Buffer.concat() in the end handler, halving peak memory usage for large responses
+* Fixed HTTP/1 retry timer accumulation: capped maxRetry at 10 via Math.min to bound outstanding setTimeout closures under sustained connection failure regardless of user config
+* Fixed req/res held in controller closure: all response-terminal exit paths in controller.js, controller.render-json.js, and controller.render-swig.js now explicitly null local.req/res/next immediately after the response is sent
+* Fixed SuperController.instance._options written on every request: removed write in getInstance() and setOptions() — _options was never read (all reads go through per-request local.options/self._options), making the write a silent corruption trap for future code
+* Fixed a silent ENOENT 500 on requests when the swig layout cache directory could not be created (e.g. permission denied). The renderer now clears the cache target, logs a warning on every affected request, and falls back to the original configured layout path so the page renders normally. The swig compiled-template cache and response cache are also suppressed while the failure persists, ensuring the warning remains visible until the underlying issue is resolved.
+* prepare_version no longer attempts a stale recovery or a no-op rename when the working version is already in sync with the published one
+* Fixed invalid JSDoc tags (@package, bare @returns) in lib/inherits and lib/logger that caused jsdoc-to-markdown parse errors
+* Fixed ReferenceError: isLocalScope is not defined in SuperController.setOptions (controller.js:413) — bare call replaced with self.isLocalScope()
+* Fixed post_install.js MIDDLEWARE update: .toString missing () caused comparison to always be true; added missing done() call in the already-in-sync branch to prevent hang
+* Fixed HTTP/2 client stream premature close silently hanging requests: req.on('close') now emits an error when the stream closes before 'end' fires (GOAWAY race, network reset, or session timeout)
+* Added stream-level timeout to HTTP/2 client requests (mirrors HTTP/1 path): streams that receive no events now time out instead of hanging indefinitely
+* Added TCP keepalive and setNoDelay on HTTP/2 session socket to prevent OrbStack (ARM64) from silently dropping idle inter-container connections
+* HTTP/2 stream timeout now auto-retries with a fresh session instead of surfacing a 500 error — transparent recovery when OrbStack silently drops idle inter-container connections
+* Fixed null lib.generator crash in post_publish.js by initializing lib inside begin() to avoid circular dependency at module load time
+* Fixed bundle crash on startup when verifyCertificate DNS lookup fails inside containers (unhandled rejection from async setTimeout callback now logs at emerg level instead of aborting the process; added 5 s timeout to ssl-checker to prevent indefinite hangs)
+* Fixed credentials.ca path not expanding ~/ before fs.readFileSync in verifyCertificate (server.js) and http2Options (server.isaac.js); credentials paths use ~/ which fs.readFileSync cannot resolve — now uses _() for tilde expansion
+* Fixed logger silently swallowing all log output when LOG_LEVEL is set to a level name with no hierarchy entry (e.g. 'notice', 'alert', 'crit'): init now falls back to 'info' with a warning, matching the existing setLevel() guard
+* Fixed bundle crash when HTTP/2 client abruptly disconnects (ECONNRESET): added session error handler in server.isaac.js and restored ECONNRESET guard in proc.js uncaughtException handler
+* Fixed bundle being SIGKILL'd by start.js stdout watchdog when a runtime uncaughtException triggered an emerg log — the emerg-detection guard in child.stdout.on('data') is now skipped once the bundle is running, letting proc.js handle the lifecycle cleanly and allowing the actual error to reach the logs
+* Replaced per-request regex /^(\.|\/|\\)/.test(file) with charAt(0) checks in render-swig.js and render-v1.js
+* Added bundle startup integration test validating the async render pipeline (P28-P31) works end-to-end; test skips gracefully when gina socket is not running
+* Reverted async readdirSync conversion in config.js (loadWithTemplate, loadBundleConfig) — async I/O in these functions breaks the synchronous Config initialisation contract, causing bundle startup crashes with TypeError: Cannot read properties of undefined (reading 'bundlesConfiguration')
+* Fixed {{ page.environment.* }} placeholders not substituted in ginaLoader (gina.onload.min.js) — ginaLoader is injected after Swig compilation so whisper() must resolve them; dic was missing page.environment.key flattened entries in render-swig.js and render-v1.js
+* Fixed %s placeholders not substituted in session-store v3/v4 debug log calls (gina logger does not support printf-style formatting)
+* Eliminated [DOMAIN] PSL Loaded ×2 noise per request in dev mode: removed unused Domain import and instantiation from controller.js (dead code), and removed redundant direct pre-load of controller.js from refreshCoreDependencies() in router.js
+* Added graceful HTTP shutdown on SIGTERM: server.close() drains in-flight requests before exit, with configurable timeout (GINA_SHUTDOWN_TIMEOUT env var, default 10s) and closeIdleConnections() for keep-alive connections (Node 18.2+ http.Server)
+* Fixed per-request "Logger instance already exists: reusing it ;)" debug noise in dev mode. Root cause: refreshCore() (server.isaac.js) deleted and re-required lib/index.js on every HTTP request, which re-ran Lib() and called _require('./logger'), evicting and re-loading the logger singleton on every request. Logger is persisted via getContext('loggerInstance') and does not benefit from hot-reload. Changed lib/index.js to use plain require('./logger') instead of _require('./logger').
+### Security
+* Fixed directory traversal vulnerability (CVE-2023-25345) in the swig template engine: a malicious template using `{% extends %}` or a path starting with `./`, `/`, or `\` could read arbitrary files outside the template root.
+* Removed dead framework version v0.1.1-alpha.1 from the repository. Its package.json declared sanitize-html ^2.5.0 (CVE-2021-26539, CVE-2021-26540 — XSS, high severity) and busboy ^0.2.14 (dicer ReDoS). Neither version nor its dependencies were in use.
+* Removed internal development files from the npm package. The published tarball no longer includes .env, CLAUDE.md, .claude/ (internal notes), .changes/ (changie entries), .changie.yaml, services/ (WIP bundles), vendor benchmark and CI files, library example and test files, locale build sources, and stray backup files. Previously .npmignore did not cover these paths.

package/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2009-2025 Rhinostone <contact@gina.io>
+Copyright (c) 2009-2026 Rhinostone <contact@gina.io>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal