@opticell/workflow-companion 1.8.0 → 1.8.1

package/README.md

@@ -1,5 +1,16 @@
 # WorkFlow Companion
 
+[![npm](https://img.shields.io/npm/v/@opticell/workflow-companion?label=npm)](https://www.npmjs.com/package/@opticell/workflow-companion)
+[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.TeamDzX%2Fworkflow--companion-4F46E5)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.TeamDzX/workflow-companion)
+
+> **This repository** is WorkFlow Companion's home: the source (`src/index.js`,
+> MIT licensed), downloads (`WorkFlow.mcpb` for Claude Desktop) on the
+> [Releases](https://github.com/TeamDzX/workflow-companion/releases) page,
+> and bugs and requests in [Issues](https://github.com/TeamDzX/workflow-companion/issues).
+> The package itself installs from npm. On a Mac, use the open-source
+> [workflow-agent-bridge](https://github.com/TeamDzX/workflow-agent-bridge) instead.
+> All of Opticell's free tools for Claude: [opticell-mcp](https://github.com/TeamDzX/opticell-mcp).
+
 Lets **Claude on Windows or Linux** work in your WorkFlow tasks, notes and
 projects: reading the queue, replying in threads, ticking checklists, filing
 notes, updating documents. It works in Claude Code, Claude Desktop, or any MCP
@@ -28,12 +39,23 @@ many devices are on.
 
 ## Install
 
-**Windows** (PowerShell): `irm https://raw.githubusercontent.com/TeamDzX/workflow-companion/main/install.ps1 | iex`
+One line installs Node.js if needed, signs this computer in, adds the
+companion to Claude Code and offers to let it start work on its own:
+
+**Windows** (PowerShell):
 
-**Mac or Linux:** `curl -fsSL https://raw.githubusercontent.com/TeamDzX/workflow-companion/main/install.sh | sh`
+```powershell
+irm https://raw.githubusercontent.com/TeamDzX/workflow-companion/main/install.ps1 | iex
+```
 
-It installs Node.js if needed, signs this computer in, adds the companion to
-Claude Code and offers to let it start work on its own. By hand:
+**Mac or Linux** (Terminal):
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/TeamDzX/workflow-companion/main/install.sh | sh
+```
+
+Switch the companion on in WorkFlow first (step 1 below). The steps that
+follow are what the installer does, if you'd rather do them by hand.
 
 ## Set up
 
@@ -158,24 +180,60 @@ npx -y @opticell/workflow-companion wake-on
 | `workflow-companion` | Runs the MCP server. This is what Claude starts. |
 | `workflow-companion setup` | Signs this computer in. Takes `--web-token` to skip the prompt. |
 | `workflow-companion status` | Which device answers, how fresh the snapshot is, any receipts that arrived late. |
+| `workflow-companion doctor` | Checks everything on this computer and says how to fix what's wrong. Start here when something isn't working. |
 | `workflow-companion keepalive` | Renews the sign-in. The scheduled job runs this. |
 | `workflow-companion update` | Updates the scheduled jobs' copy to the latest release now, and shows how to keep Claude Code on `@latest`. |
 | `workflow-companion auto-update on\|off` | Whether the scheduled jobs update themselves (on by default). |
 | `workflow-companion wake-on` | Starts a Claude Code session on its own when work for its name arrives. See above. |
 | `workflow-companion wake-off` | Stops that. Work waits until you ask Claude here. |
 | `workflow-companion wake` | One check of the queue. The scheduled job runs this. |
+| `workflow-companion monitor add\|list\|check\|remove` | Checks this computer runs without using Claude. See below. |
+| `workflow-companion approvals on\|off` | Lets an assistant run one exact command after you reply "approve CODE" (off by default). |
+| `workflow-companion inbox-on\|inbox-off` | Files dropped in a folder become tasks. |
+| `workflow-companion notifications on\|off` | Notices on this computer (on by default). `notify-test` shows one. |
+| `workflow-companion reports on\|off` | A short report attached to the task after each session (on by default). |
 | `workflow-companion signout` | Deletes the sign-in, cached data and both scheduled jobs. |
 
 ## On this computer, by itself (1.8)
 
-In the same 2-minute scheduled job, without using Claude: **monitors**
-(`monitor add --http/--port/--disk/--process/--file/--command`, posting
-changes on a task and optionally waking a session), **approvals** (an
-assistant asks to run one exact command and it runs once you reply
-"approve CODE"; off until `approvals on`), an **inbox folder** (`inbox-on`:
-dropped files become tasks), **notifications** on the computer, and a
-**session report** attached to the task after each session. Details:
-<https://github.com/TeamDzX/workflow-companion#on-this-computer-by-itself-18>
+These run in the same 2-minute scheduled job as waking, and cost no Claude
+usage.
+
+**Monitors.** Checks that wake Claude only when something changes:
+
+```sh
+workflow-companion monitor add --name site --http https://example.com --task "Server status" --wake
+workflow-companion monitor add --name disk --disk C:\ --min-gb 20 --task "Server status"
+workflow-companion monitor add --name api --port 10.0.0.5:443 --every 2
+workflow-companion monitor add --name backup --file D:\backups\latest.zip --task "Backups"
+workflow-companion monitor add --name nightly --command "check-backups.cmd" --task "Backups" --wake
+```
+
+A change (down, back up, the file changed) is posted on the task, shows a
+notification here, and with `--wake` starts a session about it. An assistant
+can set up website, port, disk, process and file monitors itself
+(`workflow_monitor`), but **only you can add a command monitor**, because it
+runs a command every few minutes.
+
+**Approvals.** An assistant can ask to run one exact command on this computer
+(restart a service, install an update). It posts the command on the task with
+a code; reply `approve K7Q2` (or `decline K7Q2`) from your phone. Only a
+person's reply counts, never another assistant's; tasks in shared projects
+can't ask; the command runs once, exactly as shown, within 24 hours. **Off
+until you run `workflow-companion approvals on` on this computer.**
+
+**Inbox folder.** `workflow-companion inbox-on` makes `~/WorkFlow Inbox`
+(or `--folder`): drop a file in and it becomes a task with the file attached.
+A subfolder named after a project files it into that project. Filed files
+move to `Filed/<date>`. `--assign` puts them in this assistant's queue.
+
+**Notifications.** A notice on this computer when work arrives, a monitor
+changes, an approval is answered, a session needs attention, or the iCloud
+sign-in has ended (with the command that fixes it).
+
+**Session reports.** After each session that changed something, a short
+report is attached to its task: what it was asked, what it changed, any
+approved commands it ran, and its last words.
 
 ## Worth knowing
 
@@ -204,11 +262,26 @@ dropped files become tasks), **notifications** on the computer, and a
 
 ## Tools
 
-The same 29 tools as the Mac's Agent Bridge MCP server, including:
+36 tools, including:
 `workflow_queue`, `workflow_get_task`, `workflow_comment`,
 `workflow_set_status_line`, `workflow_check_subtasks`, `workflow_update_task`,
 `workflow_create_task`, `workflow_list_notes`, `workflow_reply_note`,
 `workflow_list_projects`, `workflow_list_documents`, `workflow_update_document`,
-`workflow_draft_email` and `workflow_state`.
+`workflow_draft_email`, `workflow_state`, and from 1.7 and 1.8
+`workflow_hand_off`, `workflow_watch`, `workflow_house_rules`,
+`workflow_monitor`, `workflow_request_approval`, `workflow_check_approval`
+and `workflow_run_approved`.
 
 © Opticell Limited · <https://www.opticell-limited.com/companion>
+
+## Source and licence
+
+`src/index.js` is the whole server: one file, Node 18 or later, no
+dependencies. It is MIT licensed (see `LICENSE`). The published npm package
+is the same file with WorkFlow's CloudKit API token filled in at build time
+(the token is not a secret: it only lets a signed-in user reach their own
+data). Run from source, `setup` asks for it with `--api-token`.
+
+The `Dockerfile` runs the server over stdio. MCP directories use it to check
+that the server starts and lists its tools, which it does without signing in.
+

package/index.js

@@ -27,7 +27,7 @@ const path = require("path");
 const os = require("os");
 
 const PROTOCOL_VERSION = "2024-11-05";
-const SERVER_INFO = { name: "workflow", version: "1.8.0" };
+const SERVER_INFO = { name: "workflow", version: "1.8.1" };
 // Who the agent is in WorkFlow: the assignee its queue follows, the @name
 // that calls it, the signature on what it writes. On the Mac it's Claude.
 // A companion goes by the name chosen at setup (default "Companion"), so a
@@ -1168,6 +1168,12 @@ const TOOLS = [
       return `Ran ${x.code} on ${os.hostname()} (${result.seconds} s): exit ${result.exit}\n${result.output || "(no output)"}`;
     },
   },
+  {
+    name: "workflow_doctor",
+    description: "Check the companion on this computer end to end (sign-in, WorkFlow publishing and answering, version, scheduled jobs, Claude Code, last session, monitors) and say how to fix anything wrong. Use it when something isn't working.",
+    inputSchema: { type: "object", properties: {} },
+    handler: async () => (await doctorReport({ fromTool: true })).text,
+  },
   {
     name: "workflow_ping",
     description: "Confirm the app is watching the bridge (round-trips one command).",
@@ -1878,17 +1884,20 @@ function notify(title, body, onceKey) {
   if (process.env.WF_NOTIFY_LOG) { try { fs.appendFileSync(process.env.WF_NOTIFY_LOG, `${title} | ${body}\n`); } catch (_) {} return; }
   const { spawn } = require("child_process");
   const opts = { detached: true, stdio: "ignore", windowsHide: true, env: Object.assign({}, process.env, { WF_T: title, WF_B: body }) };
+  // A missing notifier (no notify-send on a server) fails asynchronously:
+  // without a listener that error would end the whole process.
+  const quiet = child => { child.on("error", () => {}); child.unref(); };
   try {
     if (process.platform === "win32") {
       const ps = "[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] > $null;" +
         "$t = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent([Windows.UI.Notifications.ToastTemplateType]::ToastText02);" +
         "$x = $t.GetElementsByTagName('text'); $x.Item(0).AppendChild($t.CreateTextNode($env:WF_T)) > $null; $x.Item(1).AppendChild($t.CreateTextNode($env:WF_B)) > $null;" +
         "[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('{1AC14E77-02E7-4E5D-B744-2EB1AE5198B7}\\WindowsPowerShell\\v1.0\\powershell.exe').Show([Windows.UI.Notifications.ToastNotification]::new($t))";
-      spawn("powershell.exe", ["-NoProfile", "-NonInteractive", "-WindowStyle", "Hidden", "-Command", ps], opts).unref();
+      quiet(spawn("powershell.exe", ["-NoProfile", "-NonInteractive", "-WindowStyle", "Hidden", "-Command", ps], opts));
     } else if (process.platform === "darwin") {
-      spawn("osascript", ["-e", "display notification (system attribute \"WF_B\") with title (system attribute \"WF_T\")"], opts).unref();
+      quiet(spawn("osascript", ["-e", "display notification (system attribute \"WF_B\") with title (system attribute \"WF_T\")"], opts));
     } else {
-      spawn("notify-send", [title, body], opts).unref();
+      quiet(spawn("notify-send", [title, body], opts));
     }
   } catch (_) {}
 }
@@ -2253,6 +2262,122 @@ async function inboxCLI(on) {
   return 0;
 }
 
+// ------------------------------------------------------------------ doctor (1.8.1)
+//
+// Checks the whole chain on this computer in one go and says how to fix
+// anything that's wrong: Node, the iCloud sign-in, whether WorkFlow is
+// publishing and answering, the name, the version, the scheduled jobs,
+// Claude Code, and what the last session did. `fromTool` skips the checks
+// that would be odd from inside a Claude session (asking Claude Code about
+// itself).
+async function doctorReport({ fromTool = false } = {}) {
+  const npx = "npx -y @opticell/workflow-companion@latest";
+  const lines = [`WorkFlow companion ${SERVER_INFO.version} on ${os.hostname()}, as "${AGENT.name}"`, ""];
+  let problems = 0, warnings = 0;
+  const ok = l => lines.push(`  ✓ ${l}`);
+  const bad = (l, fix) => { problems++; lines.push(`  ✗ ${l}`); if (fix) lines.push(`      fix: ${fix}`); };
+  const warn = (l, fix) => { warnings++; lines.push(`  ! ${l}`); if (fix) lines.push(`      ${fix}`); };
+  const done = () => {
+    lines.push("", problems ? `${problems} problem(s)${warnings ? `, ${warnings} warning(s)` : ""}. Fix the ✗ lines first.`
+      : warnings ? `Working, with ${warnings} warning(s).` : "All good.");
+    return { text: lines.join("\n"), problems, warnings };
+  };
+  const ago = t => { const m = Math.round((Date.now() - t) / 60000); return m < 1 ? "just now" : m < 90 ? `${m} min ago` : m < 2880 ? `${Math.round(m / 60)} h ago` : `${Math.round(m / 1440)} days ago`; };
+  const { spawnSync } = require("child_process");
+
+  const major = parseInt(process.versions.node, 10);
+  major >= 18 ? ok(`Node.js ${process.versions.node}`) : bad(`Node.js ${process.versions.node} is too old (18 or later)`, "install the LTS from https://nodejs.org");
+  if (!CLOUD) { warn("this is the Mac's own bridge, not a companion", "on the Mac, check Settings → Agent Bridge, or run: wf state"); return done(); }
+
+  const cfg = readJSON(CP.config, null);
+  if (!cfg || !fs.existsSync(CP.token)) { bad("not signed in on this computer", `${npx} setup`); return done(); }
+  try {
+    await cloud.call("public/users/caller");
+    ok(`iCloud sign-in works (${cfg.env || COMPANION.env})`);
+  } catch (e) {
+    if (e instanceof SignInNeeded) bad("the iCloud sign-in has ended (Apple ends one left unused for 9 to 14 hours)", `${npx} setup`);
+    else bad(`can't reach iCloud: ${String(e.message).split("\n")[0]}`, "check this computer's internet connection, then run doctor again");
+    return done();
+  }
+
+  try { await cloud.load(true); } catch (e) { bad(`couldn't read WorkFlow's snapshot: ${e.message}`); return done(); }
+  if (!cloudSnap) {
+    bad("WorkFlow hasn't published anything for the companion yet",
+      "switch it on in WorkFlow: iPhone/iPad Settings → Windows Companion → Answer the Companion, or Mac Settings → Agent Bridge → Cloud Bridge");
+  } else {
+    const age = Date.now() - Date.parse(cloudSnap.generatedAt);
+    const line = `${cloudSnap.tasks.length} tasks, published ${ago(Date.parse(cloudSnap.generatedAt))}; answering: ${cloud.macLine()}`;
+    age < 6 * 3600 * 1000 ? ok(line) : warn(line, "nothing has changed in WorkFlow for a while, or the device that answers is asleep or closed: open WorkFlow on it");
+    const clash = nameClash(AGENT.name);
+    clash ? bad(`"${AGENT.name}" is also the name of Claude on ${clash.host}: both would act on @${AGENT.name}`, `${npx} setup --name <another name>`)
+      : ok(`the name "${AGENT.name}" is this computer's alone`);
+  }
+
+  if (!fromTool) {
+    const started = Date.now();
+    try {
+      const r = await send("ping", {}, 30000);
+      r.status === "applied" ? ok(`a test command was applied by WorkFlow in ${Math.max(1, Math.round((Date.now() - started) / 1000))} s`)
+        : warn("a test command got no answer within 30 s", "WorkFlow on the answering device may be asleep or closed. Commands wait safely and run when it next looks; an iPhone can take minutes");
+    } catch (e) { warn(`couldn't send a test command: ${e.message}`); }
+  }
+
+  const rel = await latestRelease(true);
+  if (!rel) warn("couldn't check npm for a newer release");
+  else if (newerVersion(rel.version, SERVER_INFO.version)) warn(`version ${SERVER_INFO.version}; ${rel.version} is out`, `${npx} update  (and restart Claude Code)`);
+  else ok(`version ${SERVER_INFO.version} is the latest`);
+  const saved = versionOfScript(SAVED_SCRIPT);
+  if (saved && rel && newerVersion(rel.version, saved)) warn(`the scheduled jobs run ${saved}`, cfg.autoUpdate === false ? `auto-update is off: ${npx} update` : "they update themselves within 6 hours, or now with: " + `${npx} update`);
+
+  const scheduled = name => {
+    if (process.platform === "win32") return spawnSync("schtasks", ["/Query", "/TN", name], { encoding: "utf8", windowsHide: true }).status === 0;
+    const r = spawnSync("crontab", ["-l"], { encoding: "utf8" });
+    return r.status === 0 && r.stdout.includes(name === TASK_NAME ? "workflow-companion keepalive" : "workflow-companion wake");
+  };
+  let lastKeepAlive = "";
+  try { lastKeepAlive = fs.readFileSync(KEEPALIVE_LOG, "utf8").trim().split("\n").pop(); } catch (_) {}
+  scheduled(TASK_NAME) ? ok(`keep-alive scheduled${lastKeepAlive ? `; last run ${lastKeepAlive.split(" ")[0].slice(0, 16).replace("T", " ")}: ${lastKeepAlive.split(" ").slice(1).join(" ")}` : ""}`)
+    : warn("the keep-alive isn't scheduled, so the sign-in can end while Claude isn't running", `${npx} setup  (it schedules it)`);
+
+  if (cfg.wakeEnabled) {
+    scheduled(WAKE.taskName) ? ok("waking is on and scheduled every 2 minutes") : bad("waking is on but its scheduled job is missing", `${npx} wake-on`);
+    const bin = cfg.claudeBin || "claude";
+    const v = spawnSync(bin, ["--version"], { encoding: "utf8", timeout: 20000, windowsHide: true, shell: process.platform === "win32" && /\.(cmd|bat)$/i.test(bin) });
+    v.status === 0 ? ok(`Claude Code runs: ${String(v.stdout).trim().split("\n")[0]}`)
+      : bad(`Claude Code at ${bin} doesn't run`, `reinstall or sign in to Claude Code, then: ${npx} wake-on`);
+    let log = [];
+    try { log = fs.readFileSync(WAKE.log, "utf8").trim().split("\n"); } catch (_) {}
+    const last = log.filter(l => / session exited /.test(l)).pop();
+    if (!last) ok("no sessions yet");
+    else {
+      const when = Date.parse(last.split(" ")[0]);
+      const code = (/session exited (-?\d+)/.exec(last) || [])[1];
+      code === "0" && !/time limit/.test(last) ? ok(`last session ${ago(when)} finished normally`)
+        : warn(`last session ${ago(when)} didn't finish normally: ${last.split(" ").slice(1).join(" ").slice(0, 160)}`, `see ${WAKE.log}`);
+    }
+    if (log.slice(-30).some(l => /SIGN-IN ENDED/.test(l))) warn("the sign-in ended recently (it works now)", "if this PC sleeps for long, leave it awake or check it each morning");
+  } else {
+    warn("waking is off: work waits until you ask Claude on this computer", `${npx} wake-on`);
+  }
+
+  if (!fromTool) {
+    const bin = cfg.claudeBin || "claude";
+    const list = spawnSync(bin, ["mcp", "list"], { encoding: "utf8", timeout: 60000, windowsHide: true, shell: process.platform === "win32" && /\.(cmd|bat)$/i.test(bin) });
+    const text = String(list.stdout || "");
+    if (list.status !== 0 && !text) warn("couldn't ask Claude Code which tools it has", `if it isn't installed: ${claudeCodeCommand()}`);
+    else if (!/workflow/i.test(text)) bad("Claude Code doesn't have the companion", claudeCodeCommand());
+    else if (!/@latest/.test(text.split("\n").find(l => /^workflow/i.test(l)) || "")) warn("Claude Code runs a pinned version of the companion", `claude mcp remove workflow -s user, then: ${claudeCodeCommand()}`);
+    else ok("Claude Code has the companion, on @latest");
+  }
+
+  const failing = loadMonitors().filter(m => m.state && !m.state.ok);
+  if (loadMonitors().length) failing.length ? warn(`monitors failing: ${failing.map(m => `${m.name} (${m.state.detail})`).join(", ")}`) : ok(`${loadMonitors().length} monitor(s), all OK`);
+  const pending = loadApprovals().filter(a => a.status === "pending");
+  if (pending.length) warn(`${pending.length} approval(s) waiting for you: ${pending.map(a => `${a.code} on “${a.taskTitle}”`).join(", ")}`);
+  if (cfg.inboxFolder) fs.existsSync(cfg.inboxFolder) ? ok(`inbox folder: ${cfg.inboxFolder}`) : bad(`the inbox folder ${cfg.inboxFolder} is missing`, `${npx} inbox-on --folder "<path>"`);
+  return done();
+}
+
 // ------------------------------------------------------------------ versions (1.6.1)
 
 // Each companion says which version it runs, and keeps itself current.
@@ -2479,6 +2604,7 @@ const HELP = `WorkFlow companion ${SERVER_INFO.version}
   workflow-companion            run the MCP server (what Claude starts)
   workflow-companion setup      sign this computer in to iCloud for WorkFlow (--name, --takeover, --no-browser)
   workflow-companion status     which device answers, how fresh is the snapshot
+  workflow-companion doctor     check everything on this computer and say how to fix what's wrong
   workflow-companion keepalive  renew the sign-in (what the scheduled job runs)
   workflow-companion update     update the scheduled jobs' copy now, and say how to keep Claude Code current
   workflow-companion auto-update on|off   whether the scheduled jobs update themselves (on by default)
@@ -2505,6 +2631,7 @@ Install in one line: see https://github.com/TeamDzX/workflow-companion#install
 if (argv.includes("--print-config")) printConfig();
 else if (argv.includes("--help") || verb === "help") process.stdout.write(HELP);
 else if (verb === "setup") setup().then(c => { process.exitCode = c; }, e => { console.error(e.message || e); process.exitCode = 1; });
+else if (verb === "doctor") doctorReport().then(r => { console.log(r.text); process.exitCode = r.problems ? 1 : 0; }, e => { console.error(e.message || e); process.exitCode = 1; });
 else if (verb === "status") cloudStateText().then(t => console.log(t), e => { console.error(e.message || e); process.exitCode = 1; });
 else if (verb === "keepalive") keepAlive().then(c => { process.exitCode = c; });
 else if (verb === "update") updateNow().then(c => { process.exitCode = c; }, e => { console.error(e.message || e); process.exitCode = 1; });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opticell/workflow-companion",
-  "version": "1.8.0",
+  "version": "1.8.1",
   "mcpName": "io.github.TeamDzX/workflow-companion",
   "description": "Lets Claude on Windows or Linux work in your WorkFlow tasks, notes and projects, through WorkFlow for Mac and your own iCloud. An MCP server.",
   "keywords": [