samoagent 0.3.0 → 0.4.1

package/README.md

@@ -14,13 +14,15 @@ Requirements:
 - `RECALL_API_KEY`.
 - `ngrok` installed and authenticated (free plan). `join` starts and manages ngrok automatically — you don't run it yourself.
 
+Install the CLI from npm:
+
 ```bash
-bun install
+npm install -g samoagent
 export RECALL_API_KEY=...
-bun run build
+samoagent join "https://meet.google.com/..." --name Leo
 ```
 
-During development use `bun run samoagent ...`. After build or package install, use `samoagent ...`.
+During development use `bun install`, `bun run build`, then `bun run samoagent ...`.
 
 ## What It Provides
 
@@ -35,6 +37,7 @@ samoagent gives an AI agent a small set of meeting tools:
 - `transcript` - print the transcript (local file, or post-call from Recall).
 - `screenshot` - capture the local Mac screen (fallback when no call frame is available).
 - `dicts` - list available Deepgram keyword dictionaries.
+- `doctor` - check local prerequisites before joining a call.
 
 The agent still decides what to say, when to inspect a frame, and how to use the meeting context. samoagent is the local adapter that exposes those call capabilities.
 

package/dist/cli.js

@@ -1,12 +1,100 @@
 #!/usr/bin/env bun
 // @bun
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toESMCache_node;
+var __toESMCache_esm;
+var __toESM = (mod, isNodeMode, target) => {
+  var canCache = mod != null && typeof mod === "object";
+  if (canCache) {
+    var cache = isNodeMode ? __toESMCache_node ??= new WeakMap : __toESMCache_esm ??= new WeakMap;
+    var cached = cache.get(mod);
+    if (cached)
+      return cached;
+  }
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: __accessProp.bind(mod, key),
+        enumerable: true
+      });
+  if (canCache)
+    cache.set(mod, to);
+  return to;
+};
+var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+
+// package.json
+var require_package = __commonJS((exports, module) => {
+  module.exports = {
+    name: "samoagent",
+    version: "0.4.1",
+    description: "Let AI agents join Zoom and Google Meet calls as active participants.",
+    type: "module",
+    license: "Apache-2.0",
+    bin: {
+      samoagent: "dist/cli.js"
+    },
+    files: [
+      "dist/cli.js",
+      "dictionaries/",
+      "LICENSE",
+      "README.md",
+      "docs/",
+      "avatar.html",
+      "avatar.png",
+      "logo.svg"
+    ],
+    repository: {
+      type: "git",
+      url: "git+https://github.com/NikolayS/samoagent.git"
+    },
+    homepage: "https://samoagent.dev/",
+    bugs: {
+      url: "https://github.com/NikolayS/samoagent/issues"
+    },
+    keywords: [
+      "ai-agent",
+      "meetings",
+      "recall-ai",
+      "zoom",
+      "google-meet",
+      "transcript",
+      "websocket"
+    ],
+    engines: {
+      bun: ">=1.2.0"
+    },
+    publishConfig: {
+      access: "public"
+    },
+    scripts: {
+      samoagent: "bun src/cli.ts",
+      test: "bun test",
+      build: "tsc --noEmit && bun build src/cli.ts --target bun --outfile dist/cli.js && chmod +x dist/cli.js",
+      prepack: "bun run build"
+    },
+    devDependencies: {
+      "@types/bun": "latest",
+      typescript: "^5.9.3"
+    }
+  };
+});
 
 // src/config.ts
 import { homedir } from "os";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 var RECALL_BASE = "https://us-east-1.recall.ai/api/v1";
-var AVATAR_URL = "https://nikolays.github.io/samoagent/avatar.html";
+var AVATAR_URL = "https://samoagent.dev/avatar.html";
 
 class ExitError extends Error {
   code;
@@ -1153,10 +1241,8 @@ async function cmdFrame(args, deps = {}) {
         }
       }
       const raw = new Uint8Array(await resp2.arrayBuffer());
+      writeFrameFiles(out, raw, metadata);
       const output = archive && !args.out ? archiveFrameBytes(String(state.video_frame_dir ?? dirname4(out)), raw, metadata) : out;
-      if (!(archive && !args.out)) {
-        writeFrameFiles(output, raw, metadata);
-      }
       process.stdout.write(resolve3(output) + `
 `);
       return;
@@ -1280,7 +1366,7 @@ function serve(port, transcriptPath, options = {}) {
         let payload = {};
         try {
           const body = await req.text();
-          if (body.length > WEBHOOK_MAX_BYTES) {
+          if (new TextEncoder().encode(body).byteLength > WEBHOOK_MAX_BYTES) {
             return Response.json({ error: "payload too large" }, { status: 413 });
           }
           payload = body ? JSON.parse(body) : {};
@@ -1352,10 +1438,81 @@ async function cmdServe(args) {
   await new Promise(() => {});
 }
 
+// src/commands/doctor.ts
+import { existsSync as existsSync10 } from "fs";
+function commandVersion(command, args = ["--version"]) {
+  try {
+    const proc = Bun.spawnSync([command, ...args]);
+    if (proc.exitCode !== 0) {
+      const stderr = new TextDecoder().decode(proc.stderr).trim();
+      return {
+        ok: false,
+        detail: stderr || `${command} --version exited ${proc.exitCode}`
+      };
+    }
+    const stdout = new TextDecoder().decode(proc.stdout).trim();
+    return {
+      ok: true,
+      detail: stdout.split(/\r?\n/)[0] ?? ""
+    };
+  } catch (e) {
+    return {
+      ok: false,
+      detail: e instanceof Error ? e.message : String(e)
+    };
+  }
+}
+async function cmdDoctor() {
+  const bunVersion = commandVersion("bun");
+  const ngrokVersion = commandVersion("ngrok");
+  const ffmpegVersion = commandVersion("ffmpeg", ["-version"]);
+  const checks = [
+    {
+      name: "Bun",
+      ok: bunVersion.ok,
+      detail: bunVersion.detail || "not found in PATH"
+    },
+    {
+      name: "RECALL_API_KEY",
+      ok: Boolean(process.env.RECALL_API_KEY),
+      detail: process.env.RECALL_API_KEY ? "set" : "missing"
+    },
+    {
+      name: "ngrok",
+      ok: ngrokVersion.ok,
+      detail: ngrokVersion.detail || "not found in PATH"
+    },
+    {
+      name: "ffmpeg",
+      ok: ffmpegVersion.ok,
+      detail: ffmpegVersion.detail || "not found in PATH"
+    },
+    {
+      name: "state",
+      ok: true,
+      detail: existsSync10(stateFile()) ? `active state at ${stateFile()}` : "no active bot state"
+    }
+  ];
+  process.stdout.write(`samoagent doctor
+
+`);
+  for (const check of checks) {
+    process.stdout.write(`${check.ok ? "OK" : "FAIL"}  ${check.name}: ${check.detail}
+`);
+  }
+  if (checks.some((check) => !check.ok)) {
+    process.exit(1);
+  }
+}
+
 // src/cli.ts
 var USAGE = `usage: samoagent <command> [options]
 
-AI meeting agent for Zoom & Google Meet
+Put your AI agent in Zoom and Google Meet calls.
+samoagent joins through Recall.ai, streams live transcript lines,
+captures call frames on demand, and sends explicit chat messages.
+
+Requires: Bun, RECALL_API_KEY env var (get one at recall.ai), and ngrok.
 
 commands:
   join <url> [--name N] [--dict D] [--port P] [--transcript-dir DIR] [--rtmp-url URL] [--rtmp] [--no-ws-video] [--frame-dir DIR]
@@ -1367,7 +1524,52 @@ commands:
   dicts
   watch
   frame [--out FILE] [--archive] [bot_id]
+  doctor
+
+flags:
+  -h, --help     Show this help message
+  -v, --version  Show version number
 `;
+var COMMAND_HELP = {
+  join: `usage: samoagent join <url> [options]
+
+Join a Zoom or Google Meet call as a Recall.ai bot.
+By default, samoagent streams transcript events and receives call frames over WebSocket.
+
+options:
+  --name N               Bot display name
+  --dict D               Deepgram keyword dictionary name
+  --port P               Local callback server port (default: 8080)
+  --transcript-dir DIR   Directory for transcript.txt
+  --frame-dir DIR        Directory for on-demand frame output
+  --no-ws-video          Disable WebSocket call-frame capture
+  --rtmp                 Use local RTMP path through ngrok TCP
+  --rtmp-url URL         Use an existing RTMP endpoint
+
+examples:
+  samoagent join "https://meet.google.com/abc-defg-hij" --name Leo
+  samoagent join "https://zoom.us/j/123" --dict postgresfm
+`,
+  frame: `usage: samoagent frame [--out FILE] [--archive] [bot_id]
+
+Write the latest call frame to disk.
+With the default WebSocket path, frames stay in memory until this command is run.
+
+options:
+  --out FILE   Output path. Defaults to latest frame path from active state.
+  --archive    Also write a timestamped PNG+JSON archive copy.
+
+examples:
+  samoagent frame
+  samoagent frame --out /tmp/current-call.png
+  samoagent frame --archive
+`,
+  doctor: `usage: samoagent doctor
+
+Check local prerequisites for joining meetings:
+Bun, RECALL_API_KEY, ngrok, ffmpeg, and active samoagent state.
+`
+};
 
 class ArgError extends Error {
 }
@@ -1389,6 +1591,7 @@ function parseArgs(argv) {
     dicts: new Set,
     watch: new Set,
     frame: new Set(["--out"]),
+    doctor: new Set,
     _serve: new Set(["--port", "--transcript-file", "--webhook-token", "--call-id-file", "--frame-token"])
   };
   const boolFlags = {
@@ -1401,6 +1604,7 @@ function parseArgs(argv) {
     dicts: new Set,
     watch: new Set,
     frame: new Set(["--archive"]),
+    doctor: new Set,
     _serve: new Set
   };
   const knownCommands = Object.keys(valueFlags);
@@ -1494,6 +1698,7 @@ function parseArgs(argv) {
     }
     case "dicts":
     case "watch":
+    case "doctor":
       break;
     case "_serve": {
       const rawPort2 = opts["--port"];
@@ -1538,6 +1743,8 @@ async function dispatch(args) {
       return cmdDicts();
     case "watch":
       return cmdWatch();
+    case "doctor":
+      return cmdDoctor();
     case "_serve":
       return cmdServe(args);
     default:
@@ -1546,10 +1753,21 @@ async function dispatch(args) {
 }
 async function main() {
   const argv = process.argv.slice(2);
-  if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h" || argv.includes("--help") || argv.includes("-h")) {
+  if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
     process.stdout.write(USAGE);
     process.exit(argv.length === 0 ? 2 : 0);
   }
+  if (argv.length >= 2 && (argv[1] === "--help" || argv[1] === "-h")) {
+    const help = COMMAND_HELP[argv[0]];
+    process.stdout.write(help ?? USAGE);
+    process.exit(help ? 0 : 2);
+  }
+  if (argv[0] === "--version" || argv[0] === "-v" || argv[0] === "-V") {
+    const pkg = await Promise.resolve().then(() => __toESM(require_package(), 1));
+    process.stdout.write(`samoagent ${pkg.version}
+`);
+    process.exit(0);
+  }
   let args;
   try {
     args = parseArgs(argv);

package/docs/release-checklist.md

@@ -0,0 +1,56 @@
+# Release Checklist
+
+Use this checklist for each npm release.
+
+## Before Release
+
+- Confirm `main` is clean and up to date.
+- Run `bun test`.
+- Run `bun run build`.
+- Smoke-test the built CLI:
+
+  ```bash
+  ./dist/cli.js --version
+  ./dist/cli.js --help
+  ```
+
+- Check package metadata:
+
+  ```bash
+  npm pack --dry-run
+  ```
+
+- Confirm `package.json` has the intended version, description, homepage, license, files, and keywords.
+- Confirm `README.md` installation and usage examples match the current CLI.
+
+## Publish
+
+- Bump `package.json` version.
+- Commit and push the version bump.
+- Create and publish a GitHub release tag matching the package version, for example `v0.4.1`.
+- Wait for the `Publish to npm` GitHub Actions workflow to pass.
+
+## After Publish
+
+- Verify npm has the new version:
+
+  ```bash
+  npm view samoagent version
+  ```
+
+- Smoke-test the registry package from a clean prefix:
+
+  ```bash
+  tmp="$(mktemp -d)"
+  npm_config_prefix="$tmp" npm install -g samoagent
+  PATH="$tmp/bin:$PATH" samoagent --version
+  rm -rf "$tmp"
+  ```
+
+- Confirm the package page shows Apache-2.0 license, homepage, README, and provenance.
+- Confirm GitHub Pages is healthy at `https://samoagent.dev/`.
+
+## Secret Hygiene
+
+- Keep `NPM_TOKEN` only in GitHub Actions secrets.
+- Rotate `NPM_TOKEN` immediately if it is pasted into chat, logs, issues, PRs, or local shell history.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "samoagent",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Let AI agents join Zoom and Google Meet calls as active participants.",
   "type": "module",
   "license": "Apache-2.0",
@@ -12,7 +12,7 @@
     "dictionaries/",
     "LICENSE",
     "README.md",
-    "CLAUDE.md",
+    "docs/",
     "avatar.html",
     "avatar.png",
     "logo.svg"

package/CLAUDE.md

@@ -1,67 +0,0 @@
-# samoagent Agent Notes
-
-Use samoagent to join a meeting, watch the live transcript, speak in meeting chat when asked, and capture the call view on demand.
-
-## Preferred Flow
-
-```bash
-samoagent join "https://meet.google.com/..." --name Leo --dict postgresfm
-samoagent watch
-samoagent frame
-samoagent leave
-```
-
-Start `watch` immediately after `join` with your persistent monitor. Keep it running until the call ends. Each line is:
-
-```text
-[timestamp] Speaker: utterance
-```
-
-React in your agent session. Use meeting chat only for deliberate call-visible messages:
-
-```bash
-samoagent chat "Short message to the meeting"
-```
-
-## Looking At The Call
-
-Frame capture is on by default. Recall sends `video_separate_png.data` frames over the ngrok HTTPS/WSS tunnel. Frames stay in server memory; disk writes happen only when the agent calls:
-
-```bash
-samoagent frame
-```
-
-Default output is outside the repo:
-
-```text
-~/.samoagent/frames/latest.png
-~/.samoagent/frames/latest.json
-```
-
-Use explicit outputs only when needed:
-
-```bash
-samoagent frame --out /tmp/call.png
-samoagent frame --archive
-```
-
-`--archive` creates a timestamped filename with bot id, source type, and participant id.
-
-## Mixed Video
-
-Use RTMP only when separate PNG frames are not enough:
-
-```bash
-samoagent join "https://zoom.us/j/..." --rtmp
-samoagent join "https://zoom.us/j/..." --rtmp-url rtmp://HOST:1935/live/call
-```
-
-`--rtmp` needs ngrok TCP, which requires ngrok card verification. `--rtmp-url` needs a public RTMP receiver.
-
-## End The Call
-
-```bash
-samoagent leave
-```
-
-`leave` removes the bot, stops local helper processes, writes the `SAMOAGENT_CALL_ENDED` sentinel, and lets `watch` exit cleanly.