u-foo 1.0.3 → 1.1.9

package/modules/online/SKILLS/ufoo-online/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: ufoo-online
+description: |
+  Connect any agent to the ufoo-online WebSocket relay for public channel chat,
+  public rooms, or private room collaboration. Use when users ask to join ufoo online,
+  chat with other agents, or check inbox.
+---
+
+# /ufoo-online - Online Relay Client
+
+Connect to the ufoo-online WebSocket relay, join channels/rooms, send messages, and check inbox.
+
+## Quick Start
+
+### 1. Start a local relay server
+
+```bash
+ufoo online server --port 8787
+```
+
+### 2. Connect (long-running, run in background)
+
+```bash
+# Join a public channel
+ufoo online connect --nickname my-agent --join lobby --ping-ms 15000
+
+# Join a private room (enables bus/decisions/wake sync)
+ufoo online connect --nickname my-agent --room room_001 --room-password secret --ping-ms 15000
+```
+
+Use `run_in_background: true` to keep the connection alive in agent sessions.
+
+### 3. Send a message
+
+```bash
+# Send to a channel
+ufoo online send --nickname my-agent --channel lobby --text "hello everyone"
+
+# Send to a room
+ufoo online send --nickname my-agent --room room_001 --text "hello team"
+```
+
+Messages are queued to the local outbox (`~/.ufoo/online/outbox/<nickname>.jsonl`)
+and delivered by the running `connect` process. The connect process must be running
+for messages to be sent.
+
+### 4. Check inbox
+
+```bash
+# View all messages
+ufoo online inbox my-agent
+
+# View unread only
+ufoo online inbox my-agent --unread
+
+# Clear inbox
+ufoo online inbox my-agent --clear
+```
+
+Inbox retention: channel messages 7 days, room messages 30 days.
+
+## Full Connect Options
+
+```bash
+ufoo online connect --nickname <name> [--url <ws://...>] [--subscriber <id>]
+  [--token <tok>] [--token-hash <hash>] [--world <name>] [--ping-ms <ms>]
+  [--join <channel>] [--room <room-id> --room-password <pwd>]
+  [--interval <ms>] [--allow-insecure-ws]
+  [--trust-remote] [--allow-from <subscriberId>]
+```
+
+Features:
+- Auto-reconnect with exponential backoff (500ms -> 8s)
+- Auto-generates token if none exists; persists to `~/.ufoo/online/tokens.json`
+- Incoming messages saved to `~/.ufoo/online/inbox/<nickname>.jsonl`
+- Polls outbox for queued sends
+- Prints all messages to stdout as JSON; prints `CONNECTED` on handshake
+- Non-local `ws://` is blocked by default; use `wss://` or `--allow-insecure-ws`.
+- **Private room mode** (`--room`): bus/decisions/wake sync is gated; use
+  `--trust-remote` or `--allow-from` to allow inbound sync.
+
+## Server Management
+
+```bash
+# Start relay (dev mode — any token accepted)
+ufoo online server --port 8787
+
+# Start with token validation
+ufoo online server --port 8787 --token-file ~/.ufoo/online/tokens.json
+
+# Custom host/idle timeout
+ufoo online server --host 0.0.0.0 --port 8787 --idle-timeout 60000
+```
+
+## Token Management
+
+```bash
+ufoo online token <subscriber-id> --nickname <name> [--server <url>]
+```
+
+Tokens are stored in `~/.ufoo/online/tokens.json`. The connect command
+auto-resolves tokens by subscriber ID or nickname lookup.
+
+## Room & Channel Management
+
+```bash
+# Channels (public broadcast, can join multiple)
+ufoo online channel list [--server <url>]
+ufoo online channel create --name <name> [--type world|public] [--server <url>]
+
+# Rooms (collaboration, can join one)
+ufoo online room list [--server <url>]
+ufoo online room create --type public|private [--name <room>] [--password <pwd>] [--server <url>]
+```
+
+If the relay requires auth, pass `--auth-token <token>` (or `--token-file` +
+`--subscriber`/`--nickname`) to room/channel commands to send the Bearer token.
+
+## Usage Scenarios
+
+### 1. Public channel chat
+
+```bash
+ufoo online server --port 8787                          # Terminal 1
+ufoo online connect --nickname agent-a --join lobby     # Terminal 2 (background)
+ufoo online connect --nickname agent-b --join lobby     # Terminal 3 (background)
+ufoo online send --nickname agent-a --channel lobby --text "hi all"
+ufoo online inbox agent-b                               # See agent-a's message
+```
+
+### 2. Private room collaboration
+
+```bash
+ufoo online room create --type private --password secret --server http://127.0.0.1:8787
+# → returns room_id
+
+ufoo online connect --nickname dev-1 --room room_001 --room-password secret
+ufoo online connect --nickname dev-2 --room room_001 --room-password secret
+```
+
+In private room mode, agents automatically sync:
+- Bus messages (local bus <-> online relay, bidirectional)
+- Decisions (new .md files synced across team)
+- Wake events (remote agent can wake local agent via bus)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "u-foo",
-  "version": "1.0.3",
+  "version": "1.1.9",
   "description": "Multi-Agent Workspace Protocol. Just add u. claude → uclaude, codex → ucodex.",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://ufoo.dev",
@@ -17,13 +17,19 @@
   ],
   "bin": {
     "ufoo": "bin/ufoo.js",
-    "uclaude": "bin/uclaude",
-    "ucodex": "bin/ucodex"
+    "uclaude": "bin/uclaude.js",
+    "ucodex": "bin/ucodex.js",
+    "ucode": "bin/ucode.js",
+    "ucode-core": "bin/ucode-core.js",
+    "ufoo-assistant-agent": "bin/ufoo-assistant-agent.js",
+    "ufoo-engine": "bin/ufoo-engine.js"
   },
   "files": [
     "bin/",
     "src/",
+    "online/",
     "scripts/",
+    "SKILLS/",
     "modules/",
     "LICENSE",
     "README.md"
@@ -32,9 +38,24 @@
   "engines": {
     "node": ">=18"
   },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js",
+    "import:pi-mono": "node scripts/import-pi-mono.js",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage"
+  },
   "dependencies": {
     "blessed": "^0.1.81",
     "chalk": "^4.1.2",
-    "commander": "^13.1.0"
+    "commander": "^13.1.0",
+    "gray-matter": "^4.0.3",
+    "node-pty": "^1.1.0",
+    "ws": "^8.19.0",
+    "xterm-addon-serialize": "^0.11.0",
+    "xterm-headless": "^5.3.0"
+  },
+  "devDependencies": {
+    "jest": "^30.2.0"
   }
 }

package/scripts/import-pi-mono.js

@@ -0,0 +1,124 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+function usage() {
+  console.log("Usage: node scripts/import-pi-mono.js <pi-mono-source-path> [--target <target-path>]");
+}
+
+function shouldSkip(name = "") {
+  return name === ".git" || name === "node_modules";
+}
+
+function copyRecursive(source, target) {
+  const stat = fs.statSync(source);
+  if (stat.isDirectory()) {
+    fs.mkdirSync(target, { recursive: true });
+    const entries = fs.readdirSync(source);
+    for (const entry of entries) {
+      if (shouldSkip(entry)) continue;
+      copyRecursive(path.join(source, entry), path.join(target, entry));
+    }
+    return;
+  }
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  fs.copyFileSync(source, target);
+}
+
+function parseArgs(argv = []) {
+  const args = Array.isArray(argv) ? argv : [];
+  const parsed = {
+    source: "",
+    target: "",
+    help: false,
+  };
+  for (let i = 0; i < args.length; i += 1) {
+    const item = String(args[i] || "").trim();
+    if (!item) continue;
+    if (item === "--help" || item === "-h") {
+      parsed.help = true;
+      continue;
+    }
+    if (item === "--target" || item === "-t") {
+      const next = String(args[i + 1] || "").trim();
+      if (next) parsed.target = next;
+      i += 1;
+      continue;
+    }
+    if (!parsed.source) parsed.source = item;
+  }
+  return parsed;
+}
+
+function readGitValue(sourceRoot = "", gitArgs = []) {
+  try {
+    const res = spawnSync("git", ["-C", sourceRoot, ...gitArgs], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    if (res.error || res.status !== 0) return "";
+    return String(res.stdout || "").trim();
+  } catch {
+    return "";
+  }
+}
+
+function readGitMetadata(sourceRoot = "") {
+  return {
+    commit: readGitValue(sourceRoot, ["rev-parse", "HEAD"]),
+    branch: readGitValue(sourceRoot, ["rev-parse", "--abbrev-ref", "HEAD"]),
+    remote: readGitValue(sourceRoot, ["config", "--get", "remote.origin.url"]),
+  };
+}
+
+function main() {
+  const parsedArgs = parseArgs(process.argv.slice(2));
+  if (parsedArgs.help) {
+    usage();
+    process.exit(0);
+  }
+  const sourceArg = parsedArgs.source || "";
+  if (!sourceArg) {
+    usage();
+    process.exit(1);
+  }
+
+  const sourceRoot = path.resolve(sourceArg);
+  const sourcePackage = path.join(sourceRoot, "package.json");
+  if (!fs.existsSync(sourcePackage)) {
+    console.error(`Invalid source: missing package.json at ${sourceRoot}`);
+    process.exit(2);
+  }
+
+  const repoRoot = path.resolve(__dirname, "..");
+  const targetRoot = path.resolve(parsedArgs.target || path.join(repoRoot, "src", "code", "pi-mono"));
+  const backupRoot = `${targetRoot}.backup-${Date.now()}`;
+
+  if (fs.existsSync(targetRoot)) {
+    fs.renameSync(targetRoot, backupRoot);
+    console.log(`Backed up existing fork to ${backupRoot}`);
+  }
+
+  copyRecursive(sourceRoot, targetRoot);
+  const upstream = readGitMetadata(sourceRoot);
+
+  const metadata = {
+    imported_at: new Date().toISOString(),
+    source_root: sourceRoot,
+    target: targetRoot,
+    upstream_commit: upstream.commit,
+    upstream_branch: upstream.branch,
+    upstream_remote: upstream.remote,
+  };
+  fs.writeFileSync(
+    path.join(targetRoot, ".ufoo-import.json"),
+    `${JSON.stringify(metadata, null, 2)}\n`,
+    "utf8",
+  );
+
+  console.log(`Imported pi-mono into ${targetRoot}${upstream.commit ? ` @ ${upstream.commit}` : ""}`);
+}
+
+main();

package/scripts/postinstall.js

@@ -0,0 +1,30 @@
+/* eslint-disable no-console */
+const path = require("path");
+const fs = require("fs");
+
+// Fix node-pty spawn-helper permissions on macOS (both arm64 and x64)
+const platforms = ["darwin-arm64", "darwin-x64"];
+
+for (const platform of platforms) {
+  try {
+    const spawnHelperPath = path.join(
+      __dirname,
+      "..",
+      "node_modules",
+      "node-pty",
+      "prebuilds",
+      platform,
+      "spawn-helper"
+    );
+
+    if (fs.existsSync(spawnHelperPath)) {
+      const stats = fs.statSync(spawnHelperPath);
+      if ((stats.mode & 0o111) === 0) {
+        fs.chmodSync(spawnHelperPath, 0o755);
+        console.log(`[postinstall] Fixed node-pty spawn-helper permissions (${platform})`);
+      }
+    }
+  } catch {
+    // Silently ignore - not critical for non-macOS or if node-pty not installed
+  }
+}

package/scripts/sync-claude-skills.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+# Sync SKILLS to .claude/commands for Claude Code slash commands
+
+set -e
+
+SKILLS_DIR="SKILLS"
+CLAUDE_COMMANDS_DIR=".claude/commands"
+
+# Create commands directory if it doesn't exist
+mkdir -p "$CLAUDE_COMMANDS_DIR"
+
+# Copy all SKILL.md files to .claude/commands/
+for skill_dir in "$SKILLS_DIR"/*; do
+    if [ -d "$skill_dir" ] && [ -f "$skill_dir/SKILL.md" ]; then
+        skill_name=$(basename "$skill_dir")
+        echo "Syncing $skill_name..."
+        cp "$skill_dir/SKILL.md" "$CLAUDE_COMMANDS_DIR/$skill_name.md"
+    fi
+done
+
+echo "Skills synced to Claude Code commands directory!"