@mkterswingman/5mghost-wonder 0.0.1

package/dist/xlsx/shared-strings.js

@@ -0,0 +1,51 @@
+import { XMLParser } from "fast-xml-parser";
+/**
+ * 解析 xl/sharedStrings.xml 内容，返回字符串池。
+ * 索引对应 sheet.xml 中 <c t="s"><v>N</v></c> 的 N。
+ *
+ * 支持两种 <si> 格式：
+ *   - 简单文本：<si><t>text</t></si>
+ *   - 富文本：  <si><r><t>part1</t></r><r><t>part2</t></r></si>
+ *
+ * @param xml xl/sharedStrings.xml 的 UTF-8 文本内容
+ * @returns string[]，下标即共享字符串索引
+ */
+export function parseSharedStrings(xml) {
+    const parser = new XMLParser({
+        ignoreAttributes: false,
+        // 关键：强制将 <si>、<r> 包装为数组，防止单元素时被解析为对象
+        isArray: (name) => name === "si" || name === "r",
+        // 保留空字符串（Excel 中存在空 <t/>）
+        parseTagValue: false,
+        // 保留空白字符（<t xml:space="preserve"> </t> 中的空格不应被 trim）
+        trimValues: false,
+    });
+    const doc = parser.parse(xml);
+    // xl/sharedStrings.xml 根节点是 <sst>
+    const sst = doc?.sst;
+    if (!sst)
+        return [];
+    const siList = sst.si ?? [];
+    return siList.map((si) => {
+        // 富文本：有 <r> 数组，拼接所有 <r><t> 内容
+        if (si.r) {
+            const runs = Array.isArray(si.r) ? si.r : [si.r];
+            return runs
+                .map((r) => textValue(r.t))
+                .join("");
+        }
+        // 简单文本：直接取 <t>
+        return textValue(si.t);
+    });
+}
+/** 将 fast-xml-parser 解析出的 <t> 节点统一转为字符串。 */
+function textValue(t) {
+    if (t == null)
+        return "";
+    // fast-xml-parser parseTagValue:false 时纯文本节点是字符串；
+    // 带属性的 <t xml:space="preserve"> 节点是对象 { "#text": "...", "@_xml:space": "..." }
+    if (typeof t === "object") {
+        return String(t["#text"] ?? "");
+    }
+    return String(t);
+}

package/dist/xlsx/sheet.js

@@ -0,0 +1,161 @@
+// src/xlsx/sheet.ts
+// Parses xl/worksheets/sheet{N}.xml.
+// Outputs a sparse cell array, merge ranges, and bounding-box dimensions.
+// Dependencies are injected: sharedStrings[] from shared-strings.ts,
+// getFormatCode() from styles.ts. This module does not read files.
+import { XMLParser } from "fast-xml-parser";
+// ---------------------------------------------------------------------------
+// XMLParser (module-level singleton — stateless, safe to reuse)
+// ---------------------------------------------------------------------------
+const parser = new XMLParser({
+    ignoreAttributes: false,
+    attributeNamePrefix: "@_",
+    // Force arrays to eliminate single-node vs. array ambiguity.
+    isArray: (name) => name === "row" || name === "c" || name === "mergeCell" || name === "r",
+    // Keep all values as strings; we convert manually based on the t attribute.
+    parseTagValue: false,
+    // Preserve whitespace (cells may contain spaces).
+    trimValues: false,
+});
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Column letters (uppercase) → 0-based column index.
+ * A→0, Z→25, AA→26, AZ→51, BA→52.
+ */
+export function colLettersToIndex(letters) {
+    let result = 0;
+    for (let i = 0; i < letters.length; i++) {
+        result = result * 26 + (letters.charCodeAt(i) - 64); // 'A'=65 → 1
+    }
+    return result - 1; // convert to 0-based
+}
+/**
+ * "B5" → { row: 4, col: 1 } (0-based).
+ */
+export function parseCellRef(ref) {
+    const match = /^([A-Z]+)(\d+)$/.exec(ref);
+    if (!match)
+        throw new Error(`Invalid cell ref: "${ref}"`);
+    return {
+        col: colLettersToIndex(match[1]),
+        row: Number(match[2]) - 1,
+    };
+}
+/**
+ * "A1:C3" → MergeRange (0-based).
+ */
+function parseMergeRef(ref) {
+    const sep = ref.indexOf(":");
+    if (sep === -1)
+        throw new Error(`Invalid merge ref: "${ref}"`);
+    const s = parseCellRef(ref.slice(0, sep));
+    const e = parseCellRef(ref.slice(sep + 1));
+    return { startRow: s.row, startCol: s.col, endRow: e.row, endCol: e.col };
+}
+/**
+ * Extract text from an <is> node (inlineStr).
+ * Handles simple <is><t>text</t></is> and rich-text <is><r><t>part</t></r>…</is>.
+ */
+function extractInlineStr(is) {
+    if (!is)
+        return "";
+    if (is.r) {
+        const runs = Array.isArray(is.r) ? is.r : [is.r];
+        return runs.map((r) => String(r?.t ?? "")).join("");
+    }
+    return String(is.t ?? "");
+}
+/**
+ * Extract a SheetCell from a single <c> node.
+ * Returns null when the cell should be skipped (error, no value, no ref).
+ */
+function extractCellValue(c, sharedStrings, getFormatCode) {
+    const ref = c["@_r"];
+    if (!ref)
+        return null;
+    const { row, col } = parseCellRef(ref);
+    const t = c["@_t"] ?? ""; // cell type; default = numeric
+    const sAttr = c["@_s"] != null ? Number(c["@_s"]) : -1;
+    // inlineStr: text lives in <is>, no <v>
+    if (t === "inlineStr") {
+        return { row, col, text: extractInlineStr(c.is) };
+    }
+    // Error cells: skip entirely
+    if (t === "e")
+        return null;
+    // All other types require <v>
+    const vRaw = c.v != null ? String(c.v) : undefined;
+    if (vRaw === undefined)
+        return null; // formula not calculated or empty cell
+    switch (t) {
+        case "s": {
+            // Shared string: <v> is the index into sharedStrings[]
+            const text = sharedStrings[Number(vRaw)] ?? "";
+            return { row, col, text };
+        }
+        case "str": {
+            // Formula result that is a string: <v> is the literal text
+            return { row, col, text: vRaw };
+        }
+        case "b": {
+            return { row, col, text: vRaw === "1" ? "TRUE" : "FALSE" };
+        }
+        default: {
+            // Numeric (t="n" or absent t)
+            const value = Number(vRaw);
+            if (isNaN(value))
+                return null;
+            const cell = { row, col, value };
+            if (sAttr >= 0) {
+                const format = getFormatCode(sAttr);
+                if (format !== undefined)
+                    cell.format = format;
+            }
+            return cell;
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Main export
+// ---------------------------------------------------------------------------
+export function parseSheet(xml, sharedStrings, getFormatCode) {
+    const doc = parser.parse(xml);
+    const ws = doc?.worksheet;
+    if (!ws)
+        return { cells: [], merges: [], maxRow: 0, maxCol: 0 };
+    // 1. Walk rows → cells
+    const cells = [];
+    let maxRow = 0;
+    let maxCol = 0;
+    const rows = ws.sheetData?.row ?? [];
+    for (const row of rows) {
+        const cList = row.c ?? [];
+        for (const c of cList) {
+            const cell = extractCellValue(c, sharedStrings, getFormatCode);
+            if (cell === null)
+                continue;
+            cells.push(cell);
+            if (cell.row > maxRow)
+                maxRow = cell.row;
+            if (cell.col > maxCol)
+                maxCol = cell.col;
+        }
+    }
+    // 2. Parse mergeCells
+    const merges = [];
+    const mergeCellList = ws.mergeCells?.mergeCell ?? [];
+    for (const mc of mergeCellList) {
+        const ref = mc["@_ref"];
+        if (!ref)
+            continue;
+        try {
+            merges.push(parseMergeRef(ref));
+        }
+        catch {
+            // Malformed ref: skip without breaking overall parse
+        }
+    }
+    return { cells, merges, maxRow, maxCol };
+}

package/dist/xlsx/styles.js

@@ -0,0 +1,85 @@
+// src/xlsx/styles.ts
+// Parses xl/styles.xml and provides a lookup from cell style index → format code.
+//
+// Three-layer mapping:
+//   cell.s  →  cellXfs[s].numFmtId  →  numFmtId → formatCode
+//
+// Built-in formats (numFmtId 0–49) are hardcoded per ECMA-376 §18.8.30.
+// Custom formats (typically numFmtId ≥ 164) come from <numFmts> in styles.xml.
+import { XMLParser } from "fast-xml-parser";
+// ECMA-376 §18.8.30 built-in number format codes.
+// numFmtId 0 (General) is intentionally included; callers must return undefined for it.
+// IDs 5–8, 23–36, 41–44 are spec-reserved and omitted — lookups return undefined.
+const BUILTIN_FORMATS = {
+    0: "General",
+    1: "0",
+    2: "0.00",
+    3: "#,##0",
+    4: "#,##0.00",
+    9: "0%",
+    10: "0.00%",
+    11: "0.00E+00",
+    12: "# ?/?",
+    13: "# ??/??",
+    14: "mm-dd-yy",
+    15: "d-mmm-yy",
+    16: "d-mmm",
+    17: "mmm-yy",
+    18: "h:mm AM/PM",
+    19: "h:mm:ss AM/PM",
+    20: "h:mm",
+    21: "h:mm:ss",
+    22: "m/d/yy h:mm",
+    37: "#,##0 ;(#,##0)",
+    38: "#,##0 ;[Red](#,##0)",
+    39: "#,##0.00;(#,##0.00)",
+    40: "#,##0.00;[Red](#,##0.00)",
+    45: "mm:ss",
+    46: "[h]:mm:ss",
+    47: "mmss.0",
+    48: "##0.0E+0",
+    49: "@",
+};
+function parseStyles(xml) {
+    const parser = new XMLParser({
+        ignoreAttributes: false,
+        attributeNamePrefix: "@_",
+        isArray: (tagName) => tagName === "xf" || tagName === "numFmt",
+    });
+    const parsed = parser.parse(xml);
+    const styleSheet = parsed?.styleSheet ?? parsed?.["styleSheet"] ?? parsed;
+    // 1. Initialise fmtMap with built-in formats
+    const fmtMap = new Map(Object.entries(BUILTIN_FORMATS).map(([k, v]) => [Number(k), v]));
+    // 2. Overlay custom formats from <numFmts>
+    const customFmts = styleSheet?.numFmts?.numFmt ?? [];
+    for (const item of customFmts) {
+        const id = Number(item["@_numFmtId"]);
+        const code = String(item["@_formatCode"] ?? "");
+        if (!Number.isNaN(id)) {
+            fmtMap.set(id, code);
+        }
+    }
+    // 3. Build xfFmtIds from <cellXfs>
+    const xfs = styleSheet?.cellXfs?.xf ?? [];
+    const xfFmtIds = xfs.map((xf) => Number(xf["@_numFmtId"] ?? 0));
+    return { fmtMap, xfFmtIds };
+}
+/**
+ * Build a lookup function from a styles.xml string.
+ *
+ * @param xml  Content of xl/styles.xml, or "" if the file is absent.
+ * @returns    A function: (styleIndex) => formatCode | undefined
+ *             Returns undefined for numFmtId=0 (General) and out-of-bounds indices.
+ */
+export function buildStylesLookup(xml) {
+    if (!xml.trim()) {
+        return () => undefined;
+    }
+    const { fmtMap, xfFmtIds } = parseStyles(xml);
+    return (styleIndex) => {
+        const numFmtId = xfFmtIds[styleIndex];
+        if (numFmtId === undefined || numFmtId === 0)
+            return undefined;
+        return fmtMap.get(numFmtId); // returns undefined when not found
+    };
+}

package/dist/xlsx/unzip.js

@@ -0,0 +1,33 @@
+// src/xlsx/unzip.ts
+// Phase 2: Thin wrapper around JSZip for reading xlsx entries.
+import JSZip from "jszip";
+import { readFile } from "node:fs/promises";
+/**
+ * Open an xlsx file and return an XlsxZip handle.
+ * The entire ZIP is loaded into memory once; subsequent reads are synchronous
+ * decompression so they are fast for typical xlsx sizes.
+ */
+export async function openXlsx(filePath) {
+    const buffer = await readFile(filePath);
+    const zip = await JSZip.loadAsync(buffer);
+    return {
+        async readEntry(path) {
+            const file = zip.file(path);
+            if (!file)
+                return null;
+            return file.async("string");
+        },
+        async readEntryBuffer(path) {
+            const file = zip.file(path);
+            if (!file)
+                return null;
+            return file.async("nodebuffer");
+        },
+        entryNames() {
+            return Object.keys(zip.files);
+        },
+        get rawJSZip() {
+            return zip;
+        },
+    };
+}

package/dist/xlsx/workbook.js

@@ -0,0 +1,51 @@
+// src/xlsx/workbook.ts
+// Phase 2-01: Parse xl/workbook.xml + xl/_rels/workbook.xml.rels
+import { XMLParser } from "fast-xml-parser";
+/**
+ * Parse xl/workbook.xml + xl/_rels/workbook.xml.rels from an open XlsxZip.
+ * Includes hidden tabs (hidden: true).
+ * Returns tabs in workbook.xml document order.
+ */
+export async function parseWorkbook(zip) {
+    const parser = new XMLParser({
+        ignoreAttributes: false,
+        attributeNamePrefix: "@_",
+        parseAttributeValue: false,
+        isArray: (name) => name === "sheet" || name === "Relationship",
+    });
+    // --- workbook.xml ---
+    const wbXml = await zip.readEntry("xl/workbook.xml");
+    if (!wbXml)
+        throw new Error("xl/workbook.xml not found in xlsx archive");
+    const wbParsed = parser.parse(wbXml);
+    // Navigate: workbook.sheets.sheet[]
+    const wb = wbParsed["workbook"];
+    const sheets = wb["sheets"]["sheet"];
+    // --- workbook.xml.rels ---
+    const relsXml = await zip.readEntry("xl/_rels/workbook.xml.rels");
+    if (!relsXml)
+        throw new Error("xl/_rels/workbook.xml.rels not found in xlsx archive");
+    const relsParsed = parser.parse(relsXml);
+    const relationships = relsParsed["Relationships"]["Relationship"];
+    // Build rId → Target map, only worksheet type entries
+    const rIdToPath = new Map();
+    for (const rel of relationships) {
+        const type = rel["@_Type"] ?? "";
+        if (type.endsWith("/worksheet")) {
+            rIdToPath.set(rel["@_Id"], rel["@_Target"]);
+        }
+    }
+    // Merge
+    const tabs = sheets.map((sheet) => {
+        // r:id attribute is parsed as "@_r:id" by fast-xml-parser
+        const rId = sheet["@_r:id"] ?? "";
+        return {
+            name: sheet["@_name"] ?? "",
+            sheetId: sheet["@_sheetId"] ?? "",
+            rId,
+            hidden: sheet["@_state"] === "hidden",
+            sheetPath: rIdToPath.get(rId) ?? "",
+        };
+    });
+    return { tabs };
+}

package/dist/xlsx/workbook.test.js

@@ -0,0 +1,19 @@
+// src/xlsx/workbook.test.ts — Node assert, no framework
+import assert from "node:assert/strict";
+import { openXlsx } from "./unzip.js";
+import { parseWorkbook } from "./workbook.js";
+const REAL_FILE = "/Users/yimingwang/Downloads/盛世天下-Steam素材交付.xlsx";
+const zip = await openXlsx(REAL_FILE);
+const { tabs } = await parseWorkbook(zip);
+assert.equal(tabs.length, 10, `Expected 10 tabs, got ${tabs.length}`);
+assert.equal(tabs[0].name, "上部Steam商店页预览");
+assert.equal(tabs[3].hidden, true, "tabs[3] should be hidden");
+assert.equal(tabs[3].sheetPath, "worksheets/sheet4.xml");
+assert.equal(tabs[5].hidden, true, "tabs[5] should be hidden");
+assert.equal(tabs[9].name, "下部Steam商店页预览");
+assert.equal(tabs[9].sheetPath, "worksheets/sheet10.xml");
+for (const tab of tabs) {
+    assert.ok(tab.sheetPath.length > 0, `Tab "${tab.name}" has empty sheetPath`);
+}
+console.log("✅ parseWorkbook: all assertions passed");
+console.log(tabs.map((t) => `${t.hidden ? "[hidden] " : ""}${t.name} -> ${t.sheetPath}`).join("\n"));

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@mkterswingman/5mghost-wonder",
+  "version": "0.0.1",
+  "description": "企微文档读取 CLI — WeCom document reader",
+  "type": "module",
+  "engines": { "node": ">=18" },
+  "bin": { "wonder": "./dist/cli.js" },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/5mghost/5mghost-wonder.git"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "skills.manifest.json",
+    "scripts"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc && chmod +x dist/cli.js",
+    "typecheck": "tsc --noEmit",
+    "test": "node dist/wecom/url.test.js",
+    "smoke": "npm run build && node dist/cli.js help > /dev/null",
+    "postinstall": "node scripts/postinstall.mjs"
+  },
+  "dependencies": {
+    "@mkterswingman/5mghost-auth": "^0.0.1",
+    "@mkterswingman/5mghost-telemetry": "^0.0.1",
+    "@mkterswingman/5mghost-agent-skills": "^0.0.1",
+    "ws": "^8.18.0",
+    "fast-xml-parser": "^4.5.0",
+    "jszip": "^3.10.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.5.0",
+    "typescript": "^5.8.0"
+  }
+}

package/scripts/check-export-types.mjs

@@ -0,0 +1,37 @@
+// scripts/check-export-types.mjs
+// Smoke test: verify that the compiled export module exports the expected symbols.
+// Run after build: node scripts/check-export-types.mjs
+
+import { parseWecomUrl } from "../dist/wecom/url.js";
+import { exportWecomDoc, ExportError } from "../dist/wecom/export.js";
+
+// Verify exported symbols are functions/classes
+if (typeof parseWecomUrl !== "function") throw new Error("parseWecomUrl not a function");
+if (typeof exportWecomDoc !== "function") throw new Error("exportWecomDoc not a function");
+if (typeof ExportError !== "function") throw new Error("ExportError not a class");
+
+// Verify ExportError is throwable
+const err = new ExportError("poll_timeout", "test error");
+if (err.name !== "ExportError") throw new Error("ExportError.name wrong");
+if (err.kind !== "poll_timeout") throw new Error("ExportError.kind wrong");
+if (err.message !== "test error") throw new Error("ExportError.message wrong");
+if (!(err instanceof Error)) throw new Error("ExportError not instanceof Error");
+
+// Verify parseWecomUrl returns correct discriminated union shape
+const parsed = parseWecomUrl("https://doc.weixin.qq.com/sheet/e3_TestId");
+if (!parsed.ok) throw new Error("parseWecomUrl failed for valid sheet URL");
+if (parsed.docType !== "sheet") throw new Error(`docType wrong: ${parsed.docType}`);
+if (parsed.docId !== "e3_TestId") throw new Error(`docId wrong: ${parsed.docId}`);
+
+const smartpage = parseWecomUrl("https://doc.weixin.qq.com/smartpage/a1_Test");
+if (smartpage.ok) throw new Error("smartpage should be unsupported");
+if (smartpage.reason !== "unsupported" || smartpage.kind !== "smartpage") {
+  throw new Error(`smartpage narrowing wrong: ${JSON.stringify(smartpage)}`);
+}
+
+const bad = parseWecomUrl("not-a-url");
+if (bad.ok || bad.reason !== "invalid") {
+  throw new Error(`bad URL should reason=invalid: ${JSON.stringify(bad)}`);
+}
+
+console.log("✅ export module: all symbols present and structurally correct");

package/scripts/postinstall.mjs

@@ -0,0 +1,50 @@
+// scripts/postinstall.mjs
+// Runs after `npm install -g` to install wonder skills into detected AI clients.
+// Must be plain Node ESM — no TypeScript, no Bun dependencies.
+// This file runs from the installed package directory, so paths are resolved
+// relative to import.meta.url.
+
+import { fileURLToPath } from "url";
+import { dirname, resolve } from "path";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+let listDetectedAgents, installSkills;
+
+try {
+  ({ listDetectedAgents, installSkills } = await import(
+    "@mkterswingman/5mghost-agent-skills"
+  ));
+} catch (err) {
+  // agent-skills not yet available (e.g. first install before deps resolve)
+  console.log("[wonder] agent-skills not available — skipping skill install.");
+  process.exit(0);
+}
+
+const manifestPath = resolve(__dirname, "../skills.manifest.json");
+
+let agents;
+try {
+  agents = await listDetectedAgents();
+} catch (err) {
+  console.log("[wonder] Could not detect AI clients — skipping skill install.");
+  process.exit(0);
+}
+
+if (!agents || agents.length === 0) {
+  console.log("[wonder] No AI clients detected — skipping skill install.");
+  process.exit(0);
+}
+
+try {
+  const result = await installSkills({ manifestPath, detectedAgents: agents });
+  const installed = result.installedTo ?? [];
+  if (installed.length > 0) {
+    console.log(`[wonder] Installed skills to: ${installed.join(", ")}`);
+  } else {
+    console.log("[wonder] No skill targets updated.");
+  }
+} catch (err) {
+  // Skill install failure must never break npm install
+  console.log(`[wonder] Skill install failed (non-fatal): ${String(err)}`);
+}