tina4-nodejs 3.13.99 → 3.13.100

package/packages/orm/dist/index.js

@@ -2620,7 +2620,10 @@ var init_trustedProxy = __esm({
 var engine_exports = {};
 __export(engine_exports, {
   Frond: () => Frond,
+  MEMO_CACHE_MAX: () => MEMO_CACHE_MAX,
   TEMPLATE_CACHE_MAX: () => TEMPLATE_CACHE_MAX,
+  filterChainCache: () => filterChainCache,
+  pathParseCache: () => pathParseCache,
   setFormTokenSessionId: () => setFormTokenSessionId
 });
 import { createHash as createHash2, createHmac as createHmac2, randomBytes as randomBytes2 } from "node:crypto";
@@ -2724,6 +2727,12 @@ function capCache(cache, maxEntries) {
     if (--drop <= 0) break;
   }
 }
+function sweepExpiredCache(cache) {
+  const now = Date.now();
+  for (const [key, [, expiresAt]] of cache) {
+    if (expiresAt <= now) cache.delete(key);
+  }
+}
 function tokenize(source) {
   const rawBlocks = [];
   source = source.replace(RAW_BLOCK_RE, (_match, content) => {
@@ -2787,6 +2796,16 @@ function stripTag(raw) {
   }
   return [inner.trim(), stripBefore, stripAfter];
 }
+function extendsTarget(source) {
+  const matches = source.match(EXTENDS_RE_GLOBAL);
+  if (matches && matches.length > 1) {
+    throw new Error(
+      `Frond: template has ${matches.length} "{% extends %}" tags -- a template can extend only one parent`
+    );
+  }
+  const match = source.match(EXTENDS_RE);
+  return match ? match[1] : "";
+}
 function resolveVar(expr, context) {
   expr = expr.trim();
   if (expr.startsWith('"') && expr.endsWith('"') || expr.startsWith("'") && expr.endsWith("'")) {
@@ -2867,6 +2886,7 @@ function resolveVar(expr, context) {
         fromBracket.push(false);
       }
     }
+    capCache(pathParseCache, MEMO_CACHE_MAX);
     pathParseCache.set(expr, [parts, fromBracket]);
   }
   let value = context;
@@ -3454,6 +3474,7 @@ function parseFilterChain(expr) {
     }
   }
   const result = [variable, filters];
+  capCache(filterChainCache, MEMO_CACHE_MAX);
   filterChainCache.set(expr, result);
   return result;
 }
@@ -3633,7 +3654,7 @@ function _generateFormToken(descriptor = "") {
 function _generateFormTokenValue(descriptor = "") {
   return new SafeString(_buildFormTokenJwt(descriptor));
 }
-var SafeString, KNOWN_TAGS, TERMINATOR_TAGS, GATEABLE_TAGS, BLOCK_TAG_ENDS, JSON_UNSAFE_RE, JSON_UNSAFE_MAP, NUMERIC_RE, METHOD_CALL_RE, FN_CALL_RE, IS_NOT_RE, IS_RE, NOT_IN_RE, IN_RE, DIVISIBLE_BY_RE, FILTER_WITH_ARGS_RE, FILTER_COMPARISON_RE, TITLE_WORD_RE, STRIP_TAGS_RE, FORMAT_RE, LEADING_WS_RE, TRAILING_WS_RE, THOUSANDS_RE, LIVE_RE, LIVE_WS_RE, LIVE_SRC_RE, filterChainCache, pathParseCache, TEMPLATE_CACHE_MAX, TOKEN_RE, RAW_BLOCK_RE, VarRef, BUILTIN_FILTERS, _formTokenSessionId, Frond;
+var SafeString, KNOWN_TAGS, TERMINATOR_TAGS, GATEABLE_TAGS, BLOCK_TAG_ENDS, JSON_UNSAFE_RE, JSON_UNSAFE_MAP, NUMERIC_RE, METHOD_CALL_RE, FN_CALL_RE, IS_NOT_RE, IS_RE, NOT_IN_RE, IN_RE, DIVISIBLE_BY_RE, FILTER_WITH_ARGS_RE, FILTER_COMPARISON_RE, TITLE_WORD_RE, STRIP_TAGS_RE, FORMAT_RE, LEADING_WS_RE, TRAILING_WS_RE, THOUSANDS_RE, LIVE_RE, LIVE_WS_RE, LIVE_SRC_RE, EXTENDS_RE, EXTENDS_RE_GLOBAL, filterChainCache, pathParseCache, TEMPLATE_CACHE_MAX, MEMO_CACHE_MAX, TOKEN_RE, RAW_BLOCK_RE, VarRef, BUILTIN_FILTERS, _formTokenSessionId, Frond;
 var init_engine = __esm({
   "../frond/src/engine.ts"() {
     "use strict";
@@ -3727,9 +3748,12 @@ var init_engine = __esm({
     LIVE_RE = /^live\s+["']([^"']+)["']([\s\S]*)$/;
     LIVE_WS_RE = /ws\s+["']([^"']+)["']/;
     LIVE_SRC_RE = /src\s+["']([^"']+)["']/;
+    EXTENDS_RE = /\{%[-\s]*extends\s+["'](.+?)["']\s*[-]?%\}/;
+    EXTENDS_RE_GLOBAL = /\{%[-\s]*extends\s+["'](.+?)["']\s*[-]?%\}/g;
     filterChainCache = /* @__PURE__ */ new Map();
     pathParseCache = /* @__PURE__ */ new Map();
     TEMPLATE_CACHE_MAX = 256;
+    MEMO_CACHE_MAX = 1024;
     TOKEN_RE = /(\{%-?\s*[\s\S]*?\s*-?%\})|(\{\{-?\s*[\s\S]*?\s*-?\}\})|(\{#[\s\S]*?#\})/g;
     RAW_BLOCK_RE = /\{%-?\s*raw\s*-?%\}([\s\S]*?)\{%-?\s*endraw\s*-?%\}/g;
     VarRef = class {
@@ -4082,29 +4106,22 @@ var init_engine = __esm({
         return this;
       }
       /**
-       * Register a custom filter. The filter is persisted at class level
-       * so new instances created by hot-reload inherit it automatically;
-       * the live instance's local filter map also receives the addition
-       * immediately. Mirrors Python's _ClassOrInstanceMethod dual-call.
+       * Register a custom filter on this instance only. Use the static method
+       * for process-global registration. tina4: ADR-0052.
        */
       addFilter(name, fn) {
-        _Frond.classFilters.set(name, fn);
         this.filters[name] = fn;
       }
       /**
-       * Register a global variable available in all templates. Persisted
-       * at class level — see ``addFilter`` for the dual-call semantics.
+       * Register a global variable on this instance only.
        */
       addGlobal(name, value) {
-        _Frond.classGlobals.set(name, value);
         this.globals[name] = value;
       }
       /**
-       * Register a custom test. Persisted at class level — see
-       * ``addFilter`` for the dual-call semantics.
+       * Register a custom test on this instance only.
        */
       addTest(name, fn) {
-        _Frond.classTests.set(name, fn);
         this.tests[name] = fn;
       }
       /**
@@ -4219,9 +4236,8 @@ var init_engine = __esm({
         if (Object.keys(this.tests).length > 0) {
           context.__frond_tests__ = this.tests;
         }
-        const extendsMatch = source.match(/\{%[-\s]*extends\s+["'](.+?)["']\s*[-]?%\}/);
-        if (extendsMatch) {
-          const parentName = extendsMatch[1];
+        const parentName = extendsTarget(source);
+        if (parentName) {
           const parentSource = this.load(parentName);
           const childBlocks = this.extractBlocks(source);
           return this.renderWithBlocks(parentSource, context, childBlocks);
@@ -4232,9 +4248,8 @@ var init_engine = __esm({
         if (Object.keys(this.tests).length > 0) {
           context.__frond_tests__ = this.tests;
         }
-        const extendsMatch = source.match(/\{%[-\s]*extends\s+["'](.+?)["']\s*[-]?%\}/);
-        if (extendsMatch) {
-          const parentName = extendsMatch[1];
+        const parentName = extendsTarget(source);
+        if (parentName) {
           const parentSource = this.load(parentName);
           const childBlocks = this.extractBlocks(source);
           return this.renderWithBlocks(parentSource, context, childBlocks);
@@ -4279,10 +4294,93 @@ var init_engine = __esm({
         }
         return blocks;
       }
+      /**
+       * Depth-aware block substitution against `source` (typically the
+       * fully-resolved root template).
+       *
+       * A single regex `.replace()` pass (the flat `pattern` this replaces in
+       * renderWithBlocks) pairs an OUTER block's open tag with the FIRST
+       * `{% endblock %}` found -- which, when the outer block wraps a NESTED
+       * `{% block %}`, is the nested block's own close tag, not the outer's.
+       * That silently truncates the outer block's captured content and drops
+       * everything after the inner endblock (the root-nested-block
+       * content-loss bug). This scans with an open/close depth counter
+       * instead (mirroring extractBlocks), so an outer block always captures
+       * its FULL body, nested child blocks included.
+       *
+       * The content chosen for each block -- the child override in `blocks`
+       * if present, else the block's own default body -- is then recursively
+       * substituted against the SAME `blocks` map before being tokenized and
+       * rendered, so a block nested inside another block resolves correctly
+       * regardless of which template in the inheritance chain declared the
+       * nesting (the root, an intermediate, however many levels deep).
+       *
+       * `{{ parent() }}` / `{{ super() }}` inside a block still render that
+       * block's OWN default content at this level (lazy, on first call).
+       */
+      substituteBlocks(source, blocks, context) {
+        const blockOpen = /\{%[-\s]*block\s+(\w+)\s*[-]?%\}/g;
+        const blockClose = /\{%[-\s]*endblock\s*[-]?%\}/g;
+        const engine = this;
+        const pieces = [];
+        let pos = 0;
+        while (pos < source.length) {
+          blockOpen.lastIndex = pos;
+          const mOpen = blockOpen.exec(source);
+          if (!mOpen) {
+            pieces.push(source.slice(pos));
+            break;
+          }
+          pieces.push(source.slice(pos, mOpen.index));
+          const name = mOpen[1];
+          const contentStart = mOpen.index + mOpen[0].length;
+          let depth = 1;
+          let scan = contentStart;
+          let closeMatch = null;
+          while (depth > 0 && scan < source.length) {
+            blockOpen.lastIndex = scan;
+            blockClose.lastIndex = scan;
+            const nextOpen = blockOpen.exec(source);
+            const nextClose = blockClose.exec(source);
+            if (!nextClose) break;
+            if (nextOpen && nextOpen.index < nextClose.index) {
+              depth++;
+              scan = nextOpen.index + nextOpen[0].length;
+            } else {
+              depth--;
+              if (depth === 0) {
+                closeMatch = nextClose;
+              } else {
+                scan = nextClose.index + nextClose[0].length;
+              }
+            }
+          }
+          if (!closeMatch) {
+            pieces.push(source.slice(mOpen.index));
+            pos = source.length;
+            break;
+          }
+          const parentContent = source.slice(contentStart, closeMatch.index);
+          const blockSource = blocks[name] ?? parentContent;
+          const resolvedSource = engine.substituteBlocks(blockSource, blocks, context);
+          let renderedParent = null;
+          const getParent = () => {
+            if (renderedParent === null) {
+              renderedParent = new SafeString(
+                engine.renderTokens(tokenize(parentContent), context)
+              );
+            }
+            return renderedParent;
+          };
+          const blockCtx = { ...context, parent: getParent, super: getParent };
+          pieces.push(engine.renderTokens(tokenize(resolvedSource), blockCtx));
+          pos = closeMatch.index + closeMatch[0].length;
+        }
+        return pieces.join("");
+      }
       renderWithBlocks(parentSource, context, childBlocks) {
-        const extendsMatch = parentSource.trimStart().match(/\{%[-\s]*extends\s+["'](.+?)["']\s*[-]?%\}/);
-        if (extendsMatch) {
-          const grandparentName = extendsMatch[1];
+        const grandparentName = extendsTarget(parentSource);
+        if (grandparentName) {
           const grandparentSource = this.load(grandparentName);
           const parentBlocks = this.extractBlocks(parentSource);
           const mergedBlocks = { ...parentBlocks, ...childBlocks };
@@ -4302,22 +4400,7 @@ var init_engine = __esm({
           }
           return this.renderWithBlocks(grandparentSource, context, mergedBlocks);
         }
-        const pattern = /\{%[-\s]*block\s+(\w+)\s*[-]?%\}([\s\S]*?)\{%[-\s]*endblock\s*[-]?%\}/g;
-        const engine = this;
-        const result = parentSource.replace(pattern, (_match, name, parentContent) => {
-          const blockSource = childBlocks[name] ?? parentContent;
-          let renderedParent = null;
-          const getParent = () => {
-            if (renderedParent === null) {
-              renderedParent = new SafeString(
-                engine.renderTokens(tokenize(parentContent), context)
-              );
-            }
-            return renderedParent;
-          };
-          const blockCtx = { ...context, parent: getParent, super: getParent };
-          return this.renderTokens(tokenize(blockSource), blockCtx);
-        });
+        const result = this.substituteBlocks(parentSource, childBlocks, context);
         return this.renderTokens(tokenize(result), context);
       }
       renderTokens(tokens, context) {
@@ -5140,6 +5223,7 @@ var init_engine = __esm({
         const m = content.match(/^cache\s+["'](.+?)["']\s*(\d+)?/);
         const cacheKey = m ? m[1] : "default";
         const ttl = m && m[2] ? parseInt(m[2], 10) : 60;
+        sweepExpiredCache(this.fragmentCache);
         const cached = this.fragmentCache.get(cacheKey);
         if (cached) {
           const [htmlContent, expiresAt] = cached;
@@ -5187,6 +5271,7 @@ var init_engine = __esm({
           i++;
         }
         const rendered = this.renderTokens([...bodyTokens], context);
+        capCache(this.fragmentCache, TEMPLATE_CACHE_MAX);
         this.fragmentCache.set(cacheKey, [rendered, Date.now() + ttl * 1e3]);
         return [rendered, i];
       }
@@ -29385,14 +29470,16 @@ function downloadSkillsSync(jobs) {
     const jobs = JSON.parse(process.argv[1]);
     const fs = require("node:fs");
     const path = require("node:path");
+    const transientStatuses = new Set([429, 500, 502, 503, 504]);
     async function fetchOne(job) {
       const resp = await fetch(job.url, { signal: AbortSignal.timeout(15000) });
-      if (!resp.ok) throw new Error("HTTP " + resp.status);
+      if (!resp.ok) return { ok: false, retry: transientStatuses.has(resp.status) };
       const buf = Buffer.from(await resp.arrayBuffer());
       for (const dest of job.dests) {
         fs.mkdirSync(path.dirname(dest), { recursive: true });
         fs.writeFileSync(dest, buf);
       }
+      return { ok: true, retry: false };
     }
     (async () => {
       const ok = [];
@@ -29401,9 +29488,11 @@ function downloadSkillsSync(jobs) {
         const failed = [];
         await Promise.all(pending.map(async (job) => {
           try {
-            await fetchOne(job);
-            ok.push(job.url);
+            const result = await fetchOne(job);
+            if (result.ok) ok.push(job.url);
+            else if (result.retry) failed.push(job);
           } catch {
+            // DNS, TLS, timeout and connection failures are transient.
             failed.push(job);
           }
         }));

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

@@ -6,6 +6,35 @@ export interface AiTool {
 }
 export declare const AI_TOOLS: AiTool[];
 export declare const DEV_SKILL = "tina4-developer-nodejs";
+/**
+ * Fetch a set of skill files over the network SYNCHRONOUSLY.
+ *
+ * Node has no built-in synchronous HTTP, and the whole installer chain
+ * (installSelected → installForTool → installClaudeSkills) is synchronous and
+ * can't be made async without breaking its existing callers/tests. So we run
+ * ONE blocking child `node` process that fetches every URL in parallel with the
+ * global `fetch` (Node 18+) and writes each body to all of its destinations.
+ * The child prints a JSON array of the URLs it fetched successfully; any fetch
+ * failure is skipped, never fatal.
+ *
+ * MEASURED (2026-08-13): a real GitHub raw-content fetch occasionally drops a
+ * request under load (transient DNS/TLS hiccup, not a missing file — every
+ * URL here resolves fine on its own) while its siblings in the same batch
+ * succeed. One retry pass over only transport failures and transient HTTP
+ * statuses, still inside the same child process, fixes that for real installer
+ * users too. Permanent 4xx responses are final answers and are not retried.
+ *
+ * Exported (like `writeOrMerge`/`markersFor`/`skillBlock` above) so
+ * aiFetchRetry.test.ts can drive it directly against a real local server —
+ * a pure visibility change, no behaviour change.
+ *
+ * @param jobs  one entry per unique URL, with every file path it should land in
+ * @returns the set of URLs that were fetched and written to disk
+ */
+export declare function downloadSkillsSync(jobs: {
+    url: string;
+    dests: string[];
+}[]): Set<string>;
 /**
  * Install the Tina4 SKILL.md skills into the project AND the global
  * ~/.claude/skills, fetched from the release ref matching this framework

package/types/frond/src/engine.d.ts

@@ -14,6 +14,15 @@ export interface LiveResponse {
 }
 /** WebSocket broadcaster hook wired by @tina4/core so pushLive can broadcast. */
 export type LiveBroadcaster = (wsPath: string | null, name: string, envelope: string) => void;
+/**
+ * Cache for parsed filter chains: expr string -> [variable, filters].
+ * Exported (like TEMPLATE_CACHE_MAX) so the ADR-0004 bound has something for
+ * a test to inspect directly — module-level state has no instance to read
+ * off, unlike `compiled`/`compiledStrings`/`fragmentCache`.
+ */
+export declare const filterChainCache: Map<string, [string, [string, unknown[]][]]>;
+/** Cache for parsed dotted/bracket paths: expr string -> [parts, fromBracket]. Exported for the same reason as filterChainCache. */
+export declare const pathParseCache: Map<string, [string[], boolean[]]>;
 /**
  * Hard cap on the template caches — `compiled` and `compiledStrings`
  * (ADR-0004, parity with PHP/Python/Ruby TEMPLATE_CACHE_MAX).
@@ -26,6 +35,18 @@ export type LiveBroadcaster = (wsPath: string | null, name: string, envelope: st
  * dynamically adds an entry per distinct string.
  */
 export declare const TEMPLATE_CACHE_MAX = 256;
+/**
+ * Hard cap on every per-expression memo cache — `filterChainCache` and
+ * `pathParseCache` (ADR-0004, parity with PHP's MEMO_CACHE_MAX and the
+ * Python master's `@lru_cache(maxsize=1024)` on the equivalent module-level
+ * parsers). Deliberately higher than TEMPLATE_CACHE_MAX: one entry here is a
+ * small parsed-path array, orders of magnitude smaller than a token list.
+ *
+ * Also reused for `fragmentCache` (the `{% cache %}` tag's runtime store):
+ * TEMPLATE_CACHE_MAX, not this one — a rendered fragment is a whole HTML
+ * string, the same order of magnitude as a compiled template.
+ */
+export declare const MEMO_CACHE_MAX = 1024;
 /**
  * Set the session ID used by formToken() / form_token() for CSRF session binding.
  */
@@ -95,20 +116,16 @@ export declare class Frond {
     sandbox(filters?: string[], tags?: string[], vars?: string[]): Frond;
     unsandbox(): Frond;
     /**
-     * Register a custom filter. The filter is persisted at class level
-     * so new instances created by hot-reload inherit it automatically;
-     * the live instance's local filter map also receives the addition
-     * immediately. Mirrors Python's _ClassOrInstanceMethod dual-call.
+     * Register a custom filter on this instance only. Use the static method
+     * for process-global registration. tina4: ADR-0052.
      */
     addFilter(name: string, fn: FilterFn): void;
     /**
-     * Register a global variable available in all templates. Persisted
-     * at class level — see ``addFilter`` for the dual-call semantics.
+     * Register a global variable on this instance only.
      */
     addGlobal(name: string, value: unknown): void;
     /**
-     * Register a custom test. Persisted at class level — see
-     * ``addFilter`` for the dual-call semantics.
+     * Register a custom test on this instance only.
      */
     addTest(name: string, fn: TestFn): void;
     /**
@@ -143,6 +160,31 @@ export declare class Frond {
     private executeWithSource;
     private execute;
     private extractBlocks;
+    /**
+     * Depth-aware block substitution against `source` (typically the
+     * fully-resolved root template).
+     *
+     * A single regex `.replace()` pass (the flat `pattern` this replaces in
+     * renderWithBlocks) pairs an OUTER block's open tag with the FIRST
+     * `{% endblock %}` found -- which, when the outer block wraps a NESTED
+     * `{% block %}`, is the nested block's own close tag, not the outer's.
+     * That silently truncates the outer block's captured content and drops
+     * everything after the inner endblock (the root-nested-block
+     * content-loss bug). This scans with an open/close depth counter
+     * instead (mirroring extractBlocks), so an outer block always captures
+     * its FULL body, nested child blocks included.
+     *
+     * The content chosen for each block -- the child override in `blocks`
+     * if present, else the block's own default body -- is then recursively
+     * substituted against the SAME `blocks` map before being tokenized and
+     * rendered, so a block nested inside another block resolves correctly
+     * regardless of which template in the inheritance chain declared the
+     * nesting (the root, an intermediate, however many levels deep).
+     *
+     * `{{ parent() }}` / `{{ super() }}` inside a block still render that
+     * block's OWN default content at this level (lazy, on first call).
+     */
+    private substituteBlocks;
     private renderWithBlocks;
     private renderTokens;
     /**