@mkterswingman/5mghost-wonder 0.0.1

package/dist/commands/read.js

@@ -0,0 +1,198 @@
+// src/commands/read.ts
+// Implements `wonder read <url> [--save <dir>] [--tab <name>]`.
+// Phase 1: URL routing, export, metadata output.
+// Phase 2: --tab cell/merge/image parsing.
+import { parseWecomUrl } from "../wecom/url.js";
+import { exportWecomDoc, ExportError } from "../wecom/export.js";
+import { loadCookies, getCookieStatus } from "../wecom/cookies.js";
+import { resolveWonderPaths } from "../platform/paths.js";
+import { lookupCachedExport, saveExportToCache } from "../wecom/cache.js";
+import { parseTab } from "../xlsx/parse-tab.js";
+export async function runReadCommand(args, context) {
+    // --- Parse flags ---
+    let url;
+    let saveDir;
+    let tabName;
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === "--save" && args[i + 1]) {
+            saveDir = args[++i];
+        }
+        else if (args[i] === "--tab" && args[i + 1]) {
+            tabName = args[++i];
+        }
+        else if (!args[i].startsWith("-")) {
+            url = args[i];
+        }
+    }
+    const writeError = (obj) => {
+        context.io.stderr(JSON.stringify(obj));
+    };
+    // --- URL required ---
+    if (!url) {
+        writeError({ error: "missing_url", message: "用法：wonder read <url> [--save <dir>]" });
+        return { exitCode: 1, telemetry: { outcome: "failure", errorKind: "missing_url" } };
+    }
+    // --- Parse URL ---
+    const parsed = parseWecomUrl(url);
+    if (!parsed.ok) {
+        if (parsed.reason === "unsupported") {
+            const hint = parsed.kind === "smartpage"
+                ? "当前版本不支持智能文档（smartpage）。建议在浏览器中手动打开文档，选择导出为 PDF 或复制内容。"
+                : "当前版本不支持思维导图（mind）。建议在浏览器中手动打开文档并复制内容。";
+            writeError({
+                error: "unsupported_type",
+                kind: parsed.kind,
+                message: hint,
+            });
+            return {
+                exitCode: 2,
+                telemetry: { outcome: "failure", errorKind: `unsupported_${parsed.kind}` },
+            };
+        }
+        writeError({ error: "invalid_url", message: "无法识别的 WeCom URL" });
+        return { exitCode: 1, telemetry: { outcome: "failure", errorKind: "invalid_url" } };
+    }
+    const { docId, docType } = parsed;
+    // --- Auth pre-check ---
+    const paths = resolveWonderPaths({ homeDir: context.homeDir });
+    if (context.authSdk?.getAuthStatus) {
+        const authStatus = await context.authSdk.getAuthStatus({ homeDir: paths.homeDir });
+        if (!authStatus.authenticated) {
+            writeError({ error: "not_authenticated", message: "请先执行 wonder auth login" });
+            return { exitCode: 1, telemetry: { outcome: "failure", errorKind: "not_authenticated" } };
+        }
+    }
+    // --- Cookie pre-check ---
+    const cookieStatus = await getCookieStatus(paths.cookiesPath);
+    if (!cookieStatus.valid) {
+        writeError({
+            error: "cookie_invalid",
+            message: "WeCom cookie 无效或已过期，请执行 wonder wecom cookie",
+        });
+        return { exitCode: 1, telemetry: { outcome: "failure", errorKind: "cookie_invalid" } };
+    }
+    // Load cookies and convert Record<string,string> → CookieEntry[]
+    const rawCookies = loadCookies(paths.cookiesPath);
+    const cookies = rawCookies
+        ? Object.entries(rawCookies).map(([name, value]) => ({ name, value }))
+        : [];
+    // --- Resolve save dir ---
+    const resolvedSaveDir = saveDir ?? paths.defaultSaveDir;
+    // --- Export (with local cache) ---
+    const tokValue = rawCookies?.["TOK"] ?? "";
+    const cacheDir = paths.cacheDir;
+    const noCache = args.includes("--no-cache");
+    let result = null;
+    if (!noCache && tokValue) {
+        const hit = lookupCachedExport({
+            cacheDir,
+            docId,
+            tokValue,
+            maxAgeMs: 10 * 60 * 1000,
+        });
+        if (hit && hit.docType === docType) {
+            // Materialize the cached file into the requested saveDir so downstream
+            // tools that depend on `--save <dir>` keep finding the file there.
+            const { mkdirSync, copyFileSync } = await import("node:fs");
+            const { join } = await import("node:path");
+            mkdirSync(resolvedSaveDir, { recursive: true });
+            const materialisedPath = join(resolvedSaveDir, hit.fileName);
+            try {
+                copyFileSync(hit.filePath, materialisedPath);
+            }
+            catch {
+                // If copy fails, fall back to the cache path — still functional.
+            }
+            result = {
+                filePath: materialisedPath,
+                fileName: hit.fileName,
+                fileSizeBytes: hit.fileSizeBytes,
+                docType,
+            };
+        }
+    }
+    if (!result) {
+        try {
+            const fresh = await exportWecomDoc({
+                docId,
+                docType,
+                sourceUrl: url,
+                cookies,
+                saveDir: resolvedSaveDir,
+            });
+            if (!noCache && tokValue) {
+                try {
+                    saveExportToCache({
+                        cacheDir,
+                        docId,
+                        tokValue,
+                        sourceFilePath: fresh.filePath,
+                        fileName: fresh.fileName,
+                        fileSizeBytes: fresh.fileSizeBytes,
+                        docType,
+                    });
+                }
+                catch {
+                    // Cache save failure must not break the command.
+                }
+            }
+            result = {
+                filePath: fresh.filePath,
+                fileName: fresh.fileName,
+                fileSizeBytes: fresh.fileSizeBytes,
+                docType,
+            };
+        }
+        catch (err) {
+            if (err instanceof ExportError) {
+                writeError({
+                    error: "export_failed",
+                    errorKind: err.kind,
+                    message: err.message,
+                });
+                return {
+                    exitCode: 1,
+                    telemetry: { outcome: "failure", errorKind: err.kind, errorMessage: err.message },
+                };
+            }
+            const msg = err instanceof Error ? err.message : String(err);
+            writeError({ error: "export_failed", message: msg });
+            return { exitCode: 1, telemetry: { outcome: "failure", errorKind: "unknown", errorMessage: msg } };
+        }
+    }
+    // --- Build output ---
+    if (docType === "sheet") {
+        if (tabName !== undefined) {
+            // --tab: full parse, return TabOutput
+            try {
+                const tabOutput = await parseTab(result.filePath, tabName, resolvedSaveDir);
+                context.io.stdout(JSON.stringify(tabOutput));
+                return { exitCode: 0, telemetry: { outcome: "success" } };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                writeError({ error: "tab_parse_failed", message: msg });
+                return { exitCode: 1, telemetry: { outcome: "failure", errorKind: "tab_parse_failed", errorMessage: msg } };
+            }
+        }
+        // No --tab: return workbook metadata with hidden flags
+        const { openXlsx } = await import("../xlsx/unzip.js");
+        const { parseWorkbook } = await import("../xlsx/workbook.js");
+        const zip = await openXlsx(result.filePath);
+        const workbookInfo = await parseWorkbook(zip);
+        context.io.stdout(JSON.stringify({
+            type: "sheet",
+            fileName: result.fileName,
+            filePath: result.filePath,
+            tabs: workbookInfo.tabs.map((t) => ({
+                name: t.name,
+                hidden: t.hidden,
+            })),
+        }));
+        return { exitCode: 0, telemetry: { outcome: "success" } };
+    }
+    // doc or slide
+    const outputType = docType === "doc" ? "doc" : "slide";
+    context.io.stdout(JSON.stringify({ type: outputType, path: result.filePath }));
+    return { exitCode: 0, telemetry: { outcome: "success" } };
+}

package/dist/commands/setup.js

@@ -0,0 +1,81 @@
+// src/commands/setup.ts
+// Guided first-time setup: checks current state, prints numbered steps for
+// anything that is missing, then runs `wonder check` to summarise final state.
+//
+// wonder does NOT perform interactive stdin prompts — each step (auth, wecom)
+// is a separate command the user runs. setup is the guide, not the executor.
+import { runCheckCommand } from "./check.js";
+export async function runSetupCommand(_argv, context) {
+    context.io.stdout([
+        "5mghost-wonder setup",
+        "",
+        "This wizard checks your current state and tells you what to run.",
+        "You can re-run `wonder setup` at any time to see updated status.",
+        "",
+        "──────────────────────────────────────────────────",
+    ].join("\n"));
+    // ── Step 1: Auth ─────────────────────────────────────────────────────────
+    let authReady = false;
+    if (!context.authSdk) {
+        context.io.stdout("Step 1 — mkterswingman auth: not configured (sdk unavailable)");
+    }
+    else {
+        try {
+            const status = await context.authSdk.getAuthStatus({
+                homeDir: context.homeDir,
+            });
+            if (status.authenticated) {
+                authReady = true;
+                context.io.stdout("Step 1 — mkterswingman auth: ✓ authenticated");
+            }
+            else {
+                context.io.stdout([
+                    "Step 1 — mkterswingman auth: not authenticated",
+                    "  → Run: wonder auth login",
+                    "  → Or:  wonder auth login --pat <YOUR_TOKEN>",
+                ].join("\n"));
+            }
+        }
+        catch (err) {
+            context.io.stdout(`Step 1 — mkterswingman auth: error (${String(err)})`);
+        }
+    }
+    // ── Step 2: WeCom cookie ─────────────────────────────────────────────────
+    let cookieReady = false;
+    try {
+        const { getCookieStatus } = await import("../wecom/cookies.js");
+        const { resolveWonderPaths } = await import("../platform/paths.js");
+        const paths = resolveWonderPaths({ homeDir: context.homeDir });
+        const cs = await getCookieStatus(paths.cookiesPath);
+        if (cs.exists && cs.valid === true) {
+            cookieReady = true;
+            context.io.stdout("Step 2 — WeCom cookies: ✓ valid");
+        }
+        else if (cs.exists && cs.valid === false) {
+            context.io.stdout([
+                "Step 2 — WeCom cookies: invalid or expired",
+                "  → Run: wonder wecom cookie",
+                "  → (Open Chrome, scan QR code when prompted)",
+            ].join("\n"));
+        }
+        else {
+            context.io.stdout([
+                "Step 2 — WeCom cookies: not configured",
+                "  → Run: wonder wecom cookie",
+                "  → (Open Chrome, scan QR code when prompted)",
+            ].join("\n"));
+        }
+    }
+    catch (_err) {
+        context.io.stdout("Step 2 — WeCom cookies: could not check status (wecom module unavailable)");
+    }
+    // ── Summary ──────────────────────────────────────────────────────────────
+    context.io.stdout("──────────────────────────────────────────────────");
+    if (authReady && cookieReady) {
+        context.io.stdout("All steps complete. Running `wonder check` to verify...");
+        context.io.stdout("");
+        return runCheckCommand([], context);
+    }
+    context.io.stdout("Complete the steps above, then run `wonder check` to verify.");
+    return { exitCode: 1 };
+}

package/dist/commands/types.js

@@ -0,0 +1,4 @@
+// src/commands/types.ts
+// Core DI types shared by all commands.
+// All imports use .js extension (NodeNext ESM requirement).
+export {};

package/dist/commands/uninstall.js

@@ -0,0 +1,14 @@
+// src/commands/uninstall.ts
+// Runs `npm uninstall -g @mkterswingman/5mghost-wonder`.
+// NpmExecutor is injectable for unit testing.
+import { defaultNpmExecutor } from "../platform/npm.js";
+export async function runUninstallCommand(_argv, context, executor = defaultNpmExecutor) {
+    context.io.stdout("Uninstalling 5mghost-wonder...");
+    const result = executor(["uninstall", "-g", "@mkterswingman/5mghost-wonder"]);
+    if (result.exitCode !== 0) {
+        context.io.stderr(`Uninstall failed:\n${result.stderr}`);
+        return { exitCode: 1 };
+    }
+    context.io.stdout("Uninstalled successfully.");
+    return { exitCode: 0 };
+}

package/dist/commands/update.js

@@ -0,0 +1,21 @@
+// src/commands/update.ts
+// Runs `npm install -g @mkterswingman/5mghost-wonder@latest`.
+// NpmExecutor is injectable for unit testing.
+import { defaultNpmExecutor } from "../platform/npm.js";
+export async function runUpdateCommand(_argv, context, executor = defaultNpmExecutor) {
+    context.io.stdout("Checking for updates...");
+    const result = executor([
+        "install",
+        "-g",
+        "@mkterswingman/5mghost-wonder@latest",
+    ]);
+    if (result.exitCode !== 0) {
+        context.io.stderr(`Update failed:\n${result.stderr}`);
+        return {
+            exitCode: 1,
+            telemetry: { outcome: "failure", errorKind: "npm_update_failed" },
+        };
+    }
+    context.io.stdout("Updated successfully.");
+    return { exitCode: 0 };
+}

package/dist/commands/version.js

@@ -0,0 +1,8 @@
+// src/commands/version.ts
+// Prints the installed CLI version from package.json.
+// Uses `with { type: "json" }` assertion — required for NodeNext ESM JSON imports.
+import packageJson from "../../package.json" with { type: "json" };
+export async function runVersionCommand(_argv, context) {
+    context.io.stdout(packageJson.version);
+    return { exitCode: 0 };
+}

package/dist/commands/wecom.js

@@ -0,0 +1,136 @@
+// src/commands/wecom.ts
+// CLI dispatch for: wonder wecom cookie | status | set-cookie
+import { resolveWonderPaths } from "../platform/paths.js";
+import { collectWecomCookiesViaBrowser } from "../wecom/browser.js";
+import { getCookieStatus, parseCookieInput, saveCookies, validateCookies, } from "../wecom/cookies.js";
+const KEY_COOKIES = [
+    "TOK",
+    "wedrive_sid",
+    "uid",
+    "uid_key",
+    "wedrive_ticket",
+    "wedrive_skey",
+];
+// ---------------------------------------------------------------------------
+// Top-level subcommand router
+// ---------------------------------------------------------------------------
+export async function runWecom(argv, context) {
+    const [sub, ...rest] = argv;
+    switch (sub) {
+        case "cookie":
+            return runWecomCookie(rest, context);
+        case "status":
+            return runWecomStatus(rest, context);
+        case "set-cookie":
+            return runWecomSetCookie(rest, context);
+        default:
+            context.io.stderr(`Unknown subcommand: wecom ${sub ?? "(none)"}\n` +
+                "Usage: wonder wecom cookie | status | set-cookie");
+            return { exitCode: 1 };
+    }
+}
+// ---------------------------------------------------------------------------
+// wonder wecom cookie
+// ---------------------------------------------------------------------------
+async function runWecomCookie(_argv, context) {
+    const paths = resolveWonderPaths({ homeDir: context.homeDir });
+    context.io.stdout("Opening Chrome for WeCom login...");
+    context.io.stdout("Please scan the QR code in the browser. Waiting up to 3 minutes...");
+    let cookies;
+    try {
+        cookies = await collectWecomCookiesViaBrowser({
+            chromeProfilePath: paths.chromeProfilePath,
+            io: context.io,
+        });
+    }
+    catch (err) {
+        context.io.stderr(`Failed to collect cookies: ${String(err)}`);
+        return { exitCode: 1, telemetry: { errorKind: "browser_collect_failed" } };
+    }
+    saveCookies(paths.cookiesPath, cookies);
+    // Live-validate immediately after collection.
+    const valid = await validateCookies(cookies);
+    if (!valid) {
+        context.io.stderr("Cookies were collected but WeCom rejected them (got 401/403).\n" +
+            "Please complete the login in the browser, then rerun `wonder wecom cookie`.");
+        return {
+            exitCode: 1,
+            telemetry: { errorKind: "cookies_invalid_after_collect" },
+        };
+    }
+    context.io.stdout(`✅ Cookies saved to ${paths.cookiesPath}`);
+    return { exitCode: 0 };
+}
+// ---------------------------------------------------------------------------
+// wonder wecom status
+// ---------------------------------------------------------------------------
+async function runWecomStatus(_argv, context) {
+    const paths = resolveWonderPaths({ homeDir: context.homeDir });
+    const status = await getCookieStatus(paths.cookiesPath);
+    if (!status.exists) {
+        context.io.stderr("No WeCom cookies found.\n" +
+            "Run `wonder wecom cookie` to sign in.");
+        return { exitCode: 1 };
+    }
+    if (status.valid === null) {
+        context.io.stderr(`Cookie check encountered an error: ${status.error ?? "unknown"}`);
+        return {
+            exitCode: 1,
+            telemetry: { errorKind: "cookie_status_check_failed" },
+        };
+    }
+    if (!status.valid) {
+        context.io.stderr("WeCom cookies are expired or invalid.\n" +
+            "Run `wonder wecom cookie` to refresh.");
+        return { exitCode: 1 };
+    }
+    context.io.stdout(`✅ WeCom cookies are valid (${status.path})`);
+    return { exitCode: 0 };
+}
+// ---------------------------------------------------------------------------
+// wonder wecom set-cookie
+// ---------------------------------------------------------------------------
+async function runWecomSetCookie(argv, context) {
+    const paths = resolveWonderPaths({ homeDir: context.homeDir });
+    // Prefer argv[0]; fall back to stdin for pipe/heredoc scenarios.
+    let rawInput = argv[0] ?? null;
+    if (!rawInput) {
+        rawInput = await readStdin();
+    }
+    if (!rawInput?.trim()) {
+        context.io.stderr("Usage: wonder wecom set-cookie '<json or cookie-header-string>'\n" +
+            '  Example (JSON):   wonder wecom set-cookie \'{"TOK":"xxx","wedrive_sid":"yyy"}\'\n' +
+            "  Example (header): wonder wecom set-cookie 'TOK=xxx; wedrive_sid=yyy'");
+        return { exitCode: 1 };
+    }
+    const cookies = parseCookieInput(rawInput);
+    if (!cookies) {
+        context.io.stderr("Could not parse cookie input. Provide a valid JSON object or cookie header string.");
+        return { exitCode: 1 };
+    }
+    // Warn about missing key cookies (non-blocking).
+    const missingKeys = KEY_COOKIES.filter((k) => !(k in cookies));
+    if (missingKeys.length > 0) {
+        context.io.stderr(`⚠️  Warning: missing key cookies: ${missingKeys.join(", ")}`);
+    }
+    saveCookies(paths.cookiesPath, cookies);
+    const valid = await validateCookies(cookies);
+    if (!valid) {
+        context.io.stderr("⚠️  Cookies saved but WeCom returned 401/403 — they may be expired or incomplete.");
+        return { exitCode: 1, telemetry: { errorKind: "set_cookie_invalid" } };
+    }
+    context.io.stdout(`✅ Cookies saved and validated (${paths.cookiesPath})`);
+    return { exitCode: 0 };
+}
+// ---------------------------------------------------------------------------
+// Stdin helper
+// ---------------------------------------------------------------------------
+async function readStdin() {
+    if (process.stdin.isTTY)
+        return "";
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString("utf8").trim();
+}

package/dist/platform/npm.js

@@ -0,0 +1,14 @@
+// src/platform/npm.ts
+// NpmExecutor: injectable wrapper around `npm` CLI.
+// Replaces rover's BunExecutor. Used by update/uninstall commands.
+// spawnSync is synchronous and appropriate here — update/uninstall are
+// user-triggered, single-shot operations.
+import { spawnSync } from "child_process";
+export const defaultNpmExecutor = (args) => {
+    const result = spawnSync("npm", args, { encoding: "utf8" });
+    return {
+        exitCode: result.status ?? 1,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+    };
+};

package/dist/platform/paths.js

@@ -0,0 +1,25 @@
+// src/platform/paths.ts
+// Resolves all filesystem paths used by wonder at runtime.
+// __dirname equivalent uses import.meta.url (NodeNext ESM).
+import { fileURLToPath } from "url";
+import { dirname, resolve } from "path";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+export function resolveWonderPaths(opts) {
+    const homeDir = opts?.homeDir ??
+        process.env["HOME"] ??
+        process.env["USERPROFILE"] ??
+        "";
+    const wonderDir = resolve(homeDir, ".wonder");
+    // At runtime, __dirname = dist/ (tsc output). The manifest lives one level up.
+    const skillsManifestPath = resolve(__dirname, "../skills.manifest.json");
+    return {
+        homeDir,
+        wonderDir,
+        cookiesPath: resolve(wonderDir, "cookies.json"),
+        chromeProfilePath: resolve(wonderDir, "chrome-profile"),
+        cacheDir: resolve(wonderDir, "cache"),
+        skillsManifestPath,
+        defaultSaveDir: resolve(homeDir, "Downloads", "5mghost-wonder"),
+    };
+}

package/dist/telemetry/events.js

@@ -0,0 +1,42 @@
+// src/telemetry/events.ts
+// Helpers for building RecordCompletionInput from CommandResult + timing.
+import { sanitizeErrorMessage } from "@mkterswingman/5mghost-telemetry";
+/**
+ * Build the RecordCompletionInput to pass to telemetry.recordCompletion().
+ * Merges timing, exit-code-derived outcome, and any structured telemetry
+ * already attached to the CommandResult.
+ *
+ * Priority: result.telemetry.outcome > exitCode-derived outcome.
+ * Note: SDK uses "failure" not "error" for non-success outcomes.
+ */
+export function buildCompletionTelemetry(cmdInfo, result, durationMs) {
+    const baseOutcome = result.exitCode === 0 ? "success" : "failure";
+    const structured = result.telemetry ?? {};
+    // Map CommandResult.telemetry.outcome to SDK TelemetryOutcome.
+    const rawOutcome = structured.outcome;
+    const outcome = rawOutcome === "success" ? "success"
+        : rawOutcome === "failure" ? "failure"
+            : baseOutcome;
+    return {
+        toolName: cmdInfo.toolName,
+        durationMs,
+        outcome,
+        ...(structured.errorKind !== undefined
+            ? { errorKind: structured.errorKind }
+            : {}),
+        ...(structured.errorCode !== undefined
+            ? { errorCode: structured.errorCode }
+            : {}),
+        ...(structured.errorMessage !== undefined
+            ? { errorMessage: redactTelemetryErrorMessage(structured.errorMessage) }
+            : {}),
+    };
+}
+/**
+ * Sanitize an error message before it is included in a telemetry event.
+ * Delegates to the platform SDK's sanitizeErrorMessage which truncates and
+ * strips characters beyond MAX_ERROR_MESSAGE_CHARS.
+ */
+export function redactTelemetryErrorMessage(message) {
+    return sanitizeErrorMessage(message) ?? message;
+}

package/dist/telemetry/policy.js

@@ -0,0 +1,51 @@
+// src/telemetry/policy.ts
+// Maps raw CLI argv to telemetry toolName and classifies errors.
+//
+// toolName naming convention:
+//   "wecom cookie"     → "wecom_cookie"
+//   "wecom set-cookie" → "wecom_set_cookie"   (hyphen → underscore)
+//   "auth login"       → "auth_login"
+//   "read <url>"       → "read"               (URL arg is not a subcommand)
+//   "setup"            → "setup"
+//
+// SKIP_TELEMETRY: commands that must not generate events.
+// These argv[0] values produce no telemetry event.
+const SKIP_TELEMETRY = new Set(["--help", "-h", "--version", "-v"]);
+/**
+ * Resolve telemetry toolName from raw process.argv (already sliced to drop
+ * the node/bin prefix).  Returns null for commands that should not be tracked.
+ */
+export function resolveTelemetryCommand(argv) {
+    const [cmd, sub] = argv;
+    if (!cmd || SKIP_TELEMETRY.has(cmd))
+        return null;
+    // Sub-help always skips — user is reading docs, not performing an action.
+    if (sub === "--help" || sub === "-h")
+        return null;
+    // Commands with meaningful named subcommands (not URL/path args).
+    if (cmd === "auth" || cmd === "wecom") {
+        if (!sub || sub.startsWith("-"))
+            return { toolName: cmd };
+        // Normalize hyphens: "set-cookie" → "set_cookie"
+        const safeSub = sub.replace(/-/g, "_");
+        return { toolName: `${cmd}_${safeSub}` };
+    }
+    // All other commands: argv[1] may be a URL, flag, or absent —
+    // use only argv[0] as toolName.
+    return { toolName: cmd };
+}
+/**
+ * Classify an unhandled top-level CLI error into telemetry metadata.
+ * Phase 1: all unhandled errors → "internal" / "UNHANDLED_CLI_ERROR".
+ * P1-07 and later phases extend this with WeCom export error types.
+ */
+export function classifyUnhandledCliError(toolName, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+        toolName,
+        outcome: "failure",
+        errorKind: "internal",
+        errorCode: "UNHANDLED_CLI_ERROR",
+        errorMessage: message,
+    };
+}

package/dist/telemetry/runtime.js

@@ -0,0 +1,31 @@
+// src/telemetry/runtime.ts
+// Factory for the wonder telemetry runtime.
+// Returns null on any construction error — telemetry must never crash the CLI.
+import { DEFAULT_AUTH_URL, TokenManager } from "@mkterswingman/5mghost-auth";
+import { TelemetryRuntime, TelemetrySender } from "@mkterswingman/5mghost-telemetry";
+import packageJson from "../../package.json" with { type: "json" };
+export function createWonderTelemetryRuntime(options = {}) {
+    try {
+        const env = options.env ?? process.env;
+        const authUrl = options.authUrl ??
+            env["MKTERSWINGMAN_AUTH_URL"] ??
+            DEFAULT_AUTH_URL;
+        const ingestUrl = options.ingestUrl ??
+            env["MKTERSWINGMAN_TELEMETRY_INGEST_URL"] ??
+            `${authUrl.replace(/\/$/, "")}/telemetry/events`;
+        const tokenManager = new TokenManager({
+            authUrl,
+            homeDir: options.homeDir,
+        });
+        return new TelemetryRuntime({
+            product: "5mghost-wonder",
+            productVersion: packageJson.version,
+            homeDir: options.homeDir,
+            sender: new TelemetrySender(tokenManager, ingestUrl),
+        });
+    }
+    catch {
+        // Construction failure must never propagate to the CLI.
+        return null;
+    }
+}