feed-the-machine 1.1.0 → 1.3.0

package/bin/install.mjs

@@ -3,14 +3,20 @@
 /**
  * npx feed-the-machine — installs ftm skills into ~/.claude/skills/
  *
- * Works by finding the npm package root (where the skill files live)
- * and symlinking them into the Claude Code skills directory.
+ * Full install: skills, hooks, settings.json merge, and verification.
+ * Safe to re-run — idempotent.
+ *
+ * Flags:
+ *   --with-inbox    Also install the inbox service
+ *   --no-hooks      Skip hooks entirely
+ *   --skip-merge    Install hook files but don't touch settings.json
  */
 
-import { existsSync, mkdirSync, readdirSync, lstatSync, readFileSync, writeFileSync, copyFileSync, symlinkSync, unlinkSync, chmodSync } from "fs";
+import { existsSync, mkdirSync, readdirSync, lstatSync, readFileSync, writeFileSync, copyFileSync, symlinkSync, unlinkSync, chmodSync, cpSync } from "fs";
 import { join, basename, dirname } from "path";
-import { homedir } from "os";
+import { homedir, platform } from "os";
 import { fileURLToPath } from "url";
+import { execSync, spawnSync } from "child_process";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -20,11 +26,25 @@ const SKILLS_DIR = join(HOME, ".claude", "skills");
 const STATE_DIR = join(HOME, ".claude", "ftm-state");
 const CONFIG_DIR = join(HOME, ".claude");
 const HOOKS_DIR = join(HOME, ".claude", "hooks");
+const SETTINGS_FILE = join(CONFIG_DIR, "settings.json");
+const INBOX_INSTALL_DIR = join(HOME, ".claude", "ftm-inbox");
+
+const ARGS = process.argv.slice(2);
+const WITH_INBOX = ARGS.includes("--with-inbox");
+const NO_HOOKS = ARGS.includes("--no-hooks");
+const SKIP_MERGE = ARGS.includes("--skip-merge");
+
+let warnCount = 0;
 
 function log(msg) {
   console.log(`  ${msg}`);
 }
 
+function warn(msg) {
+  console.log(`  WARN: ${msg}`);
+  warnCount++;
+}
+
 function ensureDir(dir) {
   if (!existsSync(dir)) {
     mkdirSync(dir, { recursive: true });
@@ -47,7 +67,212 @@ function safeSymlink(src, dest) {
   log(`LINK ${name}`);
 }
 
+function commandExists(cmd) {
+  try {
+    execSync(`command -v ${cmd}`, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function commandVersion(cmd, flag = "--version") {
+  try {
+    return execSync(`${cmd} ${flag}`, { encoding: "utf8" }).trim().split("\n")[0];
+  } catch {
+    return "unknown";
+  }
+}
+
+// --- Preflight ---
+
+function preflight() {
+  console.log("Preflight checks...");
+
+  if (!NO_HOOKS) {
+    // jq is required for all shell hooks (they parse JSON stdin via jq)
+    if (!commandExists("jq")) {
+      console.log("");
+      console.log("  ERROR: jq is required for FTM hooks.");
+      console.log("");
+      console.log("  Install it:");
+      console.log("    macOS:   brew install jq");
+      console.log("    Ubuntu:  sudo apt-get install jq");
+      console.log("    Alpine:  apk add jq");
+      console.log("");
+      console.log("  Or skip hooks: npx feed-the-machine --no-hooks");
+      process.exit(1);
+    }
+    log(`jq: ${commandVersion("jq")}`);
+    log(`node: ${process.version}`);
+  } else {
+    log("hooks skipped (--no-hooks)");
+  }
+
+  console.log("");
+}
+
+// --- Settings Merge ---
+
+function mergeHooksIntoSettings() {
+  const templatePath = join(REPO_DIR, "hooks", "settings-template.json");
+  if (!existsSync(templatePath)) {
+    warn("hooks/settings-template.json not found — hooks installed but not registered");
+    return;
+  }
+
+  console.log("");
+  console.log("Registering hooks in settings.json...");
+
+  // Read and expand ~ to actual home directory
+  const rawTemplate = readFileSync(templatePath, "utf8");
+  const expandedTemplate = rawTemplate.replace(/~\/.claude/g, join(HOME, ".claude"));
+  const template = JSON.parse(expandedTemplate);
+  const templateHooks = template.hooks || {};
+
+  if (!existsSync(SETTINGS_FILE)) {
+    // No settings.json — create one with just the hooks
+    writeFileSync(SETTINGS_FILE, JSON.stringify({ hooks: templateHooks }, null, 2) + "\n");
+    log("CREATED settings.json with FTM hooks");
+    return;
+  }
+
+  // Read existing settings
+  const existing = JSON.parse(readFileSync(SETTINGS_FILE, "utf8"));
+
+  // Backup
+  const ts = new Date().toISOString().replace(/[-:T]/g, "").slice(0, 14);
+  const backupPath = `${SETTINGS_FILE}.ftm-backup-${ts}`;
+  copyFileSync(SETTINGS_FILE, backupPath);
+  log(`BACKUP ${backupPath}`);
+
+  // Ensure hooks key exists
+  if (!existing.hooks) {
+    existing.hooks = {};
+  }
+
+  // Merge each event type
+  const events = ["PreToolUse", "UserPromptSubmit", "PostToolUse", "Stop"];
+  for (const event of events) {
+    const templateEntries = templateHooks[event] || [];
+    const existingEntries = existing.hooks[event] || [];
+
+    if (templateEntries.length === 0) continue;
+
+    // Check if FTM hooks are already present by looking for ftm- in command paths
+    const existingCommands = JSON.stringify(existingEntries);
+    const alreadyPresent = templateEntries.some((entry) => {
+      const hooks = entry.hooks || [];
+      return hooks.some((h) => {
+        const cmd = h.command || "";
+        const cmdBase = basename(cmd.split(" ").pop()); // handle "node foo.mjs"
+        return existingCommands.includes(cmdBase);
+      });
+    });
+
+    if (alreadyPresent) {
+      log(`SKIP ${event} hooks (already configured)`);
+      continue;
+    }
+
+    existing.hooks[event] = [...existingEntries, ...templateEntries];
+    log(`MERGE ${event} hooks`);
+  }
+
+  writeFileSync(SETTINGS_FILE, JSON.stringify(existing, null, 2) + "\n");
+  log("UPDATED settings.json");
+  console.log("");
+  log("Hooks are active.");
+}
+
+// --- Verification ---
+
+function verify(skillCount, hookCount) {
+  console.log("");
+  console.log("Verifying installation...");
+
+  let errors = 0;
+
+  // Check skill symlinks resolve
+  let brokenLinks = 0;
+  const skillEntries = readdirSync(SKILLS_DIR).filter((f) => f.startsWith("ftm"));
+  for (const entry of skillEntries) {
+    const fullPath = join(SKILLS_DIR, entry);
+    try {
+      if (lstatSync(fullPath).isSymbolicLink() && !existsSync(fullPath)) {
+        warn(`broken symlink: ${entry}`);
+        brokenLinks++;
+      }
+    } catch {
+      // ignore
+    }
+  }
+  if (brokenLinks === 0) {
+    log(`Skills: ${skillCount} linked, all symlinks valid`);
+  } else {
+    errors++;
+  }
+
+  // Check blackboard state
+  const contextFile = join(STATE_DIR, "blackboard", "context.json");
+  const patternsFile = join(STATE_DIR, "blackboard", "patterns.json");
+  if (existsSync(contextFile) && existsSync(patternsFile)) {
+    log("Blackboard: initialized");
+  } else {
+    warn("blackboard state incomplete");
+    errors++;
+  }
+
+  // Check config
+  if (existsSync(join(CONFIG_DIR, "ftm-config.yml"))) {
+    log("Config: present");
+  } else {
+    warn("ftm-config.yml missing");
+    errors++;
+  }
+
+  // Check hooks
+  if (!NO_HOOKS && hookCount > 0) {
+    const hookFiles = readdirSync(HOOKS_DIR).filter((f) => f.startsWith("ftm-"));
+    const allExecutable = hookFiles
+      .filter((f) => f.endsWith(".sh"))
+      .every((f) => {
+        try {
+          const stat = lstatSync(join(HOOKS_DIR, f));
+          return (stat.mode & 0o111) !== 0;
+        } catch {
+          return false;
+        }
+      });
+
+    if (allExecutable) {
+      log(`Hooks: ${hookCount} installed, all executable`);
+    } else {
+      warn("some hook files not executable");
+      errors++;
+    }
+
+    // Verify settings.json has FTM hooks
+    if (!SKIP_MERGE && existsSync(SETTINGS_FILE)) {
+      const settingsContent = readFileSync(SETTINGS_FILE, "utf8");
+      const ftmMatches = (settingsContent.match(/ftm-/g) || []).length;
+      if (ftmMatches > 0) {
+        log(`Settings: ${ftmMatches} FTM entries in settings.json`);
+      } else {
+        warn("no FTM hooks found in settings.json");
+        errors++;
+      }
+    }
+  }
+
+  return { errors };
+}
+
+// --- Main ---
+
 function main() {
+  preflight();
+
   console.log(`Installing ftm skills from: ${REPO_DIR}`);
   console.log(`Linking into: ${SKILLS_DIR}`);
   console.log("");
@@ -77,9 +302,13 @@ function main() {
     safeSymlink(join(REPO_DIR, dir), join(SKILLS_DIR, dir));
   }
 
+  console.log("");
+  log(`${ymlFiles.length} skills linked.`);
+
   // Set up blackboard state (copy templates, don't overwrite existing data)
   const bbDir = join(REPO_DIR, "ftm-state", "blackboard");
   if (existsSync(bbDir)) {
+    console.log("");
     ensureDir(join(STATE_DIR, "blackboard", "experiences"));
 
     const jsonFiles = readdirSync(bbDir).filter((f) => f.endsWith(".json"));
@@ -108,37 +337,154 @@ function main() {
   }
 
   // Install hooks
-  const hooksDir = join(REPO_DIR, "hooks");
   let hookCount = 0;
-  if (existsSync(hooksDir)) {
-    ensureDir(HOOKS_DIR);
+
+  if (NO_HOOKS) {
     console.log("");
-    console.log("Installing hooks...");
-
-    const hookFiles = readdirSync(hooksDir).filter(
-      (f) => f.startsWith("ftm-") && (f.endsWith(".sh") || f.endsWith(".mjs"))
-    );
-    for (const hook of hookFiles) {
-      const src = join(hooksDir, hook);
-      const dest = join(HOOKS_DIR, hook);
-      const action = existsSync(dest) ? "UPDATE" : "INSTALL";
-      copyFileSync(src, dest);
-      if (hook.endsWith(".sh")) {
-        chmodSync(dest, 0o755);
+    console.log("Skipping hooks (--no-hooks).");
+  } else {
+    const hooksDir = join(REPO_DIR, "hooks");
+    if (existsSync(hooksDir)) {
+      ensureDir(HOOKS_DIR);
+      console.log("");
+      console.log("Installing hooks...");
+
+      const hookFiles = readdirSync(hooksDir).filter(
+        (f) => f.startsWith("ftm-") && (f.endsWith(".sh") || f.endsWith(".mjs"))
+      );
+      for (const hook of hookFiles) {
+        const src = join(hooksDir, hook);
+        const dest = join(HOOKS_DIR, hook);
+        const action = existsSync(dest) ? "UPDATE" : "INSTALL";
+        copyFileSync(src, dest);
+        if (hook.endsWith(".sh")) {
+          chmodSync(dest, 0o755);
+        }
+        log(`${action} ${hook}`);
+        hookCount++;
       }
-      log(`${action} ${hook}`);
-      hookCount++;
+
+      console.log("");
+      log(`${hookCount} hooks installed to ${HOOKS_DIR}`);
+    }
+
+    // Merge hooks into settings.json
+    if (SKIP_MERGE) {
+      console.log("");
+      log("Skipping settings.json merge (--skip-merge).");
+      log("Add entries from hooks/settings-template.json to ~/.claude/settings.json manually.");
+    } else {
+      mergeHooksIntoSettings();
     }
   }
 
+  // Verification
+  const { errors } = verify(ymlFiles.length, hookCount);
+
+  // Summary
   console.log("");
-  console.log(`Done. ${ymlFiles.length} skills linked, ${hookCount} hooks installed.`);
+  if (errors === 0 && warnCount === 0) {
+    console.log(`Done. ${ymlFiles.length} skills, ${hookCount} hooks. Everything checks out.`);
+  } else {
+    console.log(`Done. ${ymlFiles.length} skills, ${hookCount} hooks. ${warnCount} warning(s).`);
+  }
+  console.log("");
+  console.log("Restart Claude Code (or start a new session) to pick up the skills.");
+
+  if (WITH_INBOX) {
+    console.log("");
+    installInbox();
+  } else {
+    console.log("Try: /ftm help");
+    console.log("     To also install the inbox service: npx feed-the-machine --with-inbox");
+  }
+}
+
+function installInbox() {
+  const inboxSrc = join(REPO_DIR, "ftm-inbox");
+  if (!existsSync(inboxSrc)) {
+    console.error("ERROR: ftm-inbox/ not found in package. Cannot install inbox service.");
+    process.exit(1);
+  }
+
+  console.log("Installing ftm-inbox service...");
+  console.log(`  Source:      ${inboxSrc}`);
+  console.log(`  Destination: ${INBOX_INSTALL_DIR}`);
+  console.log("");
+
+  // Copy ftm-inbox/ to ~/.claude/ftm-inbox/
+  ensureDir(INBOX_INSTALL_DIR);
+  cpSync(inboxSrc, INBOX_INSTALL_DIR, { recursive: true });
+  log("COPY ftm-inbox → ~/.claude/ftm-inbox/");
+
+  // Make shell scripts executable
+  const binDir = join(INBOX_INSTALL_DIR, "bin");
+  const scripts = ["start.sh", "stop.sh", "status.sh"];
+  for (const script of scripts) {
+    const scriptPath = join(binDir, script);
+    if (existsSync(scriptPath)) {
+      chmodSync(scriptPath, 0o755);
+      log(`CHMOD +x bin/${script}`);
+    }
+  }
+
+  // Install Node deps if package.json exists
+  const pkgJson = join(INBOX_INSTALL_DIR, "package.json");
+  if (existsSync(pkgJson)) {
+    console.log("");
+    console.log("Installing Node.js dependencies...");
+    const npmResult = spawnSync("npm", ["install", "--prefix", INBOX_INSTALL_DIR], {
+      stdio: "inherit",
+      cwd: INBOX_INSTALL_DIR,
+    });
+    if (npmResult.status !== 0) {
+      console.warn("WARNING: npm install failed. Check Node.js version and try manually.");
+    }
+  }
+
+  // Install Python deps if requirements.txt exists
+  const reqTxt = join(INBOX_INSTALL_DIR, "requirements.txt");
+  if (existsSync(reqTxt)) {
+    console.log("");
+    console.log("Installing Python dependencies...");
+    const pipResult = spawnSync("pip3", ["install", "-r", reqTxt], {
+      stdio: "inherit",
+      cwd: INBOX_INSTALL_DIR,
+    });
+    if (pipResult.status !== 0) {
+      console.warn("WARNING: pip3 install failed. Check Python 3 and try manually:");
+      console.warn(`  pip3 install -r ${reqTxt}`);
+    }
+  }
+
+  // Run setup wizard
+  console.log("");
+  console.log("Running setup wizard...");
+  const setupScript = join(binDir, "setup.mjs");
+  if (existsSync(setupScript)) {
+    const setupResult = spawnSync("node", [setupScript], { stdio: "inherit" });
+    if (setupResult.status !== 0) {
+      console.warn("WARNING: Setup wizard exited with errors.");
+      console.warn(`Re-run manually: node ${setupScript}`);
+    }
+  } else {
+    console.warn("WARNING: setup.mjs not found. Run setup manually.");
+  }
+
+  // Offer LaunchAgent (macOS only)
+  if (platform() === "darwin") {
+    console.log("");
+    console.log("macOS detected. To auto-start ftm-inbox on login, run:");
+    console.log(`  node ${join(binDir, "launchagent.mjs")}`);
+  }
+
   console.log("");
-  console.log("To activate hooks, add them to ~/.claude/settings.json");
-  console.log("  Option A: ./install.sh --setup-hooks (auto-merge)");
-  console.log("  Option B: Copy entries from hooks/settings-template.json manually");
-  console.log("  See docs/HOOKS.md for details.");
+  console.log("ftm-inbox installed.");
+  console.log(`  Start:  ${join(binDir, "start.sh")}`);
+  console.log(`  Stop:   ${join(binDir, "stop.sh")}`);
+  console.log(`  Status: ${join(binDir, "status.sh")}`);
   console.log("");
+  console.log("See docs/INBOX.md for full documentation.");
   console.log("Try: /ftm help");
 }
 

package/docs/INBOX.md

@@ -0,0 +1,233 @@
+# ftm-inbox
+
+ftm-inbox is an optional background service that polls your work tools (Jira, Freshservice, Slack, Gmail) and surfaces actionable items directly inside the FTM Operator Cockpit dashboard. It runs locally on your machine and never sends data to external services.
+
+## What It Does
+
+Without ftm-inbox, the Operator Cockpit is a static interface. With it:
+
+- Jira issues assigned to you appear as inbox items
+- Freshservice tickets awaiting your response are surfaced
+- Slack DMs and mentions are queued for triage
+- Gmail threads that match configurable filters are included
+
+Each item is stored in a local SQLite database. The FTM skills (`/ftm-mind`, `/ftm-executor`) can read from this inbox to generate plans and take action on your behalf.
+
+## Installation
+
+```bash
+npx feed-the-machine --with-inbox
+```
+
+This will:
+
+1. Install core FTM skills (same as `npx feed-the-machine`)
+2. Copy `ftm-inbox/` to `~/.claude/ftm-inbox/`
+3. Run `npm install` for Node dependencies
+4. Run `pip3 install -r requirements.txt` for Python dependencies
+5. Launch the interactive setup wizard
+6. Optionally install a macOS LaunchAgent for auto-start on login
+
+The core `npx feed-the-machine` install (without `--with-inbox`) is completely unchanged.
+
+### Requirements
+
+- Node.js 18+
+- Python 3.9+
+- `pip3` in PATH
+
+## Configuration
+
+The setup wizard writes credentials to `~/.claude/ftm-inbox/config.yml`. This directory is outside any git repository and should never be committed.
+
+### config.yml reference
+
+```yaml
+server:
+  port: 8042              # Port for the local API (default: 8042)
+
+adapters:
+  jira:
+    enabled: true
+    base_url: "https://yourorg.atlassian.net"
+    email: "you@example.com"
+    api_token: "your-jira-api-token"
+    poll_interval_seconds: 60
+
+  freshservice:
+    enabled: true
+    domain: "yourorg.freshservice.com"
+    api_key: "your-freshservice-api-key"
+    poll_interval_seconds: 120
+
+  slack:
+    enabled: true
+    bot_token: "xoxb-your-slack-bot-token"
+    poll_interval_seconds: 30
+
+  gmail:
+    enabled: false
+    credentials_path: "~/credentials.json"
+    poll_interval_seconds: 120
+
+database:
+  path: "~/.claude/ftm-inbox/inbox.db"
+
+logging:
+  level: "INFO"
+  path: "~/.claude/ftm-inbox/logs"
+```
+
+To re-run the wizard after initial setup:
+
+```bash
+node ~/.claude/ftm-inbox/bin/setup.mjs
+```
+
+To edit manually:
+
+```bash
+$EDITOR ~/.claude/ftm-inbox/config.yml
+```
+
+## Starting and Stopping
+
+```bash
+# Start the service
+~/.claude/ftm-inbox/bin/start.sh
+
+# Stop the service
+~/.claude/ftm-inbox/bin/stop.sh
+
+# Check status and last poll times
+~/.claude/ftm-inbox/bin/status.sh
+```
+
+The port can be overridden at runtime:
+
+```bash
+FTM_INBOX_PORT=9000 ~/.claude/ftm-inbox/bin/start.sh
+```
+
+## Auto-start on Login (macOS)
+
+To generate and load a LaunchAgent that starts ftm-inbox on login:
+
+```bash
+node ~/.claude/ftm-inbox/bin/launchagent.mjs
+```
+
+This creates `~/Library/LaunchAgents/com.ftm.inbox.plist` and loads it immediately. Logs are written to `~/.claude/ftm-inbox/logs/`.
+
+To remove the LaunchAgent:
+
+```bash
+launchctl unload ~/Library/LaunchAgents/com.ftm.inbox.plist
+rm ~/Library/LaunchAgents/com.ftm.inbox.plist
+```
+
+## Architecture
+
+```
+External Services          ftm-inbox                   FTM Skills
+──────────────────         ─────────────────────────   ──────────────────
+Jira REST API    ──────► Jira Adapter (poller)   ─┐
+Freshservice API ──────► Freshservice Adapter    ─┤► SQLite DB ──► FastAPI ──► /ftm-mind
+Slack API        ──────► Slack Adapter           ─┤  inbox.db           8042    /ftm-executor
+Gmail API        ──────► Gmail Adapter           ─┘
+                                                          ▲
+                                                          │
+                                                    Svelte Dashboard
+                                                    (Operator Cockpit)
+```
+
+- **Adapters** poll their respective APIs on configurable intervals and write normalized `InboxItem` records to SQLite
+- **FastAPI backend** (`backend/main.py`) exposes a REST API at `http://localhost:8042`
+- **Svelte dashboard** reads from the API and renders the Operator Cockpit UI
+- **FTM skills** use the API to read inbox items and generate or execute plans
+
+## Adding a Custom Poller
+
+1. Create a new file in `ftm-inbox/backend/adapters/`:
+
+```python
+# ftm-inbox/backend/adapters/my_service.py
+from .base import BaseAdapter, InboxItem
+from typing import List
+
+class MyServiceAdapter(BaseAdapter):
+    name = "my_service"
+
+    async def fetch(self) -> List[InboxItem]:
+        # Hit your API, return a list of InboxItem objects
+        items = []
+        # ... your logic here ...
+        return items
+```
+
+2. Add credentials to `~/.claude/ftm-inbox/config.yml`:
+
+```yaml
+adapters:
+  my_service:
+    enabled: true
+    api_key: "your-key"
+    poll_interval_seconds: 60
+```
+
+3. Register it in `ftm-inbox/backend/adapters/__init__.py`:
+
+```python
+from .my_service import MyServiceAdapter
+ADAPTERS = [..., MyServiceAdapter]
+```
+
+4. Restart the service: `~/.claude/ftm-inbox/bin/stop.sh && ~/.claude/ftm-inbox/bin/start.sh`
+
+## Troubleshooting
+
+### Service won't start
+
+Check that Python 3 and uvicorn are installed:
+```bash
+python3 --version
+python3 -c "import uvicorn; print(uvicorn.__version__)"
+```
+
+If uvicorn is missing:
+```bash
+pip3 install -r ~/.claude/ftm-inbox/requirements.txt
+```
+
+### No items appearing in the dashboard
+
+1. Check the service is running: `~/.claude/ftm-inbox/bin/status.sh`
+2. Check logs: `tail -f ~/.claude/ftm-inbox/logs/*.log`
+3. Verify credentials in `~/.claude/ftm-inbox/config.yml`
+4. Confirm the adapter is set to `enabled: true`
+
+### Port conflict
+
+If port 8042 is already in use:
+```bash
+FTM_INBOX_PORT=9042 ~/.claude/ftm-inbox/bin/start.sh
+```
+
+Update `config.yml` to match so the dashboard connects to the right port.
+
+### Jira authentication errors
+
+Jira Cloud requires an API token, not your password. Generate one at:
+`https://id.atlassian.com/manage-profile/security/api-tokens`
+
+### Freshservice 403 errors
+
+Ensure the API key belongs to an agent with at least Viewer permissions on the relevant groups.
+
+### Re-running setup
+
+```bash
+node ~/.claude/ftm-inbox/bin/setup.mjs
+```
+
+This overwrites `~/.claude/ftm-inbox/config.yml` but does not touch the database.