@invago/mixin 1.0.8 → 1.0.9

package/src/reply-format.ts

@@ -13,6 +13,10 @@ export type MixinReplyPlan =
   | { kind: "buttons"; intro?: string; buttons: MixinButton[] }
   | { kind: "card"; card: MixinCard };
 
+export type MixinReplyPlanResolution =
+  | { matchedTemplate: false; plan: MixinReplyPlan | null }
+  | { matchedTemplate: true; plan: MixinReplyPlan | null; error?: string };
+
 const MAX_BUTTONS = 6;
 const MAX_BUTTON_LABEL = 36;
 const MAX_CARD_TITLE = 36;
@@ -166,40 +170,40 @@ function parseAudioTemplate(body: string): MixinReplyPlan | null {
   };
 }
 
-function parseExplicitTemplate(text: string): MixinReplyPlan | null {
+function parseExplicitTemplate(text: string): MixinReplyPlanResolution {
   const match = text.match(TEMPLATE_REGEX);
   if (!match) {
-    return null;
+    return { matchedTemplate: false, plan: null };
   }
 
   const templateType = (match[1] ?? "").toLowerCase();
   const body = match[2] ?? "";
 
   if (templateType === "text") {
-    return parseTextTemplate(body);
+    return { matchedTemplate: true, plan: parseTextTemplate(body), error: "Invalid mixin-text template body" };
   }
 
   if (templateType === "post") {
-    return parsePostTemplate(body);
+    return { matchedTemplate: true, plan: parsePostTemplate(body), error: "Invalid mixin-post template body" };
   }
 
   if (templateType === "buttons") {
-    return parseButtonsTemplate(body);
+    return { matchedTemplate: true, plan: parseButtonsTemplate(body), error: "Invalid mixin-buttons template JSON" };
   }
 
   if (templateType === "card") {
-    return parseCardTemplate(body);
+    return { matchedTemplate: true, plan: parseCardTemplate(body), error: "Invalid mixin-card template JSON" };
   }
 
   if (templateType === "file") {
-    return parseFileTemplate(body);
+    return { matchedTemplate: true, plan: parseFileTemplate(body), error: "Invalid mixin-file template JSON" };
   }
 
   if (templateType === "audio") {
-    return parseAudioTemplate(body);
+    return { matchedTemplate: true, plan: parseAudioTemplate(body), error: "Invalid mixin-audio template JSON" };
   }
 
-  return null;
+  return { matchedTemplate: true, plan: null, error: "Unknown Mixin template type" };
 }
 
 function toPlainText(text: string): string {
@@ -288,21 +292,21 @@ function isLongStructuredText(text: string): boolean {
   );
 }
 
-export function buildMixinReplyPlan(text: string): MixinReplyPlan | null {
+export function resolveMixinReplyPlan(text: string): MixinReplyPlanResolution {
   const normalized = normalizeWhitespace(text);
   if (!normalized) {
-    return null;
+    return { matchedTemplate: false, plan: null };
   }
 
   const explicit = parseExplicitTemplate(normalized);
-  if (explicit) {
+  if (explicit.matchedTemplate) {
     return explicit;
   }
 
   const links = extractLinks(normalized);
 
   if (isLongStructuredText(normalized)) {
-    return { kind: "post", text: normalized };
+    return { matchedTemplate: false, plan: { kind: "post", text: normalized } };
   }
 
   if (links.length >= 2 && links.length <= MAX_BUTTONS) {
@@ -310,9 +314,12 @@ export function buildMixinReplyPlan(text: string): MixinReplyPlan | null {
       normalized.replace(/\[([^\]]+)\]\((https?:\/\/[^)\s]+)\)/g, "").replace(/https?:\/\/[^\s)]+/g, ""),
     );
     return {
-      kind: "buttons",
-      intro: intro || undefined,
-      buttons: buildButtons(links),
+      matchedTemplate: false,
+      plan: {
+        kind: "buttons",
+        intro: intro || undefined,
+        buttons: buildButtons(links),
+      },
     };
   }
 
@@ -320,15 +327,22 @@ export function buildMixinReplyPlan(text: string): MixinReplyPlan | null {
     const title = detectTitle(normalized, links[0].label);
     const description = detectCardDescription(normalized, title) || truncate(links[0].url, MAX_CARD_DESCRIPTION);
     return {
-      kind: "card",
-      card: {
-        title,
-        description,
-        action: links[0].url,
-        shareable: true,
+      matchedTemplate: false,
+      plan: {
+        kind: "card",
+        card: {
+          title,
+          description,
+          action: links[0].url,
+          shareable: true,
+        },
       },
     };
   }
 
-  return { kind: "text", text: toPlainText(normalized) };
+  return { matchedTemplate: false, plan: { kind: "text", text: toPlainText(normalized) } };
+}
+
+export function buildMixinReplyPlan(text: string): MixinReplyPlan | null {
+  return resolveMixinReplyPlan(text).plan;
 }

package/src/send-service.ts

@@ -230,6 +230,17 @@ function resolveOutboxPaths(): {
   };
 }
 
+export function getOutboxPathsSnapshot(): {
+  outboxDir: string;
+  outboxFile: string;
+} {
+  const { outboxDir, outboxFile } = resolveOutboxPaths();
+  return {
+    outboxDir,
+    outboxFile,
+  };
+}
+
 function normalizeErrorMessage(message: string): string {
   if (message.length <= MAX_ERROR_LENGTH) {
     return message;

package/src/status.ts

@@ -0,0 +1,100 @@
+import { buildBaseAccountStatusSnapshot, buildBaseChannelStatusSummary } from "openclaw/plugin-sdk";
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import { getAccountConfig, resolveDefaultAccountId } from "./config.js";
+import { getOutboxPathsSnapshot, type OutboxStatus } from "./send-service.js";
+
+type RuntimeLifecycleSnapshot = {
+  running?: boolean | null;
+  lastStartAt?: number | null;
+  lastStopAt?: number | null;
+  lastError?: string | null;
+  lastInboundAt?: number | null;
+  lastOutboundAt?: number | null;
+};
+
+type MixinChannelStatusSnapshot = {
+  configured?: boolean | null;
+  running?: boolean | null;
+  lastStartAt?: number | null;
+  lastStopAt?: number | null;
+  lastError?: string | null;
+  defaultAccountId?: string | null;
+  outboxDir?: string | null;
+  outboxFile?: string | null;
+  outboxPending?: number | null;
+  mediaMaxMb?: number | null;
+};
+
+type MixinStatusAccount = {
+  accountId: string;
+  name?: string;
+  enabled?: boolean;
+  configured?: boolean;
+  config: {
+    requireMentionInGroup?: boolean;
+    mediaBypassMentionInGroup?: boolean;
+    mediaMaxMb?: number;
+    audioAutoDetectDuration?: boolean;
+    audioSendAsVoiceByDefault?: boolean;
+    audioRequireFfprobe?: boolean;
+  };
+};
+
+export function resolveMixinStatusSnapshot(
+  cfg: OpenClawConfig,
+  accountId?: string,
+  outboxStatus?: OutboxStatus | null,
+): {
+  defaultAccountId: string;
+  outboxDir: string;
+  outboxFile: string;
+  outboxPending: number;
+  mediaMaxMb: number | null;
+} {
+  const defaultAccountId = resolveDefaultAccountId(cfg);
+  const resolvedAccountId = accountId ?? defaultAccountId;
+  const accountConfig = getAccountConfig(cfg, resolvedAccountId);
+  const { outboxDir, outboxFile } = getOutboxPathsSnapshot();
+  return {
+    defaultAccountId,
+    outboxDir,
+    outboxFile,
+    outboxPending: outboxStatus?.totalPending ?? 0,
+    mediaMaxMb: accountConfig.mediaMaxMb ?? null,
+  };
+}
+
+export function buildMixinChannelSummary(params: {
+  snapshot: MixinChannelStatusSnapshot;
+}) {
+  const { snapshot } = params;
+  return {
+    ...buildBaseChannelStatusSummary(snapshot),
+    defaultAccountId: snapshot.defaultAccountId ?? null,
+    outboxDir: snapshot.outboxDir ?? null,
+    outboxFile: snapshot.outboxFile ?? null,
+    outboxPending: snapshot.outboxPending ?? 0,
+    mediaMaxMb: snapshot.mediaMaxMb ?? null,
+  };
+}
+
+export function buildMixinAccountSnapshot(params: {
+  account: MixinStatusAccount;
+  runtime?: RuntimeLifecycleSnapshot | null;
+  probe?: unknown;
+  defaultAccountId?: string | null;
+  outboxPending?: number | null;
+}) {
+  const { account, runtime, probe, defaultAccountId, outboxPending } = params;
+  return {
+    ...buildBaseAccountStatusSnapshot({ account, runtime, probe }),
+    defaultAccountId: defaultAccountId ?? null,
+    outboxPending: outboxPending ?? 0,
+    requireMentionInGroup: account.config.requireMentionInGroup ?? true,
+    mediaBypassMentionInGroup: account.config.mediaBypassMentionInGroup ?? true,
+    mediaMaxMb: account.config.mediaMaxMb ?? null,
+    audioAutoDetectDuration: account.config.audioAutoDetectDuration ?? true,
+    audioSendAsVoiceByDefault: account.config.audioSendAsVoiceByDefault ?? true,
+    audioRequireFfprobe: account.config.audioRequireFfprobe ?? false,
+  };
+}

package/tools/mixin-plugin-onboard/README.md

@@ -0,0 +1,98 @@
+# Mixin Plugin Onboarding CLI
+
+This CLI is bundled inside [`@invago/mixin`](https://www.npmjs.com/package/@invago/mixin). It helps inspect local OpenClaw installation state, verify key paths, and automate plugin install or update commands.
+
+## Commands
+
+### `info`
+
+Prints the current local OpenClaw and Mixin plugin context:
+
+- OpenClaw home, state, and extensions directories
+- detected `openclaw.json` path
+- detected Mixin plugin directories
+- whether the plugin looks enabled in config
+- current outbox path
+- whether `ffprobe` is available
+
+Run:
+
+```bash
+npx -y @invago/mixin info
+```
+
+### `doctor`
+
+Runs a basic local diagnosis and returns a non-zero exit code when required checks fail.
+
+Current checks:
+
+- config file found
+- `channels.mixin` present
+- plugin enabled in config
+- plugin installed in extensions
+- outbox directory writable
+- `ffprobe` available
+
+It also reports leftover `.openclaw-install-stage-*` directories if any are detected.
+
+Run:
+
+```bash
+npx -y @invago/mixin doctor
+```
+
+### `install`
+
+Runs:
+
+```bash
+openclaw plugins install @invago/mixin
+```
+
+You can also pass a custom npm spec:
+
+```bash
+npx -y @invago/mixin install @invago/mixin@latest
+```
+
+### `update`
+
+Runs:
+
+```bash
+openclaw plugins install @invago/mixin@latest
+```
+
+Run:
+
+```bash
+npx -y @invago/mixin update
+```
+
+## Local Development
+
+From this repository:
+
+```bash
+node --import jiti/register.js tools/mixin-plugin-onboard/src/index.ts info
+node --import jiti/register.js tools/mixin-plugin-onboard/src/index.ts doctor
+```
+
+Or from the tool directory:
+
+```bash
+cd tools/mixin-plugin-onboard
+npm run info
+npm run doctor
+```
+
+## Publish
+
+This CLI is published together with the main `@invago/mixin` package from the repository root.
+
+## Notes
+
+- This CLI is intentionally read-mostly right now.
+- `install` and `update` delegate to the local `openclaw` command.
+- `doctor` currently treats missing `ffprobe` as a failed check because native outbound audio-as-voice depends on it.

package/tools/mixin-plugin-onboard/bin/mixin-plugin-onboard.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import "jiti/register.js";
+await import("../src/index.ts");

package/tools/mixin-plugin-onboard/src/commands/doctor.ts

@@ -0,0 +1,28 @@
+import { buildContext, checkWritableDir, findMixinPluginDirs, isPluginEnabled, readMixinConfig, runFfprobeCheck } from "../utils.ts";
+
+export async function runDoctor(): Promise<number> {
+  const ctx = await buildContext();
+  const pluginDirs = await findMixinPluginDirs(ctx.extensionsDir);
+  const mixinConfig = readMixinConfig(ctx.config);
+  const checks = [
+    { label: "config_found", ok: Boolean(ctx.configPath) },
+    { label: "mixin_config_present", ok: Boolean(mixinConfig) },
+    { label: "plugin_enabled", ok: isPluginEnabled(ctx.config) },
+    { label: "plugin_installed", ok: pluginDirs.length > 0 },
+    { label: "outbox_writable", ok: await checkWritableDir(ctx.outboxDir) },
+    { label: "ffprobe_available", ok: runFfprobeCheck() },
+  ];
+
+  const stageDirs = pluginDirs.filter((dir) => dir.includes(".openclaw-install-stage-"));
+  console.log(JSON.stringify({
+    ok: checks.every((item) => item.ok),
+    checks,
+    stageDirs,
+    pluginDirs,
+    configPath: ctx.configPath,
+    outboxDir: ctx.outboxDir,
+    outboxFile: ctx.outboxFile,
+  }, null, 2));
+
+  return checks.every((item) => item.ok) ? 0 : 1;
+}

package/tools/mixin-plugin-onboard/src/commands/info.ts

@@ -0,0 +1,23 @@
+import { buildContext, findMixinPluginDirs, isPluginEnabled, readMixinConfig, runFfprobeCheck } from "../utils.ts";
+
+export async function runInfo(): Promise<number> {
+  const ctx = await buildContext();
+  const pluginDirs = await findMixinPluginDirs(ctx.extensionsDir);
+  const mixinConfig = readMixinConfig(ctx.config);
+
+  console.log(JSON.stringify({
+    homeDir: ctx.homeDir,
+    stateDir: ctx.stateDir,
+    extensionsDir: ctx.extensionsDir,
+    configPath: ctx.configPath,
+    pluginDirs,
+    pluginEnabled: isPluginEnabled(ctx.config),
+    mixinConfigured: Boolean(mixinConfig),
+    defaultAccount: typeof mixinConfig?.defaultAccount === "string" ? mixinConfig.defaultAccount : "default",
+    outboxDir: ctx.outboxDir,
+    outboxFile: ctx.outboxFile,
+    ffprobeAvailable: runFfprobeCheck(),
+  }, null, 2));
+
+  return 0;
+}

package/tools/mixin-plugin-onboard/src/commands/install.ts

@@ -0,0 +1,5 @@
+import { runOpenClawInstall } from "../utils.ts";
+
+export async function runInstall(spec?: string): Promise<number> {
+  return runOpenClawInstall(spec?.trim() || "@invago/mixin");
+}

package/tools/mixin-plugin-onboard/src/commands/update.ts

@@ -0,0 +1,5 @@
+import { runOpenClawInstall } from "../utils.ts";
+
+export async function runUpdate(spec?: string): Promise<number> {
+  return runOpenClawInstall(spec?.trim() || "@invago/mixin@latest");
+}

package/tools/mixin-plugin-onboard/src/index.ts

@@ -0,0 +1,49 @@
+import { runDoctor } from "./commands/doctor.ts";
+import { runInfo } from "./commands/info.ts";
+import { runInstall } from "./commands/install.ts";
+import { runUpdate } from "./commands/update.ts";
+
+function printUsage(): void {
+  console.log(`mixin-plugin-onboard <command>
+
+Commands:
+  info
+  doctor
+  install [npm-spec]
+  update [npm-spec]
+`);
+}
+
+async function main(): Promise<void> {
+  const [, , command, arg] = process.argv;
+  if (!command || command === "help" || command === "--help" || command === "-h") {
+    printUsage();
+    process.exitCode = 0;
+    return;
+  }
+
+  if (command === "info") {
+    process.exitCode = await runInfo();
+    return;
+  }
+
+  if (command === "doctor") {
+    process.exitCode = await runDoctor();
+    return;
+  }
+
+  if (command === "install") {
+    process.exitCode = await runInstall(arg);
+    return;
+  }
+
+  if (command === "update") {
+    process.exitCode = await runUpdate(arg);
+    return;
+  }
+
+  printUsage();
+  process.exitCode = 1;
+}
+
+await main();

package/tools/mixin-plugin-onboard/src/utils.ts

@@ -0,0 +1,189 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+export type OpenClawContext = {
+  homeDir: string;
+  stateDir: string;
+  extensionsDir: string;
+  configPath: string | null;
+  config: Record<string, unknown> | null;
+  outboxDir: string;
+  outboxFile: string;
+};
+
+export function resolveHomeDir(env: NodeJS.ProcessEnv = process.env): string {
+  const configured = env.OPENCLAW_HOME?.trim();
+  if (configured) {
+    return configured;
+  }
+  return path.join(os.homedir(), ".openclaw");
+}
+
+export function resolveStateDir(env: NodeJS.ProcessEnv = process.env): string {
+  const configured = env.OPENCLAW_STATE_DIR?.trim() || env.CLAWDBOT_STATE_DIR?.trim();
+  if (configured) {
+    return configured;
+  }
+  return path.join(resolveHomeDir(env), "state");
+}
+
+export function resolveExtensionsDir(env: NodeJS.ProcessEnv = process.env): string {
+  return path.join(resolveHomeDir(env), "extensions");
+}
+
+export function resolveOutboxPaths(env: NodeJS.ProcessEnv = process.env): {
+  outboxDir: string;
+  outboxFile: string;
+} {
+  const outboxDir = path.join(resolveStateDir(env), "mixin");
+  return {
+    outboxDir,
+    outboxFile: path.join(outboxDir, "mixin-outbox.json"),
+  };
+}
+
+export async function readConfig(env: NodeJS.ProcessEnv = process.env): Promise<{
+  path: string | null;
+  config: Record<string, unknown> | null;
+}> {
+  const explicit = env.OPENCLAW_CONFIG?.trim();
+  const candidates = [
+    explicit,
+    path.join(resolveHomeDir(env), "openclaw.json"),
+    path.join(process.cwd(), "openclaw.json"),
+  ].filter((value): value is string => Boolean(value));
+
+  for (const candidate of candidates) {
+    try {
+      const raw = await fs.readFile(candidate, "utf8");
+      return {
+        path: candidate,
+        config: parseLooseConfig(raw),
+      };
+    } catch {
+      continue;
+    }
+  }
+
+  return {
+    path: null,
+    config: null,
+  };
+}
+
+function parseLooseConfig(raw: string): Record<string, unknown> {
+  try {
+    return JSON.parse(raw) as Record<string, unknown>;
+  } catch {
+    const relaxed = raw
+      .replace(/^\uFEFF/, "")
+      .replace(/\/\*[\s\S]*?\*\//g, "")
+      .replace(/^\s*\/\/.*$/gm, "")
+      .replace(/,\s*([}\]])/g, "$1");
+    return JSON.parse(relaxed) as Record<string, unknown>;
+  }
+}
+
+export async function buildContext(env: NodeJS.ProcessEnv = process.env): Promise<OpenClawContext> {
+  const config = await readConfig(env);
+  const outbox = resolveOutboxPaths(env);
+  return {
+    homeDir: resolveHomeDir(env),
+    stateDir: resolveStateDir(env),
+    extensionsDir: resolveExtensionsDir(env),
+    configPath: config.path,
+    config: config.config,
+    outboxDir: outbox.outboxDir,
+    outboxFile: outbox.outboxFile,
+  };
+}
+
+export async function findMixinPluginDirs(extensionsDir: string): Promise<string[]> {
+  try {
+    const entries = await fs.readdir(extensionsDir, { withFileTypes: true });
+    const matched: string[] = [];
+    for (const entry of entries) {
+      if (!entry.isDirectory()) {
+        continue;
+      }
+      const dirPath = path.join(extensionsDir, entry.name);
+      const openclawPluginPath = path.join(dirPath, "openclaw.plugin.json");
+      const packageJsonPath = path.join(dirPath, "package.json");
+      try {
+        const pluginRaw = await fs.readFile(openclawPluginPath, "utf8");
+        if (pluginRaw.includes("\"mixin\"")) {
+          matched.push(dirPath);
+          continue;
+        }
+      } catch {
+      }
+      try {
+        const packageRaw = await fs.readFile(packageJsonPath, "utf8");
+        if (packageRaw.includes("\"@invago/mixin\"") || packageRaw.includes("\"id\":\"mixin\"")) {
+          matched.push(dirPath);
+        }
+      } catch {
+      }
+    }
+    return matched;
+  } catch {
+    return [];
+  }
+}
+
+export async function checkWritableDir(dirPath: string): Promise<boolean> {
+  try {
+    await fs.mkdir(dirPath, { recursive: true });
+    const testPath = path.join(dirPath, `.write-test-${Date.now()}`);
+    await fs.writeFile(testPath, "ok", "utf8");
+    await fs.rm(testPath, { force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function runOpenClawInstall(spec: string): number {
+  const result = spawnSync("openclaw", ["plugins", "install", spec], {
+    stdio: "inherit",
+    shell: process.platform === "win32",
+  });
+  return result.status ?? 1;
+}
+
+export function runFfprobeCheck(): boolean {
+  const result = spawnSync(process.platform === "win32" ? "ffprobe.exe" : "ffprobe", ["-version"], {
+    stdio: "ignore",
+    shell: false,
+  });
+  return result.status === 0;
+}
+
+export function readMixinConfig(config: Record<string, unknown> | null): Record<string, unknown> | null {
+  const channels = config?.channels;
+  if (!channels || typeof channels !== "object") {
+    return null;
+  }
+  const mixin = (channels as Record<string, unknown>).mixin;
+  return mixin && typeof mixin === "object" ? (mixin as Record<string, unknown>) : null;
+}
+
+export function isPluginEnabled(config: Record<string, unknown> | null): boolean {
+  const plugins = config?.plugins;
+  if (!plugins || typeof plugins !== "object") {
+    return false;
+  }
+  const allow = Array.isArray((plugins as Record<string, unknown>).allow)
+    ? ((plugins as Record<string, unknown>).allow as unknown[]).map(String)
+    : [];
+  const entries = (plugins as Record<string, unknown>).entries;
+  const mixinEntry = entries && typeof entries === "object"
+    ? (entries as Record<string, unknown>).mixin
+    : null;
+  const enabled = mixinEntry && typeof mixinEntry === "object"
+    ? (mixinEntry as Record<string, unknown>).enabled !== false
+    : false;
+  return allow.includes("mixin") && enabled;
+}