samoagent 0.4.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

@@ -36,7 +36,7 @@ var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports,
 var require_package = __commonJS((exports, module) => {
   module.exports = {
     name: "samoagent",
-    version: "0.4.0",
+    version: "0.4.1",
     description: "Let AI agents join Zoom and Google Meet calls as active participants.",
     type: "module",
     license: "Apache-2.0",
@@ -48,6 +48,7 @@ var require_package = __commonJS((exports, module) => {
       "dictionaries/",
       "LICENSE",
       "README.md",
+      "docs/",
       "avatar.html",
       "avatar.png",
       "logo.svg"
@@ -93,7 +94,7 @@ 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;
@@ -1437,13 +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]
 
-Meeting I/O helper for AI agents \u2014 join Zoom & Google Meet calls,
-stream live transcripts, capture frames, and send chat messages.
+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: RECALL_API_KEY env var (get one at recall.ai) and ngrok.
+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]
@@ -1455,11 +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 {
 }
@@ -1481,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 = {
@@ -1493,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);
@@ -1586,6 +1698,7 @@ function parseArgs(argv) {
     }
     case "dicts":
     case "watch":
+    case "doctor":
       break;
     case "_serve": {
       const rawPort2 = opts["--port"];
@@ -1630,6 +1743,8 @@ async function dispatch(args) {
       return cmdDicts();
     case "watch":
       return cmdWatch();
+    case "doctor":
+      return cmdDoctor();
     case "_serve":
       return cmdServe(args);
     default:
@@ -1638,10 +1753,15 @@ 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}

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.4.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,6 +12,7 @@
     "dictionaries/",
     "LICENSE",
     "README.md",
+    "docs/",
     "avatar.html",
     "avatar.png",
     "logo.svg"