@forwardimpact/outpost 3.0.3

package/src/kb-manager.js

@@ -0,0 +1,228 @@
+/**
+ * KBManager — knowledge base init/update operations.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  copyFileSync,
+  cpSync,
+  readFileSync,
+  writeFileSync,
+  readdirSync,
+} from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { homedir } from "node:os";
+import { createLogger } from "@forwardimpact/libtelemetry";
+
+const logger = createLogger("outpost");
+
+/** Manage knowledge base lifecycle including initialization, updates, and settings merging. */
+export class KBManager {
+  #fs;
+
+  /**
+   * @param {{ existsSync: Function, mkdirSync: Function, copyFileSync: Function, cpSync: Function, readFileSync: Function, writeFileSync: Function, readdirSync: Function }} fs
+   * @param {Function} logFn
+   */
+  constructor(fs, logFn) {
+    if (!fs) throw new Error("fs is required");
+    if (!logFn) throw new Error("logFn is required");
+    this.#fs = fs;
+  }
+
+  /**
+   * @param {string} dir
+   */
+  #ensureDir(dir) {
+    this.#fs.mkdirSync(dir, { recursive: true });
+  }
+
+  /**
+   * @param {string} path
+   * @param {*} fallback
+   * @returns {*}
+   */
+  #readJSON(path, fallback) {
+    try {
+      return JSON.parse(this.#fs.readFileSync(path, "utf8"));
+    } catch {
+      return fallback;
+    }
+  }
+
+  /**
+   * @param {string} path
+   * @param {*} data
+   */
+  #writeJSON(path, data) {
+    this.#ensureDir(dirname(path));
+    this.#fs.writeFileSync(path, JSON.stringify(data, null, 2) + "\n");
+  }
+
+  /**
+   * Copy bundled files (CLAUDE.md, skills, agents) from template to a KB.
+   * @param {string} tpl - Path to the template directory
+   * @param {string} dest - Path to the target knowledge base
+   */
+  copyBundledFiles(tpl, dest) {
+    this.#fs.copyFileSync(join(tpl, "CLAUDE.md"), join(dest, "CLAUDE.md"));
+    logger.info(`  Updated CLAUDE.md`);
+
+    const apmSrc = join(tpl, "apm.yml");
+    if (this.#fs.existsSync(apmSrc)) {
+      this.#fs.copyFileSync(apmSrc, join(dest, "apm.yml"));
+      logger.info(`  Updated apm.yml`);
+    }
+
+    this.mergeSettings(tpl, dest);
+
+    for (const sub of ["skills", "agents"]) {
+      const src = join(tpl, ".claude", sub);
+      if (!this.#fs.existsSync(src)) continue;
+      this.#fs.cpSync(src, join(dest, ".claude", sub), { recursive: true });
+      const entries = this.#fs
+        .readdirSync(src, { withFileTypes: true })
+        .filter((d) =>
+          sub === "skills" ? d.isDirectory() : d.name.endsWith(".md"),
+        );
+      const names = entries.map((d) =>
+        sub === "agents" ? d.name.replace(".md", "") : d.name,
+      );
+      logger.info(`  Updated ${names.length} ${sub}: ${names.join(", ")}`);
+    }
+  }
+
+  /**
+   * Merge new entries from a template permission list into an existing one.
+   * @param {Object} templatePerms - Template permissions object
+   * @param {Object} existingPerms - Existing permissions object (mutated)
+   * @returns {number} Number of entries added
+   */
+  #mergePermissionLists(templatePerms, existingPerms) {
+    let added = 0;
+    for (const key of ["allow", "deny", "additionalDirectories"]) {
+      if (!templatePerms[key]?.length) continue;
+      const set = new Set((existingPerms[key] ||= []));
+      for (const entry of templatePerms[key]) {
+        if (!set.has(entry)) {
+          existingPerms[key].push(entry);
+          set.add(entry);
+          added++;
+        }
+      }
+    }
+    if (templatePerms.defaultMode && !existingPerms.defaultMode) {
+      existingPerms.defaultMode = templatePerms.defaultMode;
+      added++;
+    }
+    return added;
+  }
+
+  /**
+   * Merge template settings.json into the destination's settings.json.
+   * @param {string} tpl - Template directory
+   * @param {string} dest - Knowledge base directory
+   */
+  mergeSettings(tpl, dest) {
+    const src = join(tpl, ".claude", "settings.json");
+    if (!this.#fs.existsSync(src)) return;
+
+    const destPath = join(dest, ".claude", "settings.json");
+
+    if (!this.#fs.existsSync(destPath)) {
+      this.#ensureDir(join(dest, ".claude"));
+      this.#fs.copyFileSync(src, destPath);
+      logger.info(`  Created settings.json`);
+      return;
+    }
+
+    const template = this.#readJSON(src, {});
+    const existing = this.#readJSON(destPath, {});
+    const added = this.#mergePermissionLists(
+      template.permissions || {},
+      (existing.permissions ||= {}),
+    );
+
+    if (added > 0) {
+      this.#writeJSON(destPath, existing);
+      logger.info(`  Updated settings.json (${added} new entries)`);
+    } else {
+      logger.info(`  Settings up to date`);
+    }
+  }
+
+  /**
+   * Initialize a new knowledge base
+   * @param {string} targetPath
+   * @param {string} templateDir
+   */
+  init(targetPath, templateDir) {
+    const dest = this.#expandPath(targetPath);
+    if (this.#fs.existsSync(join(dest, "CLAUDE.md"))) {
+      console.error(`Knowledge base already exists at ${dest}`);
+      process.exit(1);
+    }
+
+    this.#ensureDir(dest);
+    for (const d of [
+      "knowledge/People",
+      "knowledge/Organizations",
+      "knowledge/Projects",
+      "knowledge/Topics",
+      "knowledge/Briefings",
+    ])
+      this.#ensureDir(join(dest, d));
+
+    this.#fs.copyFileSync(join(templateDir, "USER.md"), join(dest, "USER.md"));
+
+    this.copyBundledFiles(templateDir, dest);
+
+    logger.info(
+      `Knowledge base initialized at ${dest}\n\nNext steps:\n  1. Edit ${dest}/USER.md with your name, email, and domain\n  2. cd ${dest} && npx apm install\n  3. claude`,
+    );
+  }
+
+  /**
+   * Update an existing knowledge base with the latest bundled files.
+   * @param {string} targetPath
+   * @param {string} templateDir
+   */
+  update(targetPath, templateDir) {
+    const dest = this.#expandPath(targetPath);
+    if (!this.#fs.existsSync(join(dest, "CLAUDE.md"))) {
+      console.error(`No knowledge base found at ${dest}`);
+      process.exit(1);
+    }
+    this.copyBundledFiles(templateDir, dest);
+    logger.info(`\nKnowledge base updated: ${dest}`);
+  }
+
+  /**
+   * @param {string} p
+   * @returns {string}
+   */
+  #expandPath(p) {
+    return p.startsWith("~/") ? join(homedir(), p.slice(2)) : resolve(p);
+  }
+}
+
+/**
+ * Create a KBManager with real fs dependencies
+ * @param {Function} logFn
+ * @returns {KBManager}
+ */
+export function createKBManager(logFn) {
+  return new KBManager(
+    {
+      existsSync,
+      mkdirSync,
+      copyFileSync,
+      cpSync,
+      readFileSync,
+      writeFileSync,
+      readdirSync,
+    },
+    logFn,
+  );
+}

package/src/outpost.js

@@ -0,0 +1,417 @@
+#!/usr/bin/env bun
+
+// Outpost — CLI and scheduler for autonomous agent teams.
+//
+// Usage:
+//   fit-outpost                     Wake due agents once and exit
+//   fit-outpost daemon              Run continuously (poll every 60s)
+//   fit-outpost wake <agent>        Wake a specific agent immediately
+//   fit-outpost init <path>         Initialize a new knowledge base
+//   fit-outpost update [path]       Update KB with latest CLAUDE.md, agents and skills
+//   fit-outpost stop                Gracefully stop daemon and all running agents
+//   fit-outpost validate            Validate agent definitions exist
+//   fit-outpost status              Show agent status
+//   fit-outpost --help              Show this help
+
+import {
+  readFileSync,
+  writeFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  copyFileSync,
+  cpSync,
+  appendFileSync,
+} from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { createCli } from "@forwardimpact/libcli";
+import { createLogger } from "@forwardimpact/libtelemetry";
+
+const logger = createLogger("outpost");
+
+import * as posixSpawn from "@forwardimpact/libmacos/posix-spawn";
+import { StateManager } from "./state-manager.js";
+import { AgentRunner } from "./agent-runner.js";
+import { Scheduler } from "./scheduler.js";
+import { KBManager } from "./kb-manager.js";
+import { SocketServer, requestShutdown } from "./socket-server.js";
+
+// --- Paths -------------------------------------------------------------------
+
+const HOME = homedir();
+const OUTPOST_HOME = join(HOME, ".fit", "outpost");
+const CONFIG_PATH = join(OUTPOST_HOME, "scheduler.json");
+const STATE_PATH = join(OUTPOST_HOME, "state.json");
+const LOG_DIR = join(OUTPOST_HOME, "logs");
+const CACHE_DIR = join(HOME, ".cache", "fit", "outpost");
+const __dirname =
+  import.meta.dirname || dirname(fileURLToPath(import.meta.url));
+const SHARE_DIR = "/usr/local/share/fit-outpost";
+const SOCKET_PATH = join(OUTPOST_HOME, "outpost.sock");
+
+// In compiled binaries (bun build --compile), `bun build --define` injects the
+// version string here so the readFileSync branch is eliminated as dead code.
+// Source execution (bun src/outpost.js) falls through to package.json.
+const VERSION =
+  process.env.OUTPOST_VERSION ||
+  JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf8"))
+    .version;
+
+// --- Logging -----------------------------------------------------------------
+
+function createFileLogger(logDir, fs) {
+  if (!logDir) throw new Error("logDir is required");
+  if (!fs) throw new Error("fs is required");
+  fs.mkdirSync(logDir, { recursive: true });
+  return function log(msg) {
+    const ts = new Date().toISOString();
+    const line = `[${ts}] ${msg}`;
+    logger.info(line);
+    fs.appendFileSync(
+      join(logDir, `scheduler-${ts.slice(0, 10)}.log`),
+      line + "\n",
+    );
+  };
+}
+
+const log = createFileLogger(LOG_DIR, { mkdirSync, appendFileSync });
+
+// --- Config ------------------------------------------------------------------
+
+function loadConfig() {
+  try {
+    return JSON.parse(readFileSync(CONFIG_PATH, "utf8"));
+  } catch {
+    return { agents: {} };
+  }
+}
+
+function expandPath(p) {
+  return p.startsWith("~/") ? join(HOME, p.slice(2)) : resolve(p);
+}
+
+// --- Wire dependencies -------------------------------------------------------
+
+const fsOps = { readFileSync, writeFileSync, mkdirSync };
+const stateManager = new StateManager(STATE_PATH, fsOps);
+const agentRunner = new AgentRunner(posixSpawn, stateManager, log, CACHE_DIR);
+const scheduler = new Scheduler(loadConfig, stateManager, agentRunner, log);
+const kbManager = new KBManager(
+  {
+    existsSync,
+    mkdirSync,
+    copyFileSync,
+    cpSync,
+    readFileSync,
+    writeFileSync,
+    readdirSync,
+  },
+  log,
+);
+
+// --- Template dir resolution -------------------------------------------------
+
+/**
+ * Detect if running from inside a macOS .app bundle.
+ * @returns {{ bundle: string, resources: string } | null}
+ */
+function getBundlePath() {
+  try {
+    const exe = process.execPath || "";
+    const macosDir = dirname(exe);
+    const contentsDir = dirname(macosDir);
+    const resourcesDir = join(contentsDir, "Resources");
+    if (existsSync(join(resourcesDir, "config"))) {
+      return { bundle: dirname(contentsDir), resources: resourcesDir };
+    }
+  } catch {
+    /* not in bundle */
+  }
+  return null;
+}
+
+function requireTemplateDir() {
+  const bundle = getBundlePath();
+  if (bundle) {
+    const tpl = join(bundle.resources, "templates");
+    if (existsSync(tpl)) return tpl;
+  }
+  for (const d of [
+    join(SHARE_DIR, "templates"),
+    join(__dirname, "..", "templates"),
+  ])
+    if (existsSync(d)) return d;
+  console.error("Template not found. Reinstall fit-outpost.");
+  process.exit(1);
+}
+
+// --- Daemon ------------------------------------------------------------------
+
+function daemon() {
+  const daemonStartedAt = Date.now();
+  log("Scheduler daemon started. Polling every 60 seconds.");
+  log(`Config: ${CONFIG_PATH}  State: ${STATE_PATH}`);
+
+  // Reset any agents left "active" from a previous daemon session.
+  const state = stateManager.load();
+  stateManager.resetStaleAgents(state, { reason: "Daemon restarted" }, log);
+
+  const socketServer = new SocketServer(
+    SOCKET_PATH,
+    scheduler,
+    agentRunner,
+    stateManager,
+    loadConfig,
+    log,
+    CACHE_DIR,
+    daemonStartedAt,
+  );
+  socketServer.start();
+
+  async function tick() {
+    try {
+      await scheduler.wakeDueAgents();
+    } catch (err) {
+      log(`Error: ${err.message}`);
+    }
+    setTimeout(tick, 60_000);
+  }
+  tick();
+}
+
+// --- Update ------------------------------------------------------------------
+
+function runUpdate(args) {
+  if (args[0]) {
+    kbManager.update(args[0], requireTemplateDir());
+    return;
+  }
+
+  const config = loadConfig();
+  const kbPaths = [
+    ...new Set(
+      Object.values(config.agents)
+        .filter((a) => a.kb)
+        .map((a) => expandPath(a.kb)),
+    ),
+  ];
+
+  if (kbPaths.length === 0) {
+    console.error(
+      "No knowledge bases configured and no path given.\n" +
+        "Usage: fit-outpost update [path]",
+    );
+    process.exit(1);
+  }
+
+  for (const kb of kbPaths) {
+    logger.info(`\nUpdating ${kb}...`);
+    kbManager.update(kb, requireTemplateDir());
+  }
+}
+
+// --- Status ------------------------------------------------------------------
+
+function formatAgentStatus(name, agent, s) {
+  const enabledMark = agent.enabled !== false ? "+" : "-";
+  const kbStatus =
+    agent.kb && !existsSync(expandPath(agent.kb)) ? " (not found)" : "";
+  const lastWake = s.lastWokeAt
+    ? new Date(s.lastWokeAt).toLocaleString()
+    : "never";
+  const lines = [
+    `  ${enabledMark} ${name}`,
+    `    KB: ${agent.kb || "(none)"}${kbStatus}  Schedule: ${JSON.stringify(agent.schedule)}`,
+    `    Status: ${s.status || "never-woken"}  Last wake: ${lastWake}  Wakes: ${s.wakeCount || 0}`,
+  ];
+  if (s.lastAction) lines.push(`    Last action: ${s.lastAction}`);
+  if (s.lastDecision) lines.push(`    Last decision: ${s.lastDecision}`);
+  if (s.lastError) lines.push(`    Error: ${s.lastError.slice(0, 80)}`);
+  return lines.join("\n");
+}
+
+function showStatus() {
+  const config = loadConfig();
+  const state = stateManager.load();
+  logger.info("\nOutpost Scheduler\n==================\n");
+
+  const agents = Object.entries(config.agents || {});
+  if (agents.length === 0) {
+    logger.info(`No agents configured.\n\nEdit ${CONFIG_PATH} to add agents.`);
+    return;
+  }
+
+  logger.info("Agents:");
+  for (const [name, agent] of agents) {
+    logger.info(formatAgentStatus(name, agent, state.agents[name] || {}));
+  }
+}
+
+// --- Validate ----------------------------------------------------------------
+
+function findInLocalOrGlobal(kbPath, subPath) {
+  const local = join(kbPath, ".claude", subPath);
+  const global = join(HOME, ".claude", subPath);
+  if (existsSync(local)) return local;
+  if (existsSync(global)) return global;
+  return null;
+}
+
+/**
+ * Validate a single agent's configuration.
+ * @param {string} name
+ * @param {Object} agent
+ * @returns {boolean} true if valid
+ */
+function validateAgent(name, agent) {
+  if (!agent.kb) {
+    logger.info(`  [FAIL] ${name}: no "kb" path specified`);
+    return false;
+  }
+  const kbPath = expandPath(agent.kb);
+  if (!existsSync(kbPath)) {
+    logger.info(`  [FAIL] ${name}: path not found: ${kbPath}`);
+    return false;
+  }
+
+  const agentFile = join("agents", name + ".md");
+  const found = findInLocalOrGlobal(kbPath, agentFile);
+  logger.info(
+    `  [${found ? "OK" : "FAIL"}]  ${name}: agent definition${found ? "" : " not found"}`,
+  );
+  return !!found;
+}
+
+function validate() {
+  const config = loadConfig();
+  const agents = Object.entries(config.agents || {});
+  if (agents.length === 0) {
+    logger.info("No agents configured. Nothing to validate.");
+    return;
+  }
+
+  logger.info("\nValidating agents...\n");
+  let errors = 0;
+
+  for (const [name, agent] of agents) {
+    if (!validateAgent(name, agent)) errors++;
+  }
+
+  logger.info(errors > 0 ? `\n${errors} error(s).` : "\nAll OK.");
+  if (errors > 0) process.exit(1);
+}
+
+// --- CLI definition ----------------------------------------------------------
+
+const definition = {
+  name: "fit-outpost",
+  version: VERSION,
+  description: "Schedule autonomous agents across knowledge bases",
+  commands: [
+    { name: "daemon", description: "Run continuously (poll every 60s)" },
+    {
+      name: "wake",
+      args: "<agent>",
+      description: "Wake a specific agent immediately",
+    },
+    {
+      name: "init",
+      args: "<path>",
+      description: "Initialize a new knowledge base",
+    },
+    {
+      name: "update",
+      args: "[path]",
+      description: "Update KB with latest CLAUDE.md, agents and skills",
+    },
+    {
+      name: "stop",
+      description: "Gracefully stop daemon and all running agents",
+    },
+    { name: "validate", description: "Validate agent definitions exist" },
+    { name: "status", description: "Show agent status" },
+  ],
+  globalOptions: {
+    help: { type: "boolean", short: "h", description: "Show this help" },
+    version: { type: "boolean", description: "Show version" },
+    json: { type: "boolean", description: "JSON output (with --help)" },
+  },
+  documentation: [
+    {
+      title: "Outpost Overview",
+      url: "https://www.forwardimpact.team/outpost/index.md",
+      description: "Product overview, audience model, and key concepts.",
+    },
+    {
+      title: "Getting Started: Outpost for Engineers",
+      url: "https://www.forwardimpact.team/docs/getting-started/engineers/outpost/index.md",
+      description: "From zero to your first daily briefing.",
+    },
+    {
+      title: "Keep Track of Context Without Effort",
+      url: "https://www.forwardimpact.team/docs/products/knowledge-systems/index.md",
+      description:
+        "Maintain continuous awareness of people, projects, and threads.",
+    },
+    {
+      title: "Walk Into Every Meeting Already Oriented",
+      url: "https://www.forwardimpact.team/docs/products/knowledge-systems/meeting-prep/index.md",
+      description: "Assemble context so you arrive prepared.",
+    },
+  ],
+};
+
+// --- CLI entry point ---------------------------------------------------------
+
+const cli = createCli(definition);
+const parsed = cli.parse(process.argv.slice(2));
+if (!parsed) process.exit(0);
+
+const { positionals } = parsed;
+const [command, ...args] = positionals;
+
+mkdirSync(OUTPOST_HOME, { recursive: true });
+
+const COMMANDS = {
+  daemon,
+  wake: async () => {
+    if (!args[0]) {
+      cli.usageError("missing required argument <agent>");
+      process.exit(2);
+    }
+    const config = loadConfig();
+    const state = stateManager.load();
+    const agent = config.agents[args[0]];
+    if (!agent) {
+      cli.error(
+        `agent "${args[0]}" not found. Available: ${Object.keys(config.agents).join(", ") || "(none)"}`,
+      );
+      process.exit(1);
+    }
+    await agentRunner.wake(args[0], agent, state);
+  },
+  init: () => {
+    if (!args[0]) {
+      cli.usageError("missing required argument <path>");
+      process.exit(2);
+    }
+    kbManager.init(args[0], requireTemplateDir());
+  },
+  update: () => runUpdate(args),
+  stop: async () => {
+    const stopped = await requestShutdown(SOCKET_PATH);
+    if (!stopped) process.exit(1);
+  },
+  validate,
+  status: showStatus,
+};
+
+const handler = COMMANDS[command];
+if (command && !handler) {
+  cli.usageError(`unknown command "${command}"`);
+  process.exit(2);
+}
+
+await (handler || (() => scheduler.wakeDueAgents()))();