tina4-nodejs 3.13.43 → 3.13.44

package/CLAUDE.md

@@ -1,4 +1,4 @@
-# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.43)
+# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.44)
 
 > This file helps AI assistants (Claude, Copilot, Cursor, etc.) understand and work on this codebase effectively.
 
@@ -1239,6 +1239,7 @@ When adding new features, add a corresponding `test/<feature>.test.ts` file.
 - **Don't break the test files** — run `npm test` before committing
 - **Don't add unnecessary dependencies** — minimal footprint is a core principle
 - **Parity across all frameworks** — Every new feature, fix, or optimization must be implemented with equivalent logic AND tests in all 4 Tina4 frameworks (Python, PHP, Ruby, Node.js). Never ship to one without shipping to all.
+- **NO mock testing. Mocks are not acceptable in any circumstances.** A test double (mock, stub, fake, spy, monkeypatch, script-introspection assertion, or any in-test object standing in for a real collaborator) may never substitute for a real dependency, under any justification. There is no "supplement" exception and no "hard to reproduce" exception. Any test that touches a dependency (a DB engine, MongoDB, Redis/Valkey/Memcached, RabbitMQ/Kafka, an HTTP/SMTP service, the filesystem, a socket) must exercise the REAL service; if a failure mode is hard to trigger, reproduce it for real, never simulate it. "Verified"/"green" requires a real run; a passing mock test is not verification. CI provisions the services; use them and add any that is missing. The only tests that need no live dependency are pure functions with no dependency and no double; that is not a mock test. (The MongoDB queue re-delivered every completed job for two releases because its queue tests were mock/script-introspection-based and never ran against a real Mongo.)
 - **Don't use `url.parse()`** — use the WHATWG `URL` constructor instead (deprecated in Node 20+)
 
 ## Tina4 Maintainer Skill

package/package.json

@@ -3,7 +3,7 @@
 
 
 
-  "version": "3.13.43",
+  "version": "3.13.44",
 
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript \u2014 54 built-in features, zero dependencies",

package/packages/core/src/graphql.ts

@@ -510,8 +510,13 @@ export class GraphQL {
   /**
    * Decorator-style resolver registration.
    *
+   * Resolvers may be synchronous OR async (return a Promise) — `execute()`
+   * awaits every resolver, so an `async` resolver's value is resolved before
+   * the field is serialized. Return a value directly, or `await` your data
+   * (e.g. an async DB driver) and the executor will await it for you.
+   *
    *     GraphQL.resolve("Query", "products", async (root, args) =>
-   *       db.fetchAll("SELECT * FROM products"));
+   *       (await db.fetch("SELECT * FROM products")).records);
    *
    *     GraphQL.resolve("Mutation", "createProduct", async (root, args) => {
    *       const p = new Product(args.input);
@@ -520,7 +525,7 @@ export class GraphQL {
    *     });
    *
    *     GraphQL.resolve("Product", "reviews", async (product, args) =>
-   *       db.fetchAll("SELECT * FROM reviews WHERE product_id = ?", [product.id]));
+   *       (await db.fetch("SELECT * FROM reviews WHERE product_id = ?", [product.id])).records);
    *
    * Resolvers registered before any GraphQL instance exists accumulate
    * in the class-level registry. `new GraphQL()` drains them into its
@@ -647,7 +652,7 @@ export class GraphQL {
   /**
    * Execute a GraphQL query string.
    */
-  execute(query: string, variables?: Record<string, unknown>, context?: Record<string, unknown>): GraphQLResult {
+  async execute(query: string, variables?: Record<string, unknown>, context?: Record<string, unknown>): Promise<GraphQLResult> {
     const vars = variables ?? {};
     const ctx = context ?? {};
     const errors: Array<{ message: string; path?: string[] }> = [];
@@ -690,7 +695,7 @@ export class GraphQL {
 
     const data: Record<string, unknown> = {};
     // Top-level selections start at depth 1.
-    const errs = this.resolveSelectionsInto(op.selections, resolvers, null, vars, ctx, fragments, data, 1);
+    const errs = await this.resolveSelectionsInto(op.selections, resolvers, null, vars, ctx, fragments, data, 1);
     errors.push(...errs);
 
     const result: GraphQLResult = { data };
@@ -710,7 +715,7 @@ export class GraphQL {
    * instead of recursing until the interpreter stack overflows. Top-level
    * starts at depth 1; `maxDepth <= 0` disables the guard.
    */
-  private resolveSelectionsInto(
+  private async resolveSelectionsInto(
     selections: ParsedSelection[],
     resolvers: Map<string, QueryConfig>,
     parent: unknown,
@@ -719,7 +724,7 @@ export class GraphQL {
     fragments: Map<string, ParsedFragment>,
     target: Record<string, unknown>,
     depth: number,
-  ): Array<{ message: string; path?: string[] }> {
+  ): Promise<Array<{ message: string; path?: string[] }>> {
     const errors: Array<{ message: string; path?: string[] }> = [];
 
     if (this.maxDepth > 0 && depth > this.maxDepth) {
@@ -736,7 +741,7 @@ export class GraphQL {
           errors.push({ message: `Fragment not found: ${sel.name}` });
           continue;
         }
-        const errs = this.resolveSelectionsInto(
+        const errs = await this.resolveSelectionsInto(
           frag.selections, resolvers, parent, variables, context, fragments, target, depth + 1,
         );
         errors.push(...errs);
@@ -744,14 +749,14 @@ export class GraphQL {
       }
 
       if (sel.kind === "inline_fragment") {
-        const errs = this.resolveSelectionsInto(
+        const errs = await this.resolveSelectionsInto(
           sel.selections, resolvers, parent, variables, context, fragments, target, depth + 1,
         );
         errors.push(...errs);
         continue;
       }
 
-      const [value, errs] = this.resolveField(sel, resolvers, parent, variables, context, fragments, depth);
+      const [value, errs] = await this.resolveField(sel, resolvers, parent, variables, context, fragments, depth);
       errors.push(...errs);
       const key = sel.alias ?? sel.name;
       target[key] = value;
@@ -1010,7 +1015,7 @@ export class GraphQL {
     return `(${parts.join(", ")})`;
   }
 
-  private resolveField(
+  private async resolveField(
     sel: ParsedField,
     resolvers: Map<string, QueryConfig>,
     parent: unknown,
@@ -1018,7 +1023,7 @@ export class GraphQL {
     context: Record<string, unknown> = {},
     fragments: Map<string, ParsedFragment> = new Map(),
     depth: number = 1,
-  ): [unknown, Array<{ message: string; path?: string[] }>] {
+  ): Promise<[unknown, Array<{ message: string; path?: string[] }>]> {
     const errors: Array<{ message: string; path?: string[] }> = [];
     const name = sel.name;
     const args = this.resolveArgs(sel.args, variables);
@@ -1046,7 +1051,11 @@ export class GraphQL {
       // Inject sub-selections into context for DataLoader/eager-loading
       const ctx = { ...context, __selections: sel.selections ?? [] };
       try {
-        value = config.resolver(null, args, ctx);
+        // Resolvers may be sync or async. Awaiting a plain value is a no-op;
+        // awaiting a Promise (async resolver) resolves it before serialization.
+        // A rejected Promise throws here, into the same catch below, so async
+        // resolver errors are masked/detailed exactly like sync ones.
+        value = await config.resolver(null, args, ctx);
       } catch (e: unknown) {
         // Log the real cause; only surface the detail to the client in debug
         // mode — a resolver exception can carry internal state (DB errors,
@@ -1067,7 +1076,7 @@ export class GraphQL {
       const result: Record<string, unknown>[] = [];
       for (const item of value) {
         const obj: Record<string, unknown> = {};
-        const errs = this.resolveSelectionsInto(
+        const errs = await this.resolveSelectionsInto(
           sel.selections, new Map(), item, variables, context, fragments, obj, depth + 1,
         );
         errors.push(...errs);
@@ -1078,7 +1087,7 @@ export class GraphQL {
 
     if (value !== null && value !== undefined) {
       const obj: Record<string, unknown> = {};
-      const errs = this.resolveSelectionsInto(
+      const errs = await this.resolveSelectionsInto(
         sel.selections, new Map(), value, variables, context, fragments, obj, depth + 1,
       );
       errors.push(...errs);

package/packages/core/src/mcp.ts

@@ -1231,7 +1231,17 @@ export function registerDevTools(server: McpServer): void {
       try {
         const db = (globalThis as any).__tina4_db;
         if (!db) return { error: "No database connection" };
-        return { info: "Migration status not yet implemented for Node.js" };
+        // Use the real migration API (parity with the Python master, whose MCP
+        // migration_status calls MigrationRunner(db).status()). Previously a stub.
+        // Load orm via dynamic ESM import (the same mechanism server.ts uses for
+        // autoMigrateOnStartup) — reqSibling()'s createRequire fails here because
+        // @tina4/orm imports @tina4/core (no CJS "exports" main).
+        const orm = await import("../../orm/src/index.js");
+        if (typeof orm.status !== "function") {
+          return { error: "Migration API not available (install @tina4/orm)" };
+        }
+        const st = await orm.status(db, { migrationsDir: path.join(projectRoot, "migrations") });
+        return { completed: st.completed, pending: st.pending };
       } catch (e) {
         return { error: (e as Error).message };
       }
@@ -1264,7 +1274,16 @@ export function registerDevTools(server: McpServer): void {
       try {
         const db = (globalThis as any).__tina4_db;
         if (!db) return { error: "No database connection" };
-        return { info: "Migration run not yet implemented for Node.js" };
+        // Run pending migrations for real (parity with the Python master's MCP
+        // migration_run -> Migration(db).migrate()). Previously a stub. Load orm
+        // via dynamic ESM import (server.ts's mechanism); reqSibling's createRequire
+        // fails because @tina4/orm imports @tina4/core.
+        const orm = await import("../../orm/src/index.js");
+        if (typeof orm.migrate !== "function") {
+          return { error: "Migration API not available (install @tina4/orm)" };
+        }
+        const result = await orm.migrate(db, { migrationsDir: path.join(projectRoot, "migrations") });
+        return { applied: result.applied, skipped: result.skipped, failed: result.failed };
       } catch (e) {
         return { error: (e as Error).message };
       }