@symerian/symi 3.0.21 → 3.0.22

package/docs/refactor/plugin-sdk.md

@@ -1,214 +0,0 @@
----
-summary: "Plan: one clean plugin SDK + runtime for all messaging connectors"
-read_when:
-  - Defining or refactoring the plugin architecture
-  - Migrating channel connectors to the plugin SDK/runtime
-title: "Plugin SDK Refactor"
----
-
-# Plugin SDK + Runtime Refactor Plan
-
-Goal: every messaging connector is a plugin (bundled or external) using one stable API.
-No plugin imports from `src/**` directly. All dependencies go through the SDK or runtime.
-
-## Why now
-
-- Current connectors mix patterns: direct core imports, dist-only bridges, and custom helpers.
-- This makes upgrades brittle and blocks a clean external plugin surface.
-
-## Target architecture (two layers)
-
-### 1) Plugin SDK (compile-time, stable, publishable)
-
-Scope: types, helpers, and config utilities. No runtime state, no side effects.
-
-Contents (examples):
-
-- Types: `ChannelPlugin`, adapters, `ChannelMeta`, `ChannelCapabilities`, `ChannelDirectoryEntry`.
-- Config helpers: `buildChannelConfigSchema`, `setAccountEnabledInConfigSection`, `deleteAccountFromConfigSection`,
-  `applyAccountNameToChannelSection`.
-- Pairing helpers: `PAIRING_APPROVED_MESSAGE`, `formatPairingApproveHint`.
-- Onboarding helpers: `promptChannelAccessConfig`, `addWildcardAllowFrom`, onboarding types.
-- Tool param helpers: `createActionGate`, `readStringParam`, `readNumberParam`, `readReactionParams`, `jsonResult`.
-- Docs link helper: `formatDocsLink`.
-
-Delivery:
-
-- Publish as `symi/plugin-sdk` (or export from core under `symi/plugin-sdk`).
-- Semver with explicit stability guarantees.
-
-### 2) Plugin Runtime (execution surface, injected)
-
-Scope: everything that touches core runtime behavior.
-Accessed via `SymiPluginApi.runtime` so plugins never import `src/**`.
-
-Proposed surface (minimal but complete):
-
-```ts
-export type PluginRuntime = {
-  channel: {
-    text: {
-      chunkMarkdownText(text: string, limit: number): string[];
-      resolveTextChunkLimit(cfg: SymiConfig, channel: string, accountId?: string): number;
-      hasControlCommand(text: string, cfg: SymiConfig): boolean;
-    };
-    reply: {
-      dispatchReplyWithBufferedBlockDispatcher(params: {
-        ctx: unknown;
-        cfg: unknown;
-        dispatcherOptions: {
-          deliver: (payload: {
-            text?: string;
-            mediaUrls?: string[];
-            mediaUrl?: string;
-          }) => void | Promise<void>;
-          onError?: (err: unknown, info: { kind: string }) => void;
-        };
-      }): Promise<void>;
-      createReplyDispatcherWithTyping?: unknown; // adapter for Teams-style flows
-    };
-    routing: {
-      resolveAgentRoute(params: {
-        cfg: unknown;
-        channel: string;
-        accountId: string;
-        peer: { kind: RoutePeerKind; id: string };
-      }): { sessionKey: string; accountId: string };
-    };
-    pairing: {
-      buildPairingReply(params: { channel: string; idLine: string; code: string }): string;
-      readAllowFromStore(channel: string): Promise<string[]>;
-      upsertPairingRequest(params: {
-        channel: string;
-        id: string;
-        meta?: { name?: string };
-      }): Promise<{ code: string; created: boolean }>;
-    };
-    media: {
-      fetchRemoteMedia(params: { url: string }): Promise<{ buffer: Buffer; contentType?: string }>;
-      saveMediaBuffer(
-        buffer: Uint8Array,
-        contentType: string | undefined,
-        direction: "inbound" | "outbound",
-        maxBytes: number,
-      ): Promise<{ path: string; contentType?: string }>;
-    };
-    mentions: {
-      buildMentionRegexes(cfg: SymiConfig, agentId?: string): RegExp[];
-      matchesMentionPatterns(text: string, regexes: RegExp[]): boolean;
-    };
-    groups: {
-      resolveGroupPolicy(
-        cfg: SymiConfig,
-        channel: string,
-        accountId: string,
-        groupId: string,
-      ): {
-        allowlistEnabled: boolean;
-        allowed: boolean;
-        groupConfig?: unknown;
-        defaultConfig?: unknown;
-      };
-      resolveRequireMention(
-        cfg: SymiConfig,
-        channel: string,
-        accountId: string,
-        groupId: string,
-        override?: boolean,
-      ): boolean;
-    };
-    debounce: {
-      createInboundDebouncer<T>(opts: {
-        debounceMs: number;
-        buildKey: (v: T) => string | null;
-        shouldDebounce: (v: T) => boolean;
-        onFlush: (entries: T[]) => Promise<void>;
-        onError?: (err: unknown) => void;
-      }): { push: (v: T) => void; flush: () => Promise<void> };
-      resolveInboundDebounceMs(cfg: SymiConfig, channel: string): number;
-    };
-    commands: {
-      resolveCommandAuthorizedFromAuthorizers(params: {
-        useAccessGroups: boolean;
-        authorizers: Array<{ configured: boolean; allowed: boolean }>;
-      }): boolean;
-    };
-  };
-  logging: {
-    shouldLogVerbose(): boolean;
-    getChildLogger(name: string): PluginLogger;
-  };
-  state: {
-    resolveStateDir(cfg: SymiConfig): string;
-  };
-};
-```
-
-Notes:
-
-- Runtime is the only way to access core behavior.
-- SDK is intentionally small and stable.
-- Each runtime method maps to an existing core implementation (no duplication).
-
-## Migration plan (phased, safe)
-
-### Phase 0: scaffolding
-
-- Introduce `symi/plugin-sdk`.
-- Add `api.runtime` to `SymiPluginApi` with the surface above.
-- Maintain existing imports during a transition window (deprecation warnings).
-
-### Phase 1: bridge cleanup (low risk)
-
-- Replace per-extension `core-bridge.ts` with `api.runtime`.
-- Migrate BlueBubbles, Zalo, Zalo Personal first (already close).
-- Remove duplicated bridge code.
-
-### Phase 2: light direct-import plugins
-
-- Migrate Matrix to SDK + runtime.
-- Validate onboarding, directory, group mention logic.
-
-### Phase 3: heavy direct-import plugins
-
-- Migrate MS Teams (largest set of runtime helpers).
-- Ensure reply/typing semantics match current behavior.
-
-### Phase 4: iMessage pluginization
-
-- Move iMessage into `extensions/imessage`.
-- Replace direct core calls with `api.runtime`.
-- Keep config keys, CLI behavior, and docs intact.
-
-### Phase 5: enforcement
-
-- Add lint rule / CI check: no `extensions/**` imports from `src/**`.
-- Add plugin SDK/version compatibility checks (runtime + SDK semver).
-
-## Compatibility and versioning
-
-- SDK: semver, published, documented changes.
-- Runtime: versioned per core release. Add `api.runtime.version`.
-- Plugins declare a required runtime range (e.g., `symiRuntime: ">=2026.2.0"`).
-
-## Testing strategy
-
-- Adapter-level unit tests (runtime functions exercised with real core implementation).
-- Golden tests per plugin: ensure no behavior drift (routing, pairing, allowlist, mention gating).
-- A single end-to-end plugin sample used in CI (install + run + smoke).
-
-## Open questions
-
-- Where to host SDK types: separate package or core export?
-- Runtime type distribution: in SDK (types only) or in core?
-- How to expose docs links for bundled vs external plugins?
-- Do we allow limited direct core imports for in-repo plugins during transition?
-
-## Success criteria
-
-- All channel connectors are plugins using SDK + runtime.
-- No `extensions/**` imports from `src/**`.
-- New connector templates depend only on SDK + runtime.
-- External plugins can be developed and updated without core source access.
-
-Related docs: [Plugins](/tools/plugin), [Channels](/channels/index), [Configuration](/gateway/configuration).

package/docs/refactor/strict-config.md

@@ -1,93 +0,0 @@
----
-summary: "Strict config validation + doctor-only migrations"
-read_when:
-  - Designing or implementing config validation behavior
-  - Working on config migrations or doctor workflows
-  - Handling plugin config schemas or plugin load gating
-title: "Strict Config Validation"
----
-
-# Strict config validation (doctor-only migrations)
-
-## Goals
-
-- **Reject unknown config keys everywhere** (root + nested), except root `$schema` metadata.
-- **Reject plugin config without a schema**; don’t load that plugin.
-- **Remove legacy auto-migration on load**; migrations run via doctor only.
-- **Auto-run doctor (dry-run) on startup**; if invalid, block non-diagnostic commands.
-
-## Non-goals
-
-- Backward compatibility on load (legacy keys do not auto-migrate).
-- Silent drops of unrecognized keys.
-
-## Strict validation rules
-
-- Config must match the schema exactly at every level.
-- Unknown keys are validation errors (no passthrough at root or nested), except root `$schema` when it is a string.
-- `plugins.entries.<id>.config` must be validated by the plugin’s schema.
-  - If a plugin lacks a schema, **reject plugin load** and surface a clear error.
-- Unknown `channels.<id>` keys are errors unless a plugin manifest declares the channel id.
-- Plugin manifests (`symi.plugin.json`) are required for all plugins.
-
-## Plugin schema enforcement
-
-- Each plugin provides a strict JSON Schema for its config (inline in the manifest).
-- Plugin load flow:
-  1. Resolve plugin manifest + schema (`symi.plugin.json`).
-  2. Validate config against the schema.
-  3. If missing schema or invalid config: block plugin load, record error.
-- Error message includes:
-  - Plugin id
-  - Reason (missing schema / invalid config)
-  - Path(s) that failed validation
-- Disabled plugins keep their config, but Doctor + logs surface a warning.
-
-## Doctor flow
-
-- Doctor runs **every time** config is loaded (dry-run by default).
-- If config invalid:
-  - Print a summary + actionable errors.
-  - Instruct: `symi doctor --fix`.
-- `symi doctor --fix`:
-  - Applies migrations.
-  - Removes unknown keys.
-  - Writes updated config.
-
-## Command gating (when config is invalid)
-
-Allowed (diagnostic-only):
-
-- `symi doctor`
-- `symi logs`
-- `symi health`
-- `symi help`
-- `symi status`
-- `symi gateway status`
-
-Everything else must hard-fail with: “Config invalid. Run `symi doctor --fix`.”
-
-## Error UX format
-
-- Single summary header.
-- Grouped sections:
-  - Unknown keys (full paths)
-  - Legacy keys / migrations needed
-  - Plugin load failures (plugin id + reason + path)
-
-## Implementation touchpoints
-
-- `src/config/zod-schema.ts`: remove root passthrough; strict objects everywhere.
-- `src/config/zod-schema.providers.ts`: ensure strict channel schemas.
-- `src/config/validation.ts`: fail on unknown keys; do not apply legacy migrations.
-- `src/config/io.ts`: remove legacy auto-migrations; always run doctor dry-run.
-- `src/config/legacy*.ts`: move usage to doctor only.
-- `src/plugins/*`: add schema registry + gating.
-- CLI command gating in `src/cli`.
-
-## Tests
-
-- Unknown key rejection (root + nested).
-- Plugin missing schema → plugin load blocked with clear error.
-- Invalid config → gateway startup blocked except diagnostic commands.
-- Doctor dry-run auto; `doctor --fix` writes corrected config.