opencode-buddy 0.2.0

package/src/index.js

@@ -0,0 +1,302 @@
+// Main runtime. Wires together state, persistence, TUI, tmux polling.
+//
+// Usage from bin/opencode-buddy.js:
+//   await runInteractive()    // for `opencode-buddy start`
+//   await runCommand(args)    // for all other subcommands
+
+import * as persistence from "./persistence.js";
+import { createTui } from "./tui.js";
+import {
+  tick,
+  feed,
+  play,
+  rest,
+  rename,
+  switchSpecies,
+  celebrate,
+  scared,
+  working,
+  deriveState,
+  maybeLevelUp,
+  describe as describeState,
+  DEFAULT_STATE,
+} from "./buddy/state.js";
+import { SPECIES } from "./buddy/species.js";
+import {
+  inTmux,
+  currentPaneId,
+  splitRight,
+  captureMainPane,
+  inferActivity,
+  killBuddyPane,
+} from "./tmux.js";
+
+const TICK_MS = 1000;
+const SAVE_EVERY_MS = 5000;
+
+const HINT = `keys: f feed · p play · r rename · s switch · z rest · n hatch · q quit`;
+
+export async function loadOrInit() {
+  const existing = await persistence.load();
+  if (existing) return existing;
+  const fresh = { ...DEFAULT_STATE, lastTick: Date.now() };
+  await persistence.save(fresh);
+  return fresh;
+}
+
+export async function runInteractive({ autoSplit = true } = {}) {
+  if (!inTmux()) {
+    throw new Error(
+      "opencode-buddy start must run inside a tmux session. " +
+        "Start tmux first, then run: opencode-buddy start",
+    );
+  }
+
+  let state = await loadOrInit();
+  let buddyPane = null;
+  if (autoSplit) {
+    buddyPane = splitRight(
+      `cd ${process.cwd()} && exec ${process.execPath} ${process.argv[1]} render`,
+      28,
+    );
+  }
+
+  const tui = createTui({
+    onKey: (key) => {
+      switch (key) {
+        case "f":
+          state = feed(state);
+          flash("yum!");
+          break;
+        case "p":
+          state = play(state);
+          flash("hehe!");
+          break;
+        case "z":
+          state = rest(state);
+          flash("zzz...");
+          break;
+        case "n":
+          state = { ...DEFAULT_STATE, lastTick: Date.now() };
+          flash("new buddy!");
+          break;
+        case "r": {
+          // simple prompt via stdout
+          process.stdout.write(`\x1b[2J\x1b[Hnew name: `);
+          let name = "";
+          const onData = (b) => {
+            const s = b.toString("utf8");
+            if (s === "\n" || s === "\r" || s === "\u0003") {
+              process.stdin.off("data", onData);
+              if (name) state = rename(state, name);
+              flash(name ? `hi ${name}!` : "ok");
+            } else if (s === "\u007f" || s === "\b") {
+              name = name.slice(0, -1);
+            } else {
+              name += s.replace(/[\r\n]/g, "");
+            }
+          };
+          process.stdin.on("data", onData);
+          break;
+        }
+        case "s": {
+          // cycle species
+          const idx = SPECIES.indexOf(state.species);
+          const next = SPECIES[(idx + 1) % SPECIES.length];
+          state = switchSpecies(state, next);
+          flash(`now ${next}`);
+          break;
+        }
+        case "q":
+        case "ctrl-c":
+          cleanup();
+          process.exit(0);
+          break;
+        default:
+          // ignore
+          break;
+      }
+    },
+  });
+
+  let flashUntil = 0;
+  let flashText = "";
+  function flash(text, ms = 1500) {
+    flashText = text;
+    flashUntil = Date.now() + ms;
+  }
+
+  function buildHint() {
+    if (Date.now() < flashUntil) return `${flashText}   ·   ${HINT}`;
+    return HINT;
+  }
+
+  let lastActivity = "unknown";
+  let lastPoll = 0;
+  let lastSave = 0;
+  let running = true;
+
+  async function loop() {
+    while (running) {
+      const now = Date.now();
+
+      // 1. tick attributes for time decay
+      state = tick(state, now);
+
+      // 2. capture tmux main pane every 2s for activity inference
+      if (now - lastPoll > 2000) {
+        lastPoll = now;
+        const text = captureMainPane(60);
+        const activity = inferActivity(text);
+        if (activity !== lastActivity) {
+          lastActivity = activity;
+          if (activity === "working") state = working(state);
+          else if (activity === "error") state = scared(state);
+          else if (activity === "idle")
+            state = celebrate(state, 1500);
+        }
+      }
+
+      // 3. derive final state (transient overrides first, then attributes)
+      state = deriveState(state, now);
+
+      // 4. level up check
+      state = maybeLevelUp(state);
+
+      // 5. render
+      tui.render(state, buildHint());
+
+      // 6. persist periodically
+      if (now - lastSave > SAVE_EVERY_MS) {
+        lastSave = now;
+        await persistence.save(state).catch(() => {});
+      }
+
+      await new Promise((r) => setTimeout(r, TICK_MS));
+    }
+  }
+
+  function cleanup() {
+    running = false;
+    tui.stop();
+    if (buddyPane) killBuddyPane(buddyPane);
+  }
+
+  process.on("SIGINT", () => {
+    cleanup();
+    process.exit(0);
+  });
+  process.on("SIGTERM", () => {
+    cleanup();
+    process.exit(0);
+  });
+
+  tui.start();
+  await loop();
+}
+
+// Headless command runner: feed, play, rename, switch, hatch, stats, notify
+export async function runCommand(argv) {
+  const [cmd, ...rest] = argv;
+  let state = await loadOrInit();
+
+  switch (cmd) {
+    case "hatch":
+    case "reset": {
+      const species = rest[0] && SPECIES.includes(rest[0]) ? rest[0] : "duck";
+      state = {
+        ...DEFAULT_STATE,
+        species,
+        name: rest[1] || DEFAULT_STATE.name,
+        lastTick: Date.now(),
+      };
+      await persistence.save(state);
+      console.log(`Hatched a new ${state.species} named ${state.name}.`);
+      break;
+    }
+    case "feed":
+      state = feed(state);
+      await persistence.save(state);
+      console.log(`Fed ${state.name}. hunger -> ${Math.floor(state.hunger)}`);
+      break;
+    case "play":
+      state = play(state);
+      await persistence.save(state);
+      console.log(
+        `Played with ${state.name}. happiness -> ${Math.floor(state.happiness)}`,
+      );
+      break;
+    case "rest":
+      state = rest(state);
+      await persistence.save(state);
+      console.log(`${state.name} took a nap.`);
+      break;
+    case "rename": {
+      const name = rest.join(" ").trim();
+      if (!name) {
+        console.error("usage: opencode-buddy rename <name>");
+        process.exit(2);
+      }
+      state = rename(state, name);
+      await persistence.save(state);
+      console.log(`Renamed to ${state.name}.`);
+      break;
+    }
+    case "switch": {
+      const species = rest[0];
+      if (!species || !SPECIES.includes(species)) {
+        console.error(`species must be one of: ${SPECIES.join(", ")}`);
+        process.exit(2);
+      }
+      state = switchSpecies(state, species);
+      await persistence.save(state);
+      console.log(`${state.name} transformed into a ${species}.`);
+      break;
+    }
+    case "stats":
+      console.log(describeState(state));
+      break;
+    case "notify": {
+      const event = rest[0];
+      if (event === "working" || event === "start")
+        state = working(state);
+      else if (event === "done" || event === "celebrate")
+        state = celebrate(state);
+      else if (event === "error" || event === "scared")
+        state = scared(state);
+      else {
+        console.error(
+          "usage: opencode-buddy notify <working|done|error>",
+        );
+        process.exit(2);
+      }
+      await persistence.save(state);
+      console.log(`Notified buddy: ${event}`);
+      break;
+    }
+    case "path":
+      console.log(persistence.pathForDisplay());
+      break;
+    default:
+      printUsage();
+      process.exit(cmd ? 2 : 0);
+  }
+}
+
+function printUsage() {
+  console.log(`opencode-buddy — a virtual pet for your tmux session
+
+Usage:
+  opencode-buddy start                    Launch interactive buddy in a tmux side pane
+  opencode-buddy hatch [species] [name]   Start a brand new buddy (resets state)
+  opencode-buddy feed                     Feed your buddy
+  opencode-buddy play                     Play with your buddy
+  opencode-buddy rest                     Let your buddy rest
+  opencode-buddy rename <name>            Give your buddy a new name
+  opencode-buddy switch <species>         Change species (${SPECIES.join(", ")})
+  opencode-buddy notify <event>           Notify buddy of an opencode event
+                                           (working | done | error)
+  opencode-buddy stats                    Print current buddy stats
+  opencode-buddy path                     Print path to state file
+`);
+}

package/src/install.js

@@ -0,0 +1,157 @@
+// One-shot installer. Writes the /buddy slash command markdown file
+// and adds this package to opencode.json's plugin list so opencode will
+// bun-install it on the next startup.
+//
+// Re-runnable: safely no-ops if everything is already in place.
+
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+const OPENCODE_DIR = path.join(os.homedir(), ".config", "opencode");
+const COMMANDS_DIR = path.join(OPENCODE_DIR, "commands");
+const COMMAND_FILE = path.join(COMMANDS_DIR, "buddy.md");
+const CONFIG_FILE = path.join(OPENCODE_DIR, "opencode.json");
+
+const PLUGIN_NAME = "opencode-buddy";
+
+const COMMAND_BODY = `---
+description: Interact with your virtual buddy companion.
+---
+
+The user typed \`/buddy\`. Use the \`buddy\` tool to respond.
+
+If the user typed \`/buddy\` with no arguments, call the tool with
+\`action: "status"\`. If they passed sub-arguments like \`/buddy feed\`
+or \`/buddy switch dragon\`, map them to the tool's \`action\`,
+\`species\`, and \`name\` arguments accordingly. Examples:
+
+  /buddy              -> buddy({ action: "status" })
+  /buddy feed         -> buddy({ action: "feed" })
+  /buddy play         -> buddy({ action: "play" })
+  /buddy switch cat   -> buddy({ action: "switch", species: "cat" })
+  /buddy rename Mia   -> buddy({ action: "rename", name: "Mia" })
+  /buddy hatch dragon Sparky -> buddy({ action: "hatch", species: "dragon", name: "Sparky" })
+  /buddy ascii        -> buddy({ action: "ascii" })
+
+Always show the tool's returned text to the user. If the user just wants
+to see the buddy, call \`action: "ascii"\` to render the current art in a
+code block.
+`;
+
+export async function install() {
+  const steps = [];
+  const errors = [];
+
+  // 1. Write the slash command file
+  try {
+    await fs.mkdir(COMMANDS_DIR, { recursive: true });
+    const existing = await fs.readFile(COMMAND_FILE, "utf8").catch(() => null);
+    if (existing === COMMAND_BODY) {
+      steps.push(`= ${COMMAND_FILE} (unchanged)`);
+    } else {
+      await fs.writeFile(COMMAND_FILE, COMMAND_BODY);
+      steps.push(`+ ${COMMAND_FILE}`);
+    }
+  } catch (err) {
+    errors.push(`failed to write ${COMMAND_FILE}: ${err.message}`);
+  }
+
+  // 2. Patch opencode.json
+  try {
+    let config = {};
+    try {
+      const raw = await fs.readFile(CONFIG_FILE, "utf8");
+      config = JSON.parse(raw);
+    } catch (err) {
+      if (err.code !== "ENOENT") throw err;
+    }
+
+    let pluginList = config.plugin;
+    if (pluginList == null) {
+      pluginList = [];
+      config.plugin = pluginList;
+    } else if (typeof pluginList === "string") {
+      pluginList = [pluginList];
+      config.plugin = pluginList;
+    } else if (!Array.isArray(pluginList)) {
+      errors.push(
+        `${CONFIG_FILE} has an unexpected "plugin" field type; expected array.`,
+      );
+      pluginList = [];
+    }
+
+    if (!pluginList.includes(PLUGIN_NAME)) {
+      pluginList.push(PLUGIN_NAME);
+      config.plugin = pluginList;
+      const tmp = CONFIG_FILE + ".tmp";
+      await fs.writeFile(tmp, JSON.stringify(config, null, 2));
+      await fs.rename(tmp, CONFIG_FILE);
+      steps.push(`~ ${CONFIG_FILE} (added "${PLUGIN_NAME}")`);
+    } else {
+      steps.push(`= ${CONFIG_FILE} (already lists "${PLUGIN_NAME}")`);
+    }
+  } catch (err) {
+    errors.push(`failed to patch ${CONFIG_FILE}: ${err.message}`);
+  }
+
+  // 3. Report
+  console.log("opencode-buddy install");
+  console.log("------------------------");
+  for (const s of steps) console.log(`  ${s}`);
+  if (errors.length) {
+    console.log("\nErrors:");
+    for (const e of errors) console.log(`  ! ${e}`);
+    process.exit(1);
+  }
+  console.log("\nDone. Restart opencode to activate the /buddy command.");
+  console.log("Then in opencode, try:  /buddy");
+}
+
+export async function uninstall() {
+  const steps = [];
+  const errors = [];
+
+  // 1. Remove the command file
+  try {
+    await fs.unlink(COMMAND_FILE);
+    steps.push(`- ${COMMAND_FILE}`);
+  } catch (err) {
+    if (err.code === "ENOENT") steps.push(`= ${COMMAND_FILE} (not present)`);
+    else errors.push(`failed to remove ${COMMAND_FILE}: ${err.message}`);
+  }
+
+  // 2. Remove from opencode.json
+  try {
+    const raw = await fs.readFile(CONFIG_FILE, "utf8");
+    const config = JSON.parse(raw);
+    if (Array.isArray(config.plugin)) {
+      const before = config.plugin.length;
+      config.plugin = config.plugin.filter((p) => p !== PLUGIN_NAME);
+      if (config.plugin.length === 0) delete config.plugin;
+      if (config.plugin.length !== before) {
+        const tmp = CONFIG_FILE + ".tmp";
+        await fs.writeFile(tmp, JSON.stringify(config, null, 2));
+        await fs.rename(tmp, CONFIG_FILE);
+        steps.push(`~ ${CONFIG_FILE} (removed "${PLUGIN_NAME}")`);
+      } else {
+        steps.push(`= ${CONFIG_FILE} (no entry to remove)`);
+      }
+    } else {
+      steps.push(`= ${CONFIG_FILE} (no plugin array)`);
+    }
+  } catch (err) {
+    if (err.code === "ENOENT") steps.push(`= ${CONFIG_FILE} (not present)`);
+    else errors.push(`failed to patch ${CONFIG_FILE}: ${err.message}`);
+  }
+
+  console.log("opencode-buddy uninstall");
+  console.log("--------------------------");
+  for (const s of steps) console.log(`  ${s}`);
+  if (errors.length) {
+    console.log("\nErrors:");
+    for (const e of errors) console.log(`  ! ${e}`);
+    process.exit(1);
+  }
+  console.log("\nDone. Restart opencode to deactivate the /buddy command.");
+}

package/src/persistence.js

@@ -0,0 +1,28 @@
+// Persist buddy state to ~/.config/opencode-buddy/state.json
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+const DIR = path.join(os.homedir(), ".config", "opencode-buddy");
+const FILE = path.join(DIR, "state.json");
+
+export async function load() {
+  try {
+    const raw = await fs.readFile(FILE, "utf8");
+    return JSON.parse(raw);
+  } catch (err) {
+    if (err.code === "ENOENT") return null;
+    throw err;
+  }
+}
+
+export async function save(state) {
+  await fs.mkdir(DIR, { recursive: true });
+  const tmp = FILE + ".tmp";
+  await fs.writeFile(tmp, JSON.stringify(state, null, 2));
+  await fs.rename(tmp, FILE);
+}
+
+export function pathForDisplay() {
+  return FILE;
+}

package/src/plugin.js

@@ -0,0 +1,178 @@
+// opencode plugin entry. Exposes a `buddy` tool the LLM can call and
+// listens for session events to keep the buddy's mood in sync with what
+// the user is actually doing.
+//
+// Loaded automatically by opencode when listed in `opencode.json`:
+//   { "plugin": ["opencode-buddy"] }
+//
+// Also installed at runtime by the `opencode-buddy install` CLI command,
+// which writes ~/.config/opencode/commands/buddy.md (the /buddy slash
+// command) and appends this package to opencode.json's plugin list.
+
+import { tool } from "@opencode-ai/plugin";
+import * as state from "./buddy/state.js";
+import * as persistence from "./persistence.js";
+import { SPECIES, paint, FLAVOR } from "./buddy/species.js";
+
+const DESCRIPTION = `Interact with your virtual buddy companion. Pass an "action" argument.
+
+Actions:
+  status                  - print current stats as a one-liner
+  feed                    - feed the buddy (+25 hunger, -5 energy)
+  play                    - play with the buddy (+20 happiness, -5 hunger, +5 xp)
+  rest                    - let the buddy rest (+30 energy)
+  switch <species>        - change species (duck, cat, dragon, axolotl, robot, ghost)
+  rename <name>           - rename the buddy (max 20 chars)
+  hatch [species] [name]  - start a brand new buddy
+  ascii                   - return a rendered ASCII art of the current buddy
+  path                    - print path to the persistent state file
+  help                    - list available actions
+
+The buddy's mood (idle/working/celebrating/scared/sleeping) is set
+automatically based on the opencode session lifecycle. Use this tool
+when the user asks things like "/buddy", "/buddy feed", "/buddy stats",
+"check on my pet", "switch to a dragon", etc.`;
+
+const SPECIES_LIST = SPECIES.join(", ");
+
+function _summary(s) {
+  return `${s.name} the ${s.species} | Lv ${s.level} | ${s.state} | hunger ${Math.floor(s.hunger)} happiness ${Math.floor(s.happiness)} energy ${Math.floor(s.energy)} | xp ${s.xp}/${s.level * 50}`;
+}
+
+async function loadOrInit() {
+  const s = await persistence.load();
+  if (s) return s;
+  const fresh = { ...state.DEFAULT_STATE, lastTick: Date.now() };
+  await persistence.save(fresh);
+  return fresh;
+}
+
+export const BuddyPlugin = async ({ client }) => {
+  return {
+    // ----- Custom tool the LLM can call --------------------------------
+    tool: {
+      buddy: tool({
+        description: DESCRIPTION,
+        args: {
+          action: tool.schema
+            .string()
+            .describe(
+              `One of: status, feed, play, rest, switch, rename, hatch, ascii, path, help. For switch/rename/hatch, also pass the "species" or "name" argument as needed.`,
+            ),
+          species: tool.schema
+            .string()
+            .optional()
+            .describe(`Species for switch/hatch: ${SPECIES_LIST}`),
+          name: tool.schema
+            .string()
+            .optional()
+            .describe(`Name for rename/hatch (max 20 chars).`),
+        },
+        async execute(args) {
+          let s = await loadOrInit();
+          const action = (args.action || "").toLowerCase();
+          const species = (args.species || "").toLowerCase();
+          const name = args.name;
+
+          switch (action) {
+            case "":
+            case "status":
+              return _summary(s);
+
+            case "feed":
+              s = state.feed(s);
+              await persistence.save(s);
+              return `${s.name} munches happily. ${_summary(s)}`;
+
+            case "play":
+              s = state.play(s);
+              s = state.maybeLevelUp(s);
+              await persistence.save(s);
+              return `${s.name} plays! ${_summary(s)}`;
+
+            case "rest":
+              s = state.rest(s);
+              await persistence.save(s);
+              return `${s.name} curls up. ${_summary(s)}`;
+
+            case "switch": {
+              if (!species) return `Pick a species: ${SPECIES_LIST}`;
+              if (!SPECIES.includes(species))
+                return `Unknown species "${species}". Valid: ${SPECIES_LIST}`;
+              s = state.switchSpecies(s, species);
+              await persistence.save(s);
+              return `${s.name} transformed into a ${species}. ${_summary(s)}`;
+            }
+
+            case "rename": {
+              if (!name) return `Provide a name with the "name" argument.`;
+              s = state.rename(s, name);
+              await persistence.save(s);
+              return `Renamed to ${s.name}. ${_summary(s)}`;
+            }
+
+            case "hatch": {
+              const sp = species && SPECIES.includes(species) ? species : "duck";
+              s = {
+                ...state.DEFAULT_STATE,
+                species: sp,
+                name: name || "Buddy",
+                lastTick: Date.now(),
+              };
+              await persistence.save(s);
+              return `Hatched a new ${sp} named ${s.name}. ${_summary(s)}`;
+            }
+
+            case "ascii": {
+              const lines = paint(s.species, s.state);
+              return ["```", ...lines, "```", _summary(s)].join("\n");
+            }
+
+            case "path":
+              return persistence.pathForDisplay();
+
+            case "help":
+              return DESCRIPTION;
+
+            default:
+              return `Unknown action "${args.action}". Try: /buddy help`;
+          }
+        },
+      }),
+    },
+
+    // ----- React to opencode session lifecycle -------------------------
+    event: async ({ event }) => {
+      // Auto-mood: when opencode finishes a turn, the buddy celebrates
+      // for a few seconds. When a session errors, the buddy gets scared.
+      // The visible feedback comes from the tmux sidecar picking up the
+      // updated state file, or the LLM re-rendering ASCII via the tool.
+      try {
+        if (event.type === "session.idle") {
+          const s = await loadOrInit();
+          await persistence.save(state.celebrate(s));
+        } else if (event.type === "session.error") {
+          const s = await loadOrInit();
+          await persistence.save(state.scared(s));
+        }
+      } catch (err) {
+        if (client?.app?.log) {
+          await client.app.log({
+            body: {
+              service: "opencode-buddy",
+              level: "warn",
+              message: `event hook failed: ${err.message}`,
+            },
+          });
+        }
+      }
+    },
+  };
+};
+
+// Re-export common helpers so other tools (e.g. custom agents) can
+// import the same state machine used by the plugin and the tmux
+// sidecar — guaranteeing the persisted state file format stays in sync.
+export { SPECIES, FLAVOR };
+export * as stateMachine from "./buddy/state.js";
+export { persistence };