foundr-companion 0.1.0

package/dist/launchd.js

@@ -0,0 +1,118 @@
+/**
+ * macOS LaunchAgent (launchd) support for the Foundr Companion daemon.
+ *
+ * Renders the per-user `.plist` and wraps the *modern* `launchctl` domain API
+ * (`enable` / `bootstrap` / `bootout` / `kickstart` / `print`). Shape mirrors the
+ * proven OpenClaw gateway LaunchAgent.
+ *
+ * Critical invariants baked into the plist:
+ * - `RunAtLoad` true so the daemon comes up at login.
+ * - `KeepAlive` is `{ SuccessfulExit: false }` — restart on crash, but DON'T
+ *   hot-loop a clean exit (a deliberate config-error exit should stay down).
+ * - `EnvironmentVariables` ALWAYS carries `FOUNDR_CODEX_THREAD_MODE=bridge`. A
+ *   launchd job has no `CODEX_THREAD_ID`, so resume mode would crash on boot.
+ * - All interpolated paths are ABSOLUTE — launchd starts jobs with a minimal env
+ *   and no working directory inheritance.
+ */
+import { execFile as nodeExecFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const defaultExecFile = promisify(nodeExecFile);
+/** XML-escape a value for safe interpolation into plist `<string>` / `<key>`. */
+function plistEscape(value) {
+    return value
+        .replaceAll('&', '&amp;')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;')
+        .replaceAll("'", '&apos;');
+}
+/**
+ * Build the LaunchAgent plist XML. Pure — no filesystem or process access.
+ */
+export function renderLaunchAgentPlist({ label, nodePath, cliJsPath, paths, env, }) {
+    const programArguments = [nodePath, cliJsPath, 'run'];
+    const argsXml = programArguments
+        .map((arg) => `\n      <string>${plistEscape(arg)}</string>`)
+        .join('');
+    // FOUNDR_CODEX_THREAD_MODE=bridge first, then caller-provided keys. A caller
+    // key of the same name overrides, but the default guarantees presence.
+    const environment = Object.assign({ FOUNDR_CODEX_THREAD_MODE: 'bridge' }, (env !== null && env !== void 0 ? env : {}));
+    const envXml = Object.entries(environment)
+        .map(([key, value]) => `\n      <key>${plistEscape(key)}</key>\n      <string>${plistEscape(value)}</string>`)
+        .join('');
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+  <dict>
+    <key>Label</key>
+    <string>${plistEscape(label)}</string>
+    <key>ProgramArguments</key>
+    <array>${argsXml}
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <dict>
+      <key>SuccessfulExit</key>
+      <false/>
+    </dict>
+    <key>ThrottleInterval</key>
+    <integer>10</integer>
+    <key>ExitTimeOut</key>
+    <integer>20</integer>
+    <key>ProcessType</key>
+    <string>Interactive</string>
+    <key>StandardInPath</key>
+    <string>/dev/null</string>
+    <key>StandardOutPath</key>
+    <string>${plistEscape(paths.logFile)}</string>
+    <key>StandardErrorPath</key>
+    <string>${plistEscape(paths.errLogFile)}</string>
+    <key>EnvironmentVariables</key>
+    <dict>${envXml}
+    </dict>
+  </dict>
+</plist>
+`;
+}
+/** Default GUI domain uid — the current process uid on a real macOS session. */
+function defaultUid() {
+    return typeof process.getuid === 'function' ? process.getuid() : 501;
+}
+/**
+ * Enable + bootstrap the LaunchAgent into the user's GUI domain.
+ *   launchctl enable   gui/<uid>/<label>
+ *   launchctl bootstrap gui/<uid> <plistPath>
+ */
+export async function installLaunchAgent({ plistPath, label, uid = defaultUid(), execFile = defaultExecFile, }) {
+    await execFile('launchctl', ['enable', `gui/${uid}/${label}`]);
+    await execFile('launchctl', ['bootstrap', `gui/${uid}`, plistPath]);
+}
+/**
+ * Tear the LaunchAgent out of the GUI domain.
+ *   launchctl bootout gui/<uid>/<label>
+ */
+export async function uninstallLaunchAgent({ label, uid = defaultUid(), execFile = defaultExecFile, }) {
+    await execFile('launchctl', ['bootout', `gui/${uid}/${label}`]);
+}
+/**
+ * Restart the running service in place.
+ *   launchctl kickstart -k gui/<uid>/<label>
+ */
+export async function restartLaunchAgent({ label, uid = defaultUid(), execFile = defaultExecFile, }) {
+    await execFile('launchctl', ['kickstart', '-k', `gui/${uid}/${label}`]);
+}
+/**
+ * Whether the LaunchAgent is bootstrapped (loaded) in the GUI domain.
+ *   launchctl print gui/<uid>/<label>   (exit 0 => loaded)
+ */
+export async function isLaunchAgentLoaded({ label, uid = defaultUid(), execFile = defaultExecFile, }) {
+    try {
+        await execFile('launchctl', ['print', `gui/${uid}/${label}`]);
+        return true;
+    }
+    catch (_a) {
+        return false;
+    }
+}
+//# sourceMappingURL=launchd.js.map

package/dist/launchd.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"launchd.js","sourceRoot":"","sources":["../src/launchd.ts"],"names":[],"mappings":"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"}

package/dist/paths.d.ts

@@ -0,0 +1,30 @@
+/** Reverse-DNS LaunchAgent label for the companion daemon. */
+export declare const LAUNCH_AGENT_LABEL = "world.foundr.companion";
+/**
+ * Canonical on-disk locations for the Foundr Companion.
+ *
+ * - `installRoot` (~/.foundr) is companion-owned scratch: logs, status, the
+ *   `bin/foundr` shim. The npm-global package itself lives wherever npm put it.
+ * - `configDir` (~/.foundr-world) is shared with the legacy CLI bridge and holds
+ *   the OAuth tokens (`bridge-auth.json`, 0600) and the Codex bridge thread id.
+ * - `launchAgentPlist` is the per-user LaunchAgent.
+ *
+ * Everything is derived from `home` so it is trivially testable.
+ */
+export interface CompanionPaths {
+    home: string;
+    installRoot: string;
+    binDir: string;
+    binShim: string;
+    logsDir: string;
+    logFile: string;
+    errLogFile: string;
+    statusFile: string;
+    configDir: string;
+    authFile: string;
+    codexThreadStore: string;
+    launchAgentsDir: string;
+    launchAgentPlist: string;
+}
+export declare function companionPaths(home?: string): CompanionPaths;
+//# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAGA,8DAA8D;AAC9D,eAAO,MAAM,kBAAkB,2BAA2B,CAAA;AAE1D;;;;;;;;;;GAUG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,gBAAgB,EAAE,MAAM,CAAA;IACxB,eAAe,EAAE,MAAM,CAAA;IACvB,gBAAgB,EAAE,MAAM,CAAA;CACzB;AAED,wBAAgB,cAAc,CAAC,IAAI,GAAE,MAAqB,GAAG,cAAc,CAoB1E"}

package/dist/paths.js

@@ -0,0 +1,26 @@
+import os from 'node:os';
+import path from 'node:path';
+/** Reverse-DNS LaunchAgent label for the companion daemon. */
+export const LAUNCH_AGENT_LABEL = 'world.foundr.companion';
+export function companionPaths(home = os.homedir()) {
+    const installRoot = path.join(home, '.foundr');
+    const logsDir = path.join(installRoot, 'logs');
+    const configDir = path.join(home, '.foundr-world');
+    const launchAgentsDir = path.join(home, 'Library', 'LaunchAgents');
+    return {
+        home,
+        installRoot,
+        binDir: path.join(installRoot, 'bin'),
+        binShim: path.join(installRoot, 'bin', 'foundr'),
+        logsDir,
+        logFile: path.join(logsDir, 'companion.log'),
+        errLogFile: path.join(logsDir, 'companion.err.log'),
+        statusFile: path.join(installRoot, 'status.json'),
+        configDir,
+        authFile: path.join(configDir, 'bridge-auth.json'),
+        codexThreadStore: path.join(configDir, 'codex-bridge-thread.json'),
+        launchAgentsDir,
+        launchAgentPlist: path.join(launchAgentsDir, `${LAUNCH_AGENT_LABEL}.plist`),
+    };
+}
+//# sourceMappingURL=paths.js.map

package/dist/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAA;AACxB,OAAO,IAAI,MAAM,WAAW,CAAA;AAE5B,8DAA8D;AAC9D,MAAM,CAAC,MAAM,kBAAkB,GAAG,wBAAwB,CAAA;AA6B1D,MAAM,UAAU,cAAc,CAAC,OAAe,EAAE,CAAC,OAAO,EAAE;IACxD,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,CAAA;IAC9C,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,CAAA;IAC9C,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,eAAe,CAAC,CAAA;IAClD,MAAM,eAAe,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,cAAc,CAAC,CAAA;IAClE,OAAO;QACL,IAAI;QACJ,WAAW;QACX,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC;QACrC,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,EAAE,QAAQ,CAAC;QAChD,OAAO;QACP,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,eAAe,CAAC;QAC5C,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,mBAAmB,CAAC;QACnD,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,aAAa,CAAC;QACjD,SAAS;QACT,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,kBAAkB,CAAC;QAClD,gBAAgB,EAAE,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,0BAA0B,CAAC;QAClE,eAAe;QACf,gBAAgB,EAAE,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,GAAG,kBAAkB,QAAQ,CAAC;KAC5E,CAAA;AACH,CAAC"}

package/install.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Foundr Companion installer.
+#
+#   curl -fsSL https://www.foundr.world/install.sh | bash
+#
+# Installs the `foundr-companion` npm package globally, wires up the per-user
+# LaunchAgent (`foundr install`), runs the Codex preflight (`foundr codex`),
+# and prints next steps. Idempotent: re-running upgrades in place.
+#
+# The entire body lives in main() and is only invoked on the very last line,
+# so a truncated download can never execute a half-written script.
+
+main() {
+  FOUNDR_VERSION="${FOUNDR_VERSION:-latest}"
+  FOUNDR_URL="${FOUNDR_URL:-https://www.foundr.world}"
+
+  say() { printf 'foundr> %s\n' "$1"; }
+  warn() { printf 'foundr! %s\n' "$1" >&2; }
+  die() { printf 'foundr x %s\n' "$1" >&2; exit 1; }
+
+  say "Installing Foundr Companion (version: ${FOUNDR_VERSION})"
+  say "Origin: ${FOUNDR_URL}"
+
+  # --- (2) Ensure Node >= 22.19 ------------------------------------------
+  need_node_install=0
+  if ! command -v node >/dev/null 2>&1; then
+    warn "Node.js not found."
+    need_node_install=1
+  else
+    node_version="$(node -v 2>/dev/null | sed 's/^v//')"
+    node_major="${node_version%%.*}"
+    rest="${node_version#*.}"
+    node_minor="${rest%%.*}"
+    case "$node_major" in
+      ''|*[!0-9]*) node_major=0 ;;
+    esac
+    case "$node_minor" in
+      ''|*[!0-9]*) node_minor=0 ;;
+    esac
+    if [ "$node_major" -lt 22 ] || { [ "$node_major" -eq 22 ] && [ "$node_minor" -lt 19 ]; }; then
+      warn "Node ${node_version} is too old (need >= 22.19)."
+      need_node_install=1
+    else
+      say "Node ${node_version} OK (>= 22.19)."
+    fi
+  fi
+
+  if [ "$need_node_install" -eq 1 ]; then
+    if [ "$(uname -s)" = "Darwin" ] && command -v brew >/dev/null 2>&1; then
+      say "Installing Node via Homebrew (brew install node)..."
+      brew install node
+    else
+      die "Please install Node.js >= 22.19 from https://nodejs.org and re-run this installer."
+    fi
+    command -v node >/dev/null 2>&1 || die "Node still not on PATH after install. Open a new shell and re-run."
+  fi
+
+  # --- (2b) Ensure a writable npm global prefix (never sudo) -------------
+  warn_no_sudo() { warn "Never run 'sudo npm -g' — it leaves root-owned files in your home dir. We are fixing the prefix instead."; }
+
+  npm_prefix="$(npm config get prefix 2>/dev/null || echo '')"
+  prefix_writable=1
+  if [ -n "$npm_prefix" ] && [ -d "$npm_prefix" ]; then
+    if [ ! -w "$npm_prefix" ]; then prefix_writable=0; fi
+  elif [ -n "$npm_prefix" ]; then
+    parent="$(dirname "$npm_prefix")"
+    if [ ! -w "$parent" ]; then prefix_writable=0; fi
+  fi
+
+  if [ "$prefix_writable" -eq 0 ]; then
+    warn_no_sudo
+    user_prefix="$HOME/.npm-global"
+    say "npm global prefix ('$npm_prefix') is not writable. Switching to a user-owned prefix: ${user_prefix}"
+    npm config set prefix "$user_prefix"
+    mkdir -p "$user_prefix/bin"
+    # Persist on PATH via ~/.npmrc-adjacent shell config and print an export line.
+    npmrc="$HOME/.npmrc"
+    if [ ! -f "$npmrc" ] || ! grep -q "^prefix=" "$npmrc" 2>/dev/null; then
+      printf 'prefix=%s\n' "$user_prefix" >> "$npmrc"
+    fi
+    case ":$PATH:" in
+      *":$user_prefix/bin:"*) ;;
+      *) PATH="$user_prefix/bin:$PATH"; export PATH ;;
+    esac
+    say "Add this to your shell profile (~/.zshrc or ~/.bashrc) so 'foundr' is always on PATH:"
+    printf '\n    export PATH="%s/bin:$PATH"\n\n' "$user_prefix"
+  fi
+
+  # --- (3) Install the package globally ----------------------------------
+  say "Installing foundr-companion@${FOUNDR_VERSION} globally (this also upgrades an existing install)..."
+  env -u NPM_CONFIG_BEFORE -u NPM_CONFIG_MIN_RELEASE_AGE \
+    npm install -g "foundr-companion@${FOUNDR_VERSION}" --no-fund --no-audit
+
+  command -v foundr >/dev/null 2>&1 || die "'foundr' not found on PATH after install. If you just set a new npm prefix, open a new shell (or run the export line above) and re-run."
+
+  # --- (4) Set up the daemon + preflight ---------------------------------
+  say "Setting up the LaunchAgent and starting the companion (foundr install)..."
+  foundr install
+
+  say "Running the Codex preflight (foundr codex)..."
+  foundr codex
+
+  # --- (5) Next steps ----------------------------------------------------
+  say "Done. Three steps to start talking to your agent:"
+  printf '\n'
+  printf '  1) Pair with Founder World:   foundr login\n'
+  printf '       (opens %s to authorize this machine)\n' "$FOUNDR_URL"
+  printf '  2) Sign in to Codex:          codex login\n'
+  printf '       (choose "Sign in with ChatGPT")\n'
+  printf '  3) Message your agent in the game at %s\n' "$FOUNDR_URL"
+  printf '\n'
+  say "Re-run this installer anytime to upgrade in place."
+}
+
+main "$@"

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "foundr-companion",
+  "version": "0.1.0",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "foundr": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "install.sh"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node copy-bridge.mjs",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@supabase/supabase-js": "^2.105.4"
+  }
+}