Add platform-independent core module + desktop port adapters + WeChat migration guide

Author: Copilot

src/core/index.ts

@@ -0,0 +1,35 @@
+/**
+ * `core` — the platform-independent heart of EchoWise.
+ *
+ * Everything re-exported here is pure TypeScript with no dependency on Tauri,
+ * the DOM, `fetch`, `MediaRecorder`, or any other host-specific API. It can be
+ * consumed unchanged by the desktop app (Tauri) and by a future WeChat
+ * mini-program built with Taro.
+ *
+ * Platform-specific behaviour (persistence, audio capture/playback, network
+ * transport) is expressed through the interfaces in `./ports` and implemented
+ * per-platform under `src/platform/*`.
+ */
+
+/* ---------- domain types ---------- */
+export * from "../types";
+
+/* ---------- pure business logic ---------- */
+export * from "../scoring";
+export * from "../companions";
+export * from "../appearance";
+
+/* ---------- AI coaching pipeline (transport-agnostic) ----------
+ * These functions take an `LLMProvider` and only build prompts / parse JSON —
+ * the actual HTTP transport is a platform concern (see ports + adapters).
+ */
+export {
+  companionTurn,
+  reviewSentence,
+  summarizeSession,
+  ttsInstructions,
+} from "../providers";
+export type { ASRProvider, LLMProvider, TTSProvider } from "../providers";
+
+/* ---------- platform port contracts ---------- */
+export * from "./ports";

src/core/ports.ts

@@ -0,0 +1,116 @@
+/**
+ * Platform port interfaces.
+ *
+ * These describe every capability the app needs from the host platform. The
+ * desktop app (Tauri) and a future WeChat mini-program (Taro) each supply a
+ * concrete implementation, while the platform-independent `core` logic depends
+ * only on these interfaces. See `docs/wechat-miniprogram.md` for the full
+ * migration architecture.
+ *
+ * Adding this file changes no runtime behaviour: it is a pure type contract
+ * that the existing desktop modules already satisfy (see `src/platform/desktop`).
+ */
+import type {
+  AppearanceConfig,
+  Companion,
+  Conversation,
+  ConversationSummary,
+  DailyStat,
+  ProviderConfig,
+  Turn,
+  UserMemory,
+} from "../types";
+
+export type { ASRProvider, LLMProvider, TTSProvider } from "../providers";
+
+/**
+ * Structured persistence: companion, memory, settings, conversations, stats.
+ *
+ * Desktop: SQLite via `@tauri-apps/plugin-sql` (`src/db.ts`).
+ * WeChat:  cloud database or `wx.setStorage` (to be implemented in the Taro app).
+ */
+export interface DataStore {
+  loadCompanion(): Promise<Companion>;
+  saveCompanion(c: Companion): Promise<void>;
+
+  loadMemory(): Promise<UserMemory>;
+  saveMemory(m: UserMemory): Promise<void>;
+
+  loadConfig(): Promise<ProviderConfig>;
+  saveConfig(c: ProviderConfig): Promise<void>;
+
+  loadAppearance(): Promise<AppearanceConfig>;
+  saveAppearance(a: AppearanceConfig): Promise<void>;
+
+  insertConversation(c: Conversation): Promise<void>;
+  finalizeConversation(c: Conversation): Promise<void>;
+  attachSummary(id: string, summary: ConversationSummary): Promise<void>;
+
+  insertTurn(conversationId: string, t: Turn): Promise<void>;
+  updateTurn(id: string, patch: Partial<Turn>): Promise<void>;
+  loadConversations(limit?: number): Promise<Conversation[]>;
+
+  loadStats(days?: number): Promise<DailyStat[]>;
+  upsertStatOnEnd(dateISO: string, addedMinutes: number): Promise<void>;
+  updateStatScores(dateISO: string, confidence: number, listening: number): Promise<void>;
+}
+
+/**
+ * Binary media persistence: recorded/synthesised audio, avatars, backgrounds.
+ *
+ * Desktop: filesystem via `@tauri-apps/plugin-fs` (`src/storage.ts`).
+ * WeChat:  `wx.saveFile` / cloud storage (to be implemented in the Taro app).
+ */
+export interface MediaStore {
+  saveUserAudio(conversationId: string, turnId: string, blob: Blob): Promise<string>;
+  saveAssistantAudio(conversationId: string, turnId: string, blob: Blob): Promise<string>;
+  audioSrc(relPath: string): Promise<string>;
+  readAudioBlob(relPath: string): Promise<Blob>;
+
+  saveAvatarFile(file: File): Promise<string>;
+  avatarUploadSrc(uploadRef: string): Promise<string>;
+
+  saveBackgroundImage(file: File): Promise<string>;
+  backgroundSrc(ref: string): Promise<string | undefined>;
+}
+
+/** A handle to in-progress audio playback that can be stopped early. */
+export interface PlaybackHandle {
+  stop(): void;
+  onEnded(cb: () => void): void;
+}
+
+/**
+ * Microphone capture with a live 0..1 input level for the waveform UI.
+ *
+ * Desktop: `MediaRecorder` + `AudioContext` (`src/audio.ts` `Recorder`).
+ * WeChat:  `wx.getRecorderManager` + `onFrameRecorded` (Taro app).
+ */
+export interface AudioRecorder {
+  start(): Promise<void>;
+  /** Subscribe to live volume updates (0..1) while recording. */
+  onLevel(cb: (level: number) => void): void;
+  /** Stop recording and resolve with the captured audio. */
+  stop(): Promise<Blob>;
+  /** Stop recording and discard the audio. */
+  cancel(): void;
+  isRecording(): boolean;
+}
+
+/**
+ * Audio playback.
+ *
+ * Desktop: `HTMLAudioElement` (`src/audio.ts` `playBlob`).
+ * WeChat:  `wx.createInnerAudioContext` (Taro app).
+ */
+export interface AudioPlayer {
+  play(blob: Blob): Promise<PlaybackHandle>;
+}
+
+/** Everything the app needs from its host platform. */
+export interface Platform {
+  data: DataStore;
+  media: MediaStore;
+  createRecorder(): AudioRecorder;
+  createPlayer(): AudioPlayer;
+}

src/platform/desktop/index.ts

@@ -0,0 +1,99 @@
+/**
+ * Desktop (Tauri) implementation of the platform ports.
+ *
+ * These are thin adapters that delegate to the existing desktop modules
+ * (`src/db.ts`, `src/storage.ts`, `src/audio.ts`, `src/providers.ts`). They add
+ * no new behaviour — they simply prove that the ports in `core/ports.ts`
+ * accurately describe what the desktop app already does, and give the app (and
+ * a future Taro app) a single, swappable `Platform` object to depend on.
+ */
+import * as db from "../../db";
+import * as storage from "../../storage";
+import { Recorder, playBlob } from "../../audio";
+import { CompatASR, CompatLLM, CompatTTS } from "../../providers";
+import type { ProviderConfig } from "../../types";
+import type {
+  AudioPlayer,
+  AudioRecorder,
+  DataStore,
+  MediaStore,
+  Platform,
+  PlaybackHandle,
+} from "../../core/ports";
+
+/** SQLite-backed structured store. */
+export const desktopDataStore: DataStore = {
+  loadCompanion: db.loadCompanion,
+  saveCompanion: db.saveCompanion,
+  loadMemory: db.loadMemory,
+  saveMemory: db.saveMemory,
+  loadConfig: db.loadConfig,
+  saveConfig: db.saveConfig,
+  loadAppearance: db.loadAppearance,
+  saveAppearance: db.saveAppearance,
+  insertConversation: db.insertConversation,
+  finalizeConversation: db.finalizeConversation,
+  attachSummary: db.attachSummary,
+  insertTurn: db.insertTurn,
+  updateTurn: db.updateTurn,
+  loadConversations: db.loadConversations,
+  loadStats: db.loadStats,
+  upsertStatOnEnd: db.upsertStatOnEnd,
+  updateStatScores: db.updateStatScores,
+};
+
+/** Filesystem-backed media store. */
+export const desktopMediaStore: MediaStore = {
+  saveUserAudio: storage.saveUserAudio,
+  saveAssistantAudio: storage.saveAssistantAudio,
+  audioSrc: storage.audioSrc,
+  readAudioBlob: storage.readAudioBlob,
+  saveAvatarFile: storage.saveAvatarFile,
+  avatarUploadSrc: storage.avatarUploadSrc,
+  saveBackgroundImage: storage.saveBackgroundImage,
+  backgroundSrc: storage.backgroundSrc,
+};
+
+/** `MediaRecorder` + `AudioContext` recorder (matches `AudioRecorder`). */
+export function createDesktopRecorder(): AudioRecorder {
+  return new Recorder();
+}
+
+/** `HTMLAudioElement` playback wrapped as a platform-neutral `PlaybackHandle`. */
+export function createDesktopPlayer(): AudioPlayer {
+  return {
+    async play(blob: Blob): Promise<PlaybackHandle> {
+      const el = await playBlob(blob);
+      return {
+        stop() {
+          try {
+            el.pause();
+            el.currentTime = 0;
+          } catch {
+            /* ignore */
+          }
+        },
+        onEnded(cb: () => void) {
+          el.addEventListener("ended", cb);
+        },
+      };
+    },
+  };
+}
+
+/** AI transport (ASR / LLM / TTS) over `fetch`, bound to a provider config. */
+export function createDesktopNetwork(cfg: ProviderConfig) {
+  return {
+    asr: new CompatASR(cfg),
+    llm: new CompatLLM(cfg),
+    tts: new CompatTTS(cfg),
+  };
+}
+
+/** The complete desktop platform. */
+export const desktopPlatform: Platform = {
+  data: desktopDataStore,
+  media: desktopMediaStore,
+  createRecorder: createDesktopRecorder,
+  createPlayer: createDesktopPlayer,
+};

tests/core/index.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from "vitest";
+
+import * as core from "../../src/core";
+import * as types from "../../src/types";
+import * as scoring from "../../src/scoring";
+import * as companions from "../../src/companions";
+import * as appearance from "../../src/appearance";
+import {
+  companionTurn,
+  reviewSentence,
+  summarizeSession,
+  ttsInstructions,
+} from "../../src/providers";
+
+/**
+ * The `core` barrel must expose the platform-independent logic *by reference*
+ * (re-exports, not copies) so desktop and mini-program share one source of
+ * truth. It must NOT pull in any host-specific transport (e.g. the fetch-based
+ * Compat* classes stay in the platform layer).
+ */
+describe("core barrel", () => {
+  it("re-exports domain types/helpers by reference", () => {
+    expect(core.tierForDay).toBe(types.tierForDay);
+    expect(core.dayCount).toBe(types.dayCount);
+    expect(core.RELATIONSHIP_TIERS).toBe(types.RELATIONSHIP_TIERS);
+  });
+
+  it("re-exports pure business logic by reference", () => {
+    // scoring
+    for (const k of Object.keys(scoring) as (keyof typeof scoring)[]) {
+      expect((core as Record<string, unknown>)[k]).toBe(scoring[k]);
+    }
+    // companions
+    for (const k of Object.keys(companions) as (keyof typeof companions)[]) {
+      expect((core as Record<string, unknown>)[k]).toBe(companions[k]);
+    }
+    // appearance
+    for (const k of Object.keys(appearance) as (keyof typeof appearance)[]) {
+      expect((core as Record<string, unknown>)[k]).toBe(appearance[k]);
+    }
+  });
+
+  it("re-exports the transport-agnostic coaching pipeline", () => {
+    expect(core.companionTurn).toBe(companionTurn);
+    expect(core.reviewSentence).toBe(reviewSentence);
+    expect(core.summarizeSession).toBe(summarizeSession);
+    expect(core.ttsInstructions).toBe(ttsInstructions);
+  });
+
+  it("does not leak host-specific transport classes into core", () => {
+    expect((core as Record<string, unknown>).CompatASR).toBeUndefined();
+    expect((core as Record<string, unknown>).CompatLLM).toBeUndefined();
+    expect((core as Record<string, unknown>).CompatTTS).toBeUndefined();
+  });
+});