tina4-nodejs 3.13.99 → 3.13.101

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/core/src/aiClient.d.ts

@@ -0,0 +1,66 @@
+export declare class AiError extends Error {
+}
+export declare class AiConfigError extends AiError {
+}
+export declare class AiTimeoutError extends AiError {
+}
+export declare class AiParseError extends AiError {
+}
+export declare class AiHTTPError extends AiError {
+    readonly status: number | null;
+    constructor(message: string, status?: number | null);
+}
+export interface ChatResponse {
+    text: string;
+    model: string;
+    usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    finishReason: string | null;
+    raw: Record<string, unknown>;
+}
+export interface AiMessage {
+    role: "system" | "user" | "assistant";
+    content: string;
+}
+export interface AiChatOptions {
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    stream?: boolean;
+    timeout?: number;
+    provider?: "local" | "openai" | "anthropic";
+}
+export interface AiEmbedOptions {
+    model?: string;
+    timeout?: number;
+    provider?: "local" | "openai" | "anthropic";
+}
+export declare class Ai {
+    static chat(messages: AiMessage[], options: AiChatOptions & {
+        stream: true;
+    }): AsyncGenerator<string>;
+    static chat(messages: AiMessage[], options?: AiChatOptions & {
+        stream?: false;
+    }): Promise<ChatResponse>;
+    static complete(prompt: string, options?: Omit<AiChatOptions, "stream">): Promise<string>;
+    static embed(textOrTexts: string | string[], options?: AiEmbedOptions): Promise<number[] | number[][]>;
+    private static validateMessages;
+    private static number;
+    private static config;
+    private static endpoint;
+    private static headers;
+    private static chatBody;
+    private static open;
+    private static readBody;
+    private static retryDelay;
+    private static requestJson;
+    private static normalizeChat;
+    private static chatResponse;
+    private static streamDelta;
+    private static streamData;
+    private static streamError;
+    private static streamRequest;
+}

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

@@ -55,6 +55,8 @@ export { HtmlElement, htmlElement, addHtmlHelpers, Raw, SafeString } from "./htm
 export { renderErrorOverlay, isDebugMode } from "./errorOverlay.js";
 export { AI_TOOLS, isInstalled, showMenu, installSelected, installAll, generateContext } from "./ai.js";
 export type { AiTool } from "./ai.js";
+export { Ai, AiError, AiConfigError, AiHTTPError, AiTimeoutError, AiParseError } from "./aiClient.js";
+export type { ChatResponse, AiMessage, AiChatOptions, AiEmbedOptions } from "./aiClient.js";
 export type { ImapMessage, ImapFullMessage, ImapAttachment } from "./messenger.js";
 export { LiteBackend } from "./queueBackends/liteBackend.js";
 export { RabbitMQBackend, parseAmqpUrl } from "./queueBackends/rabbitmqBackend.js";

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

@@ -1,41 +1,6 @@
-export declare function quickMetrics(root?: string): Record<string, any>;
-/**
- * The native metrics engine could not produce a payload.
- *
- * Thrown instead of falling back to a second implementation.
- */
 export declare class MetricsEngineError extends Error {
     constructor(message: string);
 }
-export declare const SEVERITY_RANK: Record<string, number>;
-/**
- * Return [directory to scan, scanMode] for any metrics producer.
- *
- * The engine is language-agnostic and cannot know which directory holds a
- * framework package, so root resolution and the "framework" label stay here,
- * shared by the census and the engine adapter so the two never disagree.
- */
-export declare function resolveScanTarget(root?: string): [string, string];
-/** Absolute path to the tina4 CLI binary, or null when it is not installed. */
 export declare function enginePath(): string | null;
-/** Full code analysis from the native engine, shaped for the dashboard. */
 export declare function fullAnalysis(root?: string): Record<string, any>;
-export interface OffendersResult {
-    offenders: Record<string, any>[];
-    summary: Record<string, any>;
-}
-/**
- * Top code-health offenders from the native engine.
- *
- * The engine ranks and severity-tags them, and its own --fail-on gate reads the
- * same list, so the CLI and the dashboard can never disagree about what counts
- * as an offender.
- */
-export declare function offenders(root?: string, top?: number): OffendersResult;
-/**
- * Per-file metrics from the native engine.
- *
- * The engine accepts a single file for --path, so one code path serves both the
- * whole-tree scan and one file.
- */
 export declare function fileDetail(filePath: string): Record<string, any>;

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;
     /**

package/packages/cli/src/commands/metrics.ts

@@ -1,160 +0,0 @@
-/**
- * CLI command: metrics — Rank top code-quality offenders.
- *
- * Exposes the existing static analyzer (cyclomatic complexity, maintainability,
- * large-file, too-many-functions, and the now-precise has_tests) on the CLI as
- * a self-monitoring tool.
- *
- *   tina4nodejs metrics                          # human report, scans src/ (or framework)
- *   tina4nodejs metrics --top 10                 # only the worst 10
- *   tina4nodejs metrics --path packages/core/src # scan a specific directory
- *   tina4nodejs metrics --json                   # machine-readable for CI (ONLY json printed)
- *   tina4nodejs metrics --fail-on warn           # exit 1 if any warn/error offender
- *   tina4nodejs metrics --fail-on error          # exit 1 only on error-severity
- *
- * Returns the intended process exit code (the caller exits). Splitting "compute
- * exit code" from "exit the process" keeps the handler unit-testable.
- */
-import { offenders, MetricsEngineError } from "../../../core/src/metrics.js";
-
-type Flags = {
-  top: number;
-  json: boolean;
-  path: string;
-  failOn: "warn" | "error" | null;
-};
-
-/** Parse `--top N`, `--json`, `--fail-on warn|error`, `--path DIR` out of argv. */
-function parseFlags(args: string[]): Flags | { error: string } {
-  const flags: Flags = { top: 20, json: false, path: "src", failOn: null };
-
-  for (let i = 0; i < args.length; i++) {
-    const a = args[i];
-    switch (a) {
-      case "--json":
-        flags.json = true;
-        break;
-      case "--top": {
-        const v = args[++i];
-        if (v === undefined || !/^\d+$/.test(v)) {
-          return { error: `--top expects a number (got '${v ?? ""}')` };
-        }
-        flags.top = parseInt(v, 10);
-        break;
-      }
-      case "--path": {
-        const v = args[++i];
-        if (v === undefined) return { error: "--path expects a directory" };
-        flags.path = v;
-        break;
-      }
-      case "--fail-on": {
-        const v = args[++i];
-        if (v !== "warn" && v !== "error") {
-          return { error: `invalid --fail-on '${v ?? ""}' (use warn or error)` };
-        }
-        flags.failOn = v;
-        break;
-      }
-      default:
-        return { error: `unknown option '${a}'` };
-    }
-  }
-
-  return flags;
-}
-
-/**
- * Run the metrics report. Returns the process exit code; does NOT call
- * process.exit (the bin wrapper does). 0 = ok / below threshold, 1 = gated
- * failure, 2 = bad arguments / analysis error.
- */
-export function runMetrics(args: string[] = []): number {
-  const parsed = parseFlags(args);
-  if ("error" in parsed) {
-    console.log(`  ${parsed.error}`);
-    return 2;
-  }
-  const { top, json, path, failOn } = parsed;
-
-  // ONE engine run. Ask for every offender and slice for display: the gate must
-  // read the FULL set, not the printed top-N, and the old second call re-ran the
-  // whole analysis (its "mtime-cached" comment stopped being true when the
-  // in-process analyzer and its cache were deleted -- ADR-0002).
-  let result;
-  try {
-    result = offenders(path, Number.MAX_SAFE_INTEGER);
-  } catch (e) {
-    if (e instanceof MetricsEngineError) {
-      console.error(`  metrics error: ${e.message}`);
-      return 2;
-    }
-    throw e;
-  }
-  const summary = result.summary;
-  const allOffenders = result.offenders;
-  const found = allOffenders.slice(0, top);
-
-  const severities = new Set(allOffenders.map((o) => o.severity));
-  let exitCode = 0;
-  if (failOn === "warn" && (severities.has("warn") || severities.has("error"))) {
-    exitCode = 1;
-  } else if (failOn === "error" && severities.has("error")) {
-    exitCode = 1;
-  }
-
-  if (json) {
-    // Print ONLY the JSON — machine-readable for CI / tooling.
-    console.log(JSON.stringify({ summary, offenders: found }, null, 2));
-    return exitCode;
-  }
-
-  // ── Human report ──────────────────────────────────────────────────
-  const useColor = Boolean(process.stdout.isTTY);
-  const c = (text: string, code: string): string =>
-    useColor ? `\x1b[${code}m${text}\x1b[0m` : text;
-  const sevColor: Record<string, string> = { error: "31", warn: "33", info: "2" }; // red / yellow / dim
-
-  console.log("");
-  console.log(`  Tina4 Metrics — ${summary.scan_mode} scan (${summary.scan_root})`);
-  console.log(
-    `  files: ${summary.files_analyzed}   ` +
-      `functions: ${summary.total_functions}   ` +
-      `avg complexity: ${summary.avg_complexity}   ` +
-      `avg maintainability: ${summary.avg_maintainability}`
-  );
-  console.log(
-    `  offenders: ${summary.total_offenders} total` +
-      (found.length ? ` (showing top ${found.length})` : "")
-  );
-  console.log("");
-
-  if (found.length === 0) {
-    console.log("  " + c("✓ no offenders — clean", "32"));
-    console.log("");
-    return exitCode;
-  }
-
-  // Column widths so the table lines up.
-  const locs = found.map((o) => `${o.file}:${o.line}`);
-  const locW = Math.max("FILE:LINE".length, ...locs.map((s) => s.length));
-  const kindW = Math.max("KIND".length, ...found.map((o) => o.kind.length));
-
-  const pad = (s: string, w: number) => s.padEnd(w);
-  const header = `  ${pad("#", 3)}  ${pad("SEVERITY", 8)}  ${pad("KIND", kindW)}  ${pad(
-    "FILE:LINE",
-    locW
-  )}  DETAIL`;
-  console.log(c(header, "1"));
-  console.log("  " + "-".repeat(header.length - 2));
-  found.forEach((o, idx) => {
-    const i = idx + 1;
-    const sevCell = c(pad(o.severity, 8), sevColor[o.severity]);
-    console.log(
-      `  ${String(i).padStart(3)}  ${sevCell}  ${pad(o.kind, kindW)}  ` +
-        `${pad(locs[idx], locW)}  ${o.detail}`
-    );
-  });
-  console.log("");
-  return exitCode;
-}

package/types/cli/src/commands/metrics.d.ts

@@ -1,6 +0,0 @@
-/**
- * Run the metrics report. Returns the process exit code; does NOT call
- * process.exit (the bin wrapper does). 0 = ok / below threshold, 1 = gated
- * failure, 2 = bad arguments / analysis error.
- */
-export declare function runMetrics(args?: string[]): number;