@forwardimpact/outpost 3.1.3 → 3.2.0

package/bin/fit-outpost.js

@@ -1,5 +1,17 @@
 #!/usr/bin/env node
-// Thin entry point — delegates to src/outpost.js.
+// Thin entry point — the sole construction site for the runtime collaborator
+// bag, threaded into src/outpost.js's dispatch via run(runtime, version).
 import "@forwardimpact/libpreflight/node22";
 
-import "../src/outpost.js";
+import { resolveVersion } from "@forwardimpact/libcli";
+import { createDefaultRuntime } from "@forwardimpact/libutil/runtime";
+
+import { run } from "../src/outpost.js";
+
+const runtime = createDefaultRuntime();
+const version = resolveVersion({
+  packageJsonUrl: new URL("../package.json", import.meta.url),
+  runtime,
+});
+const code = await run(runtime, version);
+if (code) runtime.proc.exit(code);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/outpost",
-  "version": "3.1.3",
+  "version": "3.2.0",
   "description": "Personal operations center — context from email, calendar, and knowledge assembled so preparation is continuous, not a morning scramble.",
   "homepage": "https://www.forwardimpact.team",
   "repository": {
@@ -50,17 +50,23 @@
   },
   "dependencies": {
     "@forwardimpact/libcli": "^0.1.0",
-    "@forwardimpact/libmacos": "^0.1.0",
     "@forwardimpact/libpreflight": "^0.1.0",
-    "@forwardimpact/libtelemetry": "^0.1.33"
+    "@forwardimpact/libtelemetry": "^0.1.33",
+    "@forwardimpact/libutil": "^0.1.0"
   },
   "devDependencies": {
     "@forwardimpact/libmock": "^0.1.0"
   },
+  "optionalDependencies": {
+    "@forwardimpact/libmacos": "^0.1.0"
+  },
   "engines": {
     "bun": ">=1.2.0",
     "node": ">=22.0.0"
   },
+  "os": [
+    "darwin"
+  ],
   "publishConfig": {
     "access": "public"
   }

package/src/agent-runner.js

@@ -2,9 +2,9 @@
  * AgentRunner — spawn agent process, capture output, update state.
  */
 
-import { existsSync } from "node:fs";
 import { resolve, join } from "node:path";
 import { homedir } from "node:os";
+import { isoTimestamp } from "@forwardimpact/libutil";
 
 /** Spawn agent CLI processes, capture their output, and update agent state. */
 export class AgentRunner {
@@ -13,22 +13,38 @@ export class AgentRunner {
   #log;
   #activeChildren;
   #cacheDir;
+  #fs;
+  #proc;
+  #clock;
+  #runtime;
 
   /**
-   * @param {Object} spawn - posix-spawn module
+   * @param {Object | (() => Object | Promise<{default?: Object}>)} spawn -
+   *   The posix-spawn module, or a (possibly async) loader returning it. A
+   *   loader lets the Bun-FFI module load lazily so plain `node` invocations
+   *   that never wake an agent don't pull in `bun:ffi`.
    * @param {import('./state-manager.js').StateManager} stateManager
    * @param {Function} logFn - Logging function
    * @param {string} cacheDir - Cache directory for state files
+   * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
+   *   Injected runtime bag (uses `fs` (async), `proc`, `clock`).
    */
-  constructor(spawn, stateManager, logFn, cacheDir) {
+  constructor(spawn, stateManager, logFn, cacheDir, runtime) {
     if (!spawn) throw new Error("spawn is required");
     if (!stateManager) throw new Error("stateManager is required");
     if (!logFn) throw new Error("logFn is required");
     if (!cacheDir) throw new Error("cacheDir is required");
+    if (!runtime?.fs) throw new Error("runtime.fs is required");
+    if (!runtime?.proc) throw new Error("runtime.proc is required");
+    if (!runtime?.clock) throw new Error("runtime.clock is required");
     this.#spawn = spawn;
     this.#stateManager = stateManager;
     this.#log = logFn;
     this.#cacheDir = cacheDir;
+    this.#fs = runtime.fs;
+    this.#proc = runtime.proc;
+    this.#clock = runtime.clock;
+    this.#runtime = runtime;
     this.#activeChildren = new Set();
   }
 
@@ -37,11 +53,36 @@ export class AgentRunner {
     return this.#activeChildren;
   }
 
+  /**
+   * Resolve the injected spawn collaborator to the posix-spawn module,
+   * invoking and unwrapping a loader thunk on first use.
+   * @returns {Promise<Object>}
+   */
+  async #resolveSpawn() {
+    if (typeof this.#spawn === "function" && !this.#spawn.spawn) {
+      const loaded = await this.#spawn();
+      this.#spawn = loaded?.spawn ? loaded : (loaded?.default ?? loaded);
+    }
+    return this.#spawn;
+  }
+
+  /**
+   * Test whether a path exists, via the async fs surface.
+   * @param {string} p
+   * @returns {Promise<boolean>}
+   */
+  async #exists(p) {
+    return this.#fs.access(p).then(
+      () => true,
+      () => false,
+    );
+  }
+
   /**
    * Find the claude CLI binary
-   * @returns {string}
+   * @returns {Promise<string>}
    */
-  #findClaude() {
+  async #findClaude() {
     const HOME = homedir();
     const paths = [
       "/usr/local/bin/claude",
@@ -49,7 +90,7 @@ export class AgentRunner {
       join(HOME, ".local", "bin", "claude"),
       "/opt/homebrew/bin/claude",
     ];
-    for (const p of paths) if (existsSync(p)) return p;
+    for (const p of paths) if (await this.#exists(p)) return p;
     return "claude";
   }
 
@@ -71,7 +112,7 @@ export class AgentRunner {
     Object.assign(agentState, {
       status: "failed",
       startedAt: null,
-      lastWokeAt: new Date().toISOString(),
+      lastWokeAt: isoTimestamp(this.#clock.now()),
       lastError: String(error).slice(0, 500),
     });
   }
@@ -84,7 +125,7 @@ export class AgentRunner {
    * @returns {Record<string, string>}
    */
   #buildSpawnEnv(configEnv) {
-    const env = { ...process.env };
+    const env = { ...this.#proc.env };
     if (configEnv) {
       const home = homedir();
       for (const [key, value] of Object.entries(configEnv)) {
@@ -108,21 +149,21 @@ export class AgentRunner {
       return;
     }
     const kbPath = this.#expandPath(agent.kb);
-    if (!existsSync(kbPath)) {
+    if (!(await this.#exists(kbPath))) {
       this.#log(
         `Agent ${agentName}: path "${kbPath}" does not exist, skipping.`,
       );
       return;
     }
 
-    const claude = this.#findClaude();
+    const claude = await this.#findClaude();
 
     this.#log(`Waking agent: ${agentName} (kb: ${agent.kb})`);
 
     const as = (state.agents[agentName] ||= {});
     as.status = "active";
-    as.startedAt = new Date().toISOString();
-    this.#stateManager.save(state);
+    as.startedAt = isoTimestamp(this.#clock.now());
+    await this.#stateManager.save(state);
 
     const spawnArgs = [
       "--chrome",
@@ -134,27 +175,33 @@ export class AgentRunner {
     ];
 
     const env = this.#buildSpawnEnv(configEnv);
+    const spawnMod = await this.#resolveSpawn();
 
     try {
-      const { pid, stdoutFile, stderrFile } = this.#spawn.spawn(
+      const { pid, stdoutFile, stderrFile } = spawnMod.spawn(
         claude,
         spawnArgs,
         env,
         kbPath,
+        this.#runtime,
       );
       this.#activeChildren.add(pid);
 
-      const exitCode = await this.#spawn.waitForExit(pid);
+      const exitCode = await spawnMod.waitForExit(
+        pid,
+        undefined,
+        this.#runtime,
+      );
       this.#activeChildren.delete(pid);
 
-      const stdout = this.#spawn.readOutput(stdoutFile);
-      const stderr = this.#spawn.readOutput(stderrFile);
+      const stdout = spawnMod.readOutput(stdoutFile, this.#runtime);
+      const stderr = spawnMod.readOutput(stderrFile, this.#runtime);
 
       if (exitCode === 0) {
         this.#log(
           `Agent ${agentName} completed. Output: ${stdout.slice(0, 200)}...`,
         );
-        this.#stateManager.updateAgentState(
+        await this.#stateManager.updateAgentState(
           as,
           stdout,
           agentName,
@@ -169,7 +216,7 @@ export class AgentRunner {
       this.#log(`Agent ${agentName} failed: ${err.message}`);
       this.#failAgent(as, err.message);
     }
-    this.#stateManager.save(state);
+    await this.#stateManager.save(state);
   }
 
   /**
@@ -178,7 +225,7 @@ export class AgentRunner {
   killActiveChildren() {
     for (const pid of this.#activeChildren) {
       try {
-        process.kill(pid, "SIGTERM");
+        this.#proc.kill(pid, "SIGTERM");
         this.#log(`Sent SIGTERM to child PID ${pid}`);
       } catch {
         // Already exited

package/src/kb-manager.js

@@ -2,50 +2,55 @@
  * 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;
+  #logger;
 
   /**
-   * @param {{ existsSync: Function, mkdirSync: Function, copyFileSync: Function, cpSync: Function, readFileSync: Function, writeFileSync: Function, readdirSync: Function }} fs
+   * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
+   *   Injected runtime bag (uses `fs` (async)).
    * @param {Function} logFn
    */
-  constructor(fs, logFn) {
-    if (!fs) throw new Error("fs is required");
+  constructor(runtime, logFn) {
+    if (!runtime?.fs) throw new Error("runtime.fs is required");
     if (!logFn) throw new Error("logFn is required");
-    this.#fs = fs;
+    this.#fs = runtime.fs;
+    this.#logger = createLogger("outpost", runtime);
+  }
+
+  /**
+   * Test whether a path exists, via the async fs surface.
+   * @param {string} p
+   * @returns {Promise<boolean>}
+   */
+  async #exists(p) {
+    return this.#fs.access(p).then(
+      () => true,
+      () => false,
+    );
   }
 
   /**
    * @param {string} dir
+   * @returns {Promise<void>}
    */
-  #ensureDir(dir) {
-    this.#fs.mkdirSync(dir, { recursive: true });
+  async #ensureDir(dir) {
+    await this.#fs.mkdir(dir, { recursive: true });
   }
 
   /**
    * @param {string} path
    * @param {*} fallback
-   * @returns {*}
+   * @returns {Promise<*>}
    */
-  #readJSON(path, fallback) {
+  async #readJSON(path, fallback) {
     try {
-      return JSON.parse(this.#fs.readFileSync(path, "utf8"));
+      return JSON.parse(await this.#fs.readFile(path, "utf8"));
     } catch {
       return fallback;
     }
@@ -54,42 +59,46 @@ export class KBManager {
   /**
    * @param {string} path
    * @param {*} data
+   * @returns {Promise<void>}
    */
-  #writeJSON(path, data) {
-    this.#ensureDir(dirname(path));
-    this.#fs.writeFileSync(path, JSON.stringify(data, null, 2) + "\n");
+  async #writeJSON(path, data) {
+    await this.#ensureDir(dirname(path));
+    await this.#fs.writeFile(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
+   * @returns {Promise<void>}
    */
-  copyBundledFiles(tpl, dest) {
-    this.#fs.copyFileSync(join(tpl, "CLAUDE.md"), join(dest, "CLAUDE.md"));
-    logger.info(`  Updated CLAUDE.md`);
+  async copyBundledFiles(tpl, dest) {
+    await this.#fs.copyFile(join(tpl, "CLAUDE.md"), join(dest, "CLAUDE.md"));
+    this.#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`);
+    if (await this.#exists(apmSrc)) {
+      await this.#fs.copyFile(apmSrc, join(dest, "apm.yml"));
+      this.#logger.info(`  Updated apm.yml`);
     }
 
-    this.mergeSettings(tpl, dest);
+    await 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"),
-        );
+      if (!(await this.#exists(src))) continue;
+      await this.#fs.cp(src, join(dest, ".claude", sub), { recursive: true });
+      const entries = (
+        await this.#fs.readdir(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(", ")}`);
+      this.#logger.info(
+        `  Updated ${names.length} ${sub}: ${names.join(", ")}`,
+      );
     }
   }
 
@@ -123,48 +132,53 @@ export class KBManager {
    * Merge template settings.json into the destination's settings.json.
    * @param {string} tpl - Template directory
    * @param {string} dest - Knowledge base directory
+   * @returns {Promise<void>}
    */
-  mergeSettings(tpl, dest) {
+  async mergeSettings(tpl, dest) {
     const src = join(tpl, ".claude", "settings.json");
-    if (!this.#fs.existsSync(src)) return;
+    if (!(await this.#exists(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`);
+    if (!(await this.#exists(destPath))) {
+      await this.#ensureDir(join(dest, ".claude"));
+      await this.#fs.copyFile(src, destPath);
+      this.#logger.info(`  Created settings.json`);
       return;
     }
 
-    const template = this.#readJSON(src, {});
-    const existing = this.#readJSON(destPath, {});
+    const template = await this.#readJSON(src, {});
+    const existing = await 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)`);
+      await this.#writeJSON(destPath, existing);
+      this.#logger.info(`  Updated settings.json (${added} new entries)`);
     } else {
-      logger.info(`  Settings up to date`);
+      this.#logger.info(`  Settings up to date`);
     }
   }
 
   /**
-   * Initialize a new knowledge base
+   * Initialize a new knowledge base.
    * @param {string} targetPath
    * @param {string} templateDir
+   * @returns {Promise<{ok: true, value: {dest: string}} | {ok: false, code: number, error: string}>}
    */
-  init(targetPath, templateDir) {
+  async 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);
+    if (await this.#exists(join(dest, "CLAUDE.md"))) {
+      return {
+        ok: false,
+        code: 1,
+        error: `Knowledge base already exists at ${dest}`,
+      };
     }
 
-    this.#ensureDir(dest);
+    await this.#ensureDir(dest);
     for (const d of [
       "knowledge/People",
       "knowledge/Organizations",
@@ -172,30 +186,39 @@ export class KBManager {
       "knowledge/Topics",
       "knowledge/Briefings",
     ])
-      this.#ensureDir(join(dest, d));
+      await this.#ensureDir(join(dest, d));
 
-    this.#fs.copyFileSync(join(templateDir, "USER.md"), join(dest, "USER.md"));
+    await this.#fs.copyFile(
+      join(templateDir, "USER.md"),
+      join(dest, "USER.md"),
+    );
 
-    this.copyBundledFiles(templateDir, dest);
+    await this.copyBundledFiles(templateDir, dest);
 
-    logger.info(
+    this.#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`,
     );
+    return { ok: true, value: { dest } };
   }
 
   /**
    * Update an existing knowledge base with the latest bundled files.
    * @param {string} targetPath
    * @param {string} templateDir
+   * @returns {Promise<{ok: true, value: {dest: string}} | {ok: false, code: number, error: string}>}
    */
-  update(targetPath, templateDir) {
+  async 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);
+    if (!(await this.#exists(join(dest, "CLAUDE.md")))) {
+      return {
+        ok: false,
+        code: 1,
+        error: `No knowledge base found at ${dest}`,
+      };
     }
-    this.copyBundledFiles(templateDir, dest);
-    logger.info(`\nKnowledge base updated: ${dest}`);
+    await this.copyBundledFiles(templateDir, dest);
+    this.#logger.info(`\nKnowledge base updated: ${dest}`);
+    return { ok: true, value: { dest } };
   }
 
   /**
@@ -206,23 +229,3 @@ export class KBManager {
     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,
-  );
-}