release: v2.5.7 — resolve inline-reference spans in field values

Fixed:
- tana_query / tana_tagged returned "" for reference-type field values
  (David D.V.'s bug report against v2.5.5: "Context": "" where Context
  pointed to Pr MB2). Tana stores references as empty spans:
    <span data-inlineref-node="NODE_ID"></span>
  FieldResolver ran stripHtml() on those and got empty strings back.

  The resolver now parses inline-ref spans, batch-looks up the referenced
  node names (one SQL per unique id set), and substitutes the display
  text before stripping residual HTML. Also handles data-inlineref-date
  spans (extracts the dateTimeString).

  No reindex required — fix applies at query time. Graceful fallback to
  empty string when the referenced node is missing.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: jcfischer

CHANGELOG.md

@@ -5,6 +5,11 @@ All notable changes to Supertag CLI are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.5.7] - 2026-04-17
+
+### Fixed
+- **Reference-type field values returned empty string** — `tana_query`, `tana_tagged`, and any code path through `FieldResolver` returned `""` for fields whose value is a reference to another node (e.g., `"Context": ""` where Context pointed to `Pr MB2`). Root cause: Tana stores inline references as empty `<span data-inlineref-node="NODE_ID"></span>` tags; the resolver ran `stripHtml()` which removed the span, leaving the empty content behind. The resolver now parses those spans, looks up the referenced node's name (batched, single SQL query per unique set), and substitutes the resolved display text before stripping residual HTML. Also resolves `data-inlineref-date` spans to their `dateTimeString` value.
+
 ## [2.5.6] - 2026-04-16
 
 ### Fixed

export/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pai/supertag-export",
-  "version": "2.5.6",
+  "version": "2.5.7",
   "description": "Browser automation for Tana workspace exports using Playwright",
   "type": "module",
   "bin": {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "supertag-cli",
-  "version": "2.5.6",
+  "version": "2.5.7",
   "description": "CLI for Tana integration - query, create, sync, and manage Tana workspaces with semantic search",
   "type": "module",
   "bin": {

src/services/field-resolver.ts

@@ -7,7 +7,7 @@
  */
 
 import { Database } from "bun:sqlite";
-import { stripHtml } from "../utils/html";
+import { resolveInlineRefsBatch } from "../utils/resolve-inline-refs";
 
 /**
  * Field value map: field_name -> value (comma-joined if multiple)
@@ -182,7 +182,16 @@ export class FieldResolver {
         value_order: number;
       }[];
 
-      for (const row of rows) {
+      // v2.5.7 fix: resolve <span data-inlineref-node="..."></span> and
+      // data-inlineref-date spans to their display text before stripping
+      // HTML. Tana stores references/dates as empty spans, so plain stripHtml
+      // collapsed pure-reference values to empty strings (symptom:
+      // "Context": "" in query output despite the reference being set).
+      const rawTexts = rows.map((r) => r.value_text);
+      const resolvedTexts = resolveInlineRefsBatch(rawTexts, this.db);
+
+      for (let idx = 0; idx < rows.length; idx++) {
+        const row = rows[idx];
         let nodeMap = result.get(row.parent_id);
         if (!nodeMap) {
           nodeMap = new Map();
@@ -195,7 +204,7 @@ export class FieldResolver {
           nodeMap.set(row.field_name, values);
         }
 
-        values.push(stripHtml(row.value_text));
+        values.push(resolvedTexts[idx]);
       }
     }
 

src/utils/resolve-inline-refs.ts

@@ -0,0 +1,100 @@
+/**
+ * Resolve Tana inline-reference spans to display text.
+ *
+ * Tana stores references and dates inside field values as self-closing or
+ * empty spans:
+ *
+ *   <span data-inlineref-node="NODE_ID"></span>
+ *   <span data-inlineref-date="{&quot;dateTimeString&quot;:&quot;2026-01-26&quot;,...}"></span>
+ *
+ * When naively stripped of HTML, these collapse to empty strings — which is
+ * what caused v2.5.5's reference-field bug ("Context" → "").
+ *
+ * This module resolves those spans to their display text:
+ *   - inlineref-node → target node's `name` from the nodes table
+ *   - inlineref-date → the `dateTimeString` value
+ *
+ * Any HTML that remains after substitution is stripped (existing behavior for
+ * option fields with color spans).
+ */
+
+import { Database } from "bun:sqlite";
+import { stripHtml } from "./html";
+
+const INLINEREF_NODE_RE = /<span[^>]*data-inlineref-node="([^"]+)"[^>]*><\/span>/g;
+const INLINEREF_DATE_RE = /<span[^>]*data-inlineref-date="([^"]+)"[^>]*><\/span>/g;
+
+/**
+ * Resolve all inline-reference spans in a batch of strings. Uses a single
+ * SQL query per unique referenced-node set to avoid N+1 lookups.
+ */
+export function resolveInlineRefsBatch(values: string[], db: Database): string[] {
+  const nodeIds = new Set<string>();
+  for (const v of values) {
+    INLINEREF_NODE_RE.lastIndex = 0;
+    let m: RegExpExecArray | null;
+    while ((m = INLINEREF_NODE_RE.exec(v)) !== null) {
+      nodeIds.add(decodeHtmlEntities(m[1]));
+    }
+  }
+
+  const nameMap = nodeIds.size > 0 ? lookupNodeNames([...nodeIds], db) : new Map<string, string>();
+
+  return values.map((v) => resolveOne(v, nameMap));
+}
+
+/**
+ * Resolve a single string's inline-reference spans. Prefer the batch variant
+ * for bulk work — this is for one-off calls.
+ */
+export function resolveInlineRefs(value: string, db: Database): string {
+  return resolveInlineRefsBatch([value], db)[0];
+}
+
+function resolveOne(value: string, nameMap: Map<string, string>): string {
+  let out = value;
+
+  out = out.replace(INLINEREF_NODE_RE, (_full, rawId) => {
+    const id = decodeHtmlEntities(rawId);
+    return nameMap.get(id) ?? "";
+  });
+
+  out = out.replace(INLINEREF_DATE_RE, (_full, rawJson) => {
+    const json = decodeHtmlEntities(rawJson);
+    try {
+      const parsed = JSON.parse(json) as { dateTimeString?: string };
+      return parsed.dateTimeString ?? "";
+    } catch {
+      return "";
+    }
+  });
+
+  return stripHtml(out).trim();
+}
+
+function lookupNodeNames(ids: string[], db: Database): Map<string, string> {
+  const result = new Map<string, string>();
+  // SQLite defaults cap to ~999 params; batch conservatively at 500.
+  const BATCH = 500;
+  for (let i = 0; i < ids.length; i += BATCH) {
+    const batch = ids.slice(i, i + BATCH);
+    const placeholders = batch.map(() => "?").join(", ");
+    const rows = db
+      .query(`SELECT id, name FROM nodes WHERE id IN (${placeholders})`)
+      .all(...batch) as Array<{ id: string; name: string | null }>;
+    for (const r of rows) {
+      if (r.name) result.set(r.id, r.name);
+    }
+  }
+  return result;
+}
+
+function decodeHtmlEntities(s: string): string {
+  return s
+    .replace(/&quot;/g, '"')
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&#39;/g, "'")
+    .replace(/&apos;/g, "'");
+}

tests/unit/resolve-inline-refs.test.ts

@@ -0,0 +1,130 @@
+/**
+ * Tests for the inline-reference resolver (v2.5.7 fix).
+ *
+ * Tana stores field values that contain references or dates as empty
+ * `<span>` tags with data attributes, e.g.:
+ *
+ *   <span data-inlineref-node="abc123"></span>
+ *   <span data-inlineref-date="{&quot;dateTimeString&quot;:&quot;2026-01-26&quot;,...}"></span>
+ *
+ * Prior to this fix, FieldResolver ran stripHtml() on these and got back
+ * empty strings — causing `tana_query` to return "Context": "" for reference
+ * fields (David Delgado Vendrell's bug report against v2.5.5).
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { mkdtempSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import {
+  resolveInlineRefs,
+  resolveInlineRefsBatch,
+} from "../../src/utils/resolve-inline-refs";
+
+function makeDb(): { db: Database; dir: string } {
+  const dir = mkdtempSync(join(tmpdir(), "resolve-refs-"));
+  const db = new Database(join(dir, "t.db"));
+  db.run(`CREATE TABLE nodes (id TEXT PRIMARY KEY, name TEXT)`);
+  return { db, dir };
+}
+
+describe("resolveInlineRefs", () => {
+  let db: Database;
+  let dir: string;
+
+  beforeEach(() => {
+    ({ db, dir } = makeDb());
+    db.run("INSERT INTO nodes (id, name) VALUES (?, ?)", ["abc123", "Pr MB2"]);
+    db.run("INSERT INTO nodes (id, name) VALUES (?, ?)", ["xyz789", "Another Project"]);
+  });
+
+  afterEach(() => {
+    db.close();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("resolves a pure inline node reference to the target name (regression test)", () => {
+    const input = '<span data-inlineref-node="abc123"></span>';
+    expect(resolveInlineRefs(input, db)).toBe("Pr MB2");
+  });
+
+  it("resolves an inline reference embedded in surrounding text", () => {
+    const input = 'Meeting with <span data-inlineref-node="abc123"></span> today';
+    expect(resolveInlineRefs(input, db)).toBe("Meeting with Pr MB2 today");
+  });
+
+  it("resolves multiple references in one value", () => {
+    const input =
+      '<span data-inlineref-node="abc123"></span>, <span data-inlineref-node="xyz789"></span>';
+    expect(resolveInlineRefs(input, db)).toBe("Pr MB2, Another Project");
+  });
+
+  it("returns empty string when the referenced node is missing (deleted/orphaned)", () => {
+    const input = '<span data-inlineref-node="nonexistent"></span>';
+    expect(resolveInlineRefs(input, db)).toBe("");
+  });
+
+  it("resolves inline-ref-date to its dateTimeString", () => {
+    const input =
+      '<span data-inlineref-date="{&quot;dateTimeString&quot;:&quot;2026-01-26&quot;,&quot;timezone&quot;:&quot;UTC&quot;}"></span>';
+    expect(resolveInlineRefs(input, db)).toBe("2026-01-26");
+  });
+
+  it("handles plain text without any spans (no-op)", () => {
+    expect(resolveInlineRefs("Pr MB2", db)).toBe("Pr MB2");
+  });
+
+  it("strips residual HTML after reference substitution (option color spans)", () => {
+    const input = '<span data-color="blue">DONE</span>';
+    expect(resolveInlineRefs(input, db)).toBe("DONE");
+  });
+
+  it("trims whitespace from the final result", () => {
+    const input = '  <span data-inlineref-node="abc123"></span>  ';
+    expect(resolveInlineRefs(input, db)).toBe("Pr MB2");
+  });
+
+  it("returns empty string for completely empty input", () => {
+    expect(resolveInlineRefs("", db)).toBe("");
+  });
+
+  it("handles malformed date JSON gracefully", () => {
+    const input = '<span data-inlineref-date="not-valid-json"></span>';
+    expect(resolveInlineRefs(input, db)).toBe("");
+  });
+});
+
+describe("resolveInlineRefsBatch", () => {
+  let db: Database;
+  let dir: string;
+
+  beforeEach(() => {
+    ({ db, dir } = makeDb());
+    db.run("INSERT INTO nodes (id, name) VALUES (?, ?)", ["a", "Alpha"]);
+    db.run("INSERT INTO nodes (id, name) VALUES (?, ?)", ["b", "Beta"]);
+    db.run("INSERT INTO nodes (id, name) VALUES (?, ?)", ["c", "Gamma"]);
+  });
+
+  afterEach(() => {
+    db.close();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("resolves references across many values in one pass", () => {
+    const input = [
+      '<span data-inlineref-node="a"></span>',
+      '<span data-inlineref-node="b"></span>',
+      '<span data-inlineref-node="c"></span>',
+      "plain text",
+    ];
+    expect(resolveInlineRefsBatch(input, db)).toEqual(["Alpha", "Beta", "Gamma", "plain text"]);
+  });
+
+  it("performs a single node lookup per unique id (batch efficiency)", () => {
+    // Repeat the same ref many times; the lookup should deduplicate.
+    const input = Array.from({ length: 100 }, () => '<span data-inlineref-node="a"></span>');
+    const results = resolveInlineRefsBatch(input, db);
+    expect(results.every((r) => r === "Alpha")).toBe(true);
+  });
+});