@mkterswingman/5mghost-wonder 0.0.6 → 0.0.7

package/dist/xlsx/format.js

@@ -0,0 +1,171 @@
+// src/xlsx/format.ts
+// Convert Excel number values to display strings using their numFmt format
+// codes. Currently handles date / time / datetime formats — the most common
+// source of "?" placeholders in WeCom xlsx output (date columns, time slots).
+//
+// Excel serial date semantics: integer = days since 1899-12-30, fractional
+// part = time-of-day fraction. There is a legacy "1900 leap-year bug" where
+// serial 60 represents the (fictional) 1900-02-29; standard practice is to
+// pin the epoch to 1899-12-30 so the off-by-one cancels out for all serials
+// >= 61. Serials < 61 are rare in real workbooks and are left to fall back
+// to numeric formatting; the WeCom date columns we target are all in 2025+.
+const DAY_MS = 24 * 60 * 60 * 1000;
+const EPOCH_UTC = Date.UTC(1899, 11, 30); // 1899-12-30
+/**
+ * Detect whether a number-format code contains date/time tokens. Tokens
+ * inside double-quoted literals (e.g. `"年"`, `"月"`) and inside escaped
+ * characters (`\.`) are ignored.
+ *
+ * Date tokens: y, m, d (also full names `mm`, `mmm`, `mmmm`, `dd`, `ddd`).
+ * Time tokens: h, s, AM/PM. Note: lowercase `m` is ambiguous (month vs.
+ * minute) — we keep it simple: any unquoted `m` adjacent to `h` or `s` is
+ * still classed as date-or-time, which is fine for our purposes.
+ */
+export function classifyFormat(format) {
+    let inQuote = false;
+    let escape = false;
+    let hasDate = false;
+    let hasTime = false;
+    const toks = [];
+    for (let i = 0; i < format.length; i++) {
+        const ch = format[i];
+        if (escape) {
+            escape = false;
+            continue;
+        }
+        if (ch === "\\") {
+            escape = true;
+            continue;
+        }
+        if (ch === '"') {
+            inQuote = !inQuote;
+            continue;
+        }
+        if (inQuote)
+            continue;
+        toks.push({ ch, pos: i });
+    }
+    // Indices that belong to AM/PM literals — they are time markers and
+    // must not be treated as month/minute when we walk through tokens.
+    const ampmIdx = new Set();
+    for (let i = 0; i < toks.length; i++) {
+        const ch = toks[i].ch;
+        if (ch.toLowerCase() !== "a")
+            continue;
+        // Try AM/PM first (5 tokens), then AM/P (4 tokens).
+        const slice5 = toks
+            .slice(i, i + 5)
+            .map((t) => t.ch.toUpperCase())
+            .join("");
+        const slice4 = toks
+            .slice(i, i + 4)
+            .map((t) => t.ch.toUpperCase())
+            .join("");
+        if (slice5 === "AM/PM") {
+            hasTime = true;
+            for (let j = i; j < i + 5; j++)
+                ampmIdx.add(j);
+        }
+        else if (slice4 === "AM/P") {
+            hasTime = true;
+            for (let j = i; j < i + 4; j++)
+                ampmIdx.add(j);
+        }
+    }
+    for (let i = 0; i < toks.length; i++) {
+        if (ampmIdx.has(i))
+            continue;
+        const t = toks[i];
+        const lower = t.ch.toLowerCase();
+        if (lower === "y" || lower === "d") {
+            hasDate = true;
+        }
+        else if (lower === "h" || lower === "s") {
+            hasTime = true;
+        }
+        else if (lower === "m") {
+            // Excel's lowercase `m` is ambiguous between month and minute.
+            // Disambiguation rule (matches Excel's own behaviour): `m` is
+            // minutes when adjacent to an h/hh token (immediately before, run
+            // of m's allowed) or immediately before s/ss. Otherwise month.
+            // We search through runs of m and across simple separators
+            // (`:` is the canonical time separator) but stop at any other
+            // letter — so `AM/PM` with its `/` separator does not pollute.
+            const prev = findAdjacentLetter(toks, i, -1, ampmIdx);
+            const next = findAdjacentLetter(toks, i, 1, ampmIdx);
+            const prevH = prev != null && prev.ch.toLowerCase() === "h";
+            const nextS = next != null && next.ch.toLowerCase() === "s";
+            if (prevH || nextS)
+                hasTime = true;
+            else
+                hasDate = true;
+        }
+        // AM/PM is handled in the pre-pass above.
+    }
+    return { hasDate, hasTime };
+}
+/**
+ * Walk through `m` characters and time-only separators (`:`) to find the
+ * nearest disambiguating letter. Stops on any non-`:` separator — so a
+ * format like `mm/yyyy` correctly classifies the `m` as month (slash
+ * stops the search), and `h:mm:ss AM/PM` keeps the `m` as minute (only
+ * `:` separators between h and the m run).
+ */
+function findAdjacentLetter(toks, from, step, skip) {
+    // Disambiguating month-vs-minute by looking at the nearest letter token,
+    // skipping over m's, time separators (`:`), and whitespace. Stops on
+    // any other separator (e.g. `/`, `-`) so that `mm/yyyy` correctly keeps
+    // `m` as month while `h:mm:ss` and `h mm` correctly keep it as minute.
+    for (let i = from + step; i >= 0 && i < toks.length; i += step) {
+        if (skip.has(i))
+            continue;
+        const ch = toks[i].ch;
+        if (ch.toLowerCase() === "m")
+            continue;
+        if (ch === ":")
+            continue;
+        if (ch === " " || ch === "\t")
+            continue;
+        if (/[a-zA-Z]/.test(ch))
+            return toks[i];
+        return null; // hard separator stops the search
+    }
+    return null;
+}
+function pad2(n) {
+    return n < 10 ? `0${n}` : String(n);
+}
+/**
+ * Render an Excel serial number as a display string using a sensible
+ * default — `YYYY-MM-DD` for pure dates, `HH:MM` for pure times,
+ * `YYYY-MM-DD HH:MM` for combined. We deliberately do not honour the
+ * exact format string (e.g. `m"月"d"日"`) because the goal is for the
+ * AI / user to see *some* readable date, not a pixel-perfect Excel render.
+ */
+export function formatSerial(value, kind) {
+    const ms = EPOCH_UTC + Math.round(value * DAY_MS);
+    const d = new Date(ms);
+    const Y = d.getUTCFullYear();
+    const M = pad2(d.getUTCMonth() + 1);
+    const D = pad2(d.getUTCDate());
+    const h = pad2(d.getUTCHours());
+    const m = pad2(d.getUTCMinutes());
+    if (kind.hasDate && kind.hasTime)
+        return `${Y}-${M}-${D} ${h}:${m}`;
+    if (kind.hasDate)
+        return `${Y}-${M}-${D}`;
+    if (kind.hasTime)
+        return `${h}:${m}`;
+    return String(value);
+}
+/**
+ * Convenience: returns a rendered text string when `format` is a date/time
+ * format, undefined otherwise. The caller should fall back to the raw
+ * numeric value when undefined is returned.
+ */
+export function renderNumberByFormat(value, format) {
+    const kind = classifyFormat(format);
+    if (!kind.hasDate && !kind.hasTime)
+        return undefined;
+    return formatSerial(value, kind);
+}

package/dist/xlsx/parse-tab.js

@@ -99,6 +99,31 @@ export async function parseTab(xlsxPath, tabName, saveDir) {
         if (m.endCol > maxCol)
             maxCol = m.endCol;
     }
+    // Step 7c.5: annotate top-left anchor cells with their merge span. We do
+    // this after image merging so even cells that exist only because of an
+    // image anchor still receive the span if they happen to be a merge anchor
+    // (rare but possible — e.g. a merged cell whose only content is a picture).
+    for (const m of sheetData.merges) {
+        const rows = m.endRow - m.startRow + 1;
+        const cols = m.endCol - m.startCol + 1;
+        if (rows === 1 && cols === 1)
+            continue; // not really a merge
+        const key = cellKey(m.startRow, m.startCol);
+        const anchor = cellMap.get(key);
+        if (anchor) {
+            anchor.mergeSpan = { rows, cols };
+        }
+        else {
+            // Anchor has no content of its own; create a stub so the merge span
+            // is still surfaced. Without this, an empty merged-anchor cell would
+            // be invisible in cells[] even though it represents a 4-row block.
+            cellMap.set(key, {
+                row: m.startRow,
+                col: m.startCol,
+                mergeSpan: { rows, cols },
+            });
+        }
+    }
     // Step 7d: sort cells row-asc, col-asc
     const cells = Array.from(cellMap.values()).sort((a, b) => a.row !== b.row ? a.row - b.row : a.col - b.col);
     return {

package/dist/xlsx/sheet.js

@@ -12,6 +12,7 @@
 // still injected: `sharedStrings[]` from shared-strings.ts and
 // `getFormatCode()` from styles.ts.
 import { SaxesParser } from "saxes";
+import { renderNumberByFormat } from "./format.js";
 // ---------------------------------------------------------------------------
 // Cell ref helpers (pure functions, reused)
 // ---------------------------------------------------------------------------
@@ -207,8 +208,15 @@ function buildCell(ref, cType, cStyleIdx, vRaw, isText, sharedStrings, getFormat
             const cell = { row, col, value };
             if (cStyleIdx >= 0) {
                 const format = getFormatCode(cStyleIdx);
-                if (format !== undefined)
+                if (format !== undefined) {
                     cell.format = format;
+                    // Render dates/times to a readable text so consumers don't have
+                    // to translate Excel serial numbers themselves. Other formats
+                    // (currency, percentages, etc.) are left numeric.
+                    const rendered = renderNumberByFormat(value, format);
+                    if (rendered !== undefined)
+                        cell.text = rendered;
+                }
             }
             return cell;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mkterswingman/5mghost-wonder",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "企微文档读取 CLI — WeCom document reader",
   "type": "module",
   "engines": {
@@ -25,7 +25,7 @@
   "scripts": {
     "build": "rm -rf dist && tsc && chmod +x dist/cli.js",
     "typecheck": "tsc --noEmit",
-    "test": "node dist/wecom/url.test.js && node --test tests/sheet-parity.test.mjs && node --test tests/export-sanitize.test.mjs",
+    "test": "node dist/wecom/url.test.js && node --test tests/sheet-parity.test.mjs && node --test tests/export-sanitize.test.mjs && node --test tests/format.test.mjs",
     "smoke": "npm run build && node dist/cli.js help > /dev/null",
     "postinstall": "node scripts/postinstall.mjs"
   },

package/skills/use-5mghost-wonder/SKILL.md

@@ -96,6 +96,18 @@ Output is a structured JSON:
 
 Consume this JSON directly to answer the user's question.
 
+### ⚠️ Merged cells — always check `mergeSpan`
+
+A cell may carry `mergeSpan: {rows, cols}` when it is the top-left anchor of a merged range. The cell's content is shared across `rows × cols` grid positions starting at `(row, col)`. **When the user asks about a cell's content, always factor `mergeSpan` into the answer.**
+
+Concrete example: in a half-hour-grid time table, a `mergeSpan: {rows: 4, cols: 1}` anchored at `(row=39, col=40)` saying "★直播 + Poach" means the activity actually occupies **4 half-hour slots = 2 hours**, not 30 minutes. Quoting only the anchor row's time would mislead the user.
+
+The complete merge list is also available in the top-level `merges[]` array if you need to reason about every merge in the sheet.
+
+### ⚠️ Date / time cells — read `text`, not `value`
+
+Number cells with date or time formats (e.g. `m"月"d"日"`, `h:mm`) are rendered into a readable `text` string (`"2026-04-30"`, `"12:00"`) alongside the raw `value` and `format`. **Always use `text` when reporting dates and times to the user.** The raw `value` is an Excel serial number (days since 1899-12-30) and is meaningless to humans.
+
 ### ⚠️ Row/column indexing — JSON is 0-based, Excel is 1-based
 
 In wonder's JSON output, `row` and `col` (and `startRow`/`endRow`/`startCol`/`endCol` in `merges`) are **0-based**. Excel addresses the user sees in the WeCom UI are **1-based**.