@ramarivera/coding-buddy 0.9.3 → 0.9.5

package/scripts/sync-version.ts

@@ -0,0 +1,122 @@
+/**
+ * Sync every version field in the repo to package.json.
+ *
+ *   bun run sync-version           # rewrite drifted fields
+ *   bun run sync-version --check   # exit 1 on drift, change nothing (CI)
+ *
+ * Wired into the npm `version` lifecycle so `npm version <bump>` updates the
+ * manifests in the same commit as package.json, and into CI via --check so
+ * drift cannot land.
+ *
+ * Design and the original implementation come from #110 by @grlee. That PR
+ * conflicted with main and lives on a fork, so it is reimplemented here rather
+ * than rebased.
+ *
+ * server/index.ts is deliberately NOT a target — it imports pkg.version
+ * directly, which is strictly better than syncing a literal. Anything that can
+ * import package.json should do that instead of being added below.
+ */
+
+import { readFileSync, writeFileSync } from "fs";
+import { join } from "path";
+
+const ROOT = join(import.meta.dir, "..");
+const CHECK_ONLY = process.argv.includes("--check");
+
+const version: unknown = JSON.parse(
+  readFileSync(join(ROOT, "package.json"), "utf8"),
+).version;
+
+if (typeof version !== "string" || version === "") {
+  console.error("sync-version: package.json is missing a version field");
+  process.exit(2);
+}
+
+interface Target {
+  /** Repo-relative path. */
+  path: string;
+  /** Every version field in the document, for reporting and for rewriting. */
+  fields: (doc: any) => { label: string; get: () => string; set: () => void }[];
+}
+
+const TARGETS: Target[] = [
+  {
+    path: ".claude-plugin/plugin.json",
+    fields: (doc) => [
+      { label: "version", get: () => doc.version, set: () => { doc.version = version; } },
+    ],
+  },
+  {
+    path: ".claude-plugin/marketplace.json",
+    fields: (doc) => [
+      {
+        label: "metadata.version",
+        get: () => doc.metadata?.version,
+        // Creates metadata if absent. Guarding the write instead would let
+        // --check report drift that the fixer could never resolve.
+        set: () => {
+          doc.metadata ??= {};
+          doc.metadata.version = version;
+        },
+      },
+      ...(doc.plugins ?? []).map((plugin: any, i: number) => ({
+        label: `plugins[${i}].version`,
+        get: () => plugin.version,
+        set: () => { plugin.version = version; },
+      })),
+    ],
+  },
+];
+
+export interface Drift {
+  path: string;
+  label: string;
+  current: string;
+}
+
+/** Returns every field that disagrees with package.json. Never writes. */
+export function findDrift(): Drift[] {
+  const drift: Drift[] = [];
+  for (const target of TARGETS) {
+    const doc = JSON.parse(readFileSync(join(ROOT, target.path), "utf8"));
+    for (const field of target.fields(doc)) {
+      const current = field.get();
+      if (current !== version) drift.push({ path: target.path, label: field.label, current });
+    }
+  }
+  return drift;
+}
+
+function main(): void {
+  const drift = findDrift();
+
+  for (const d of drift) {
+    console.log(
+      `${CHECK_ONLY ? "DRIFT" : "sync"}: ${d.path} :: ${d.label} ${d.current} -> ${version}`,
+    );
+  }
+
+  if (drift.length === 0) {
+    console.log(`sync-version: all version fields already at ${version}`);
+    return;
+  }
+
+  if (CHECK_ONLY) {
+    console.error(
+      "sync-version: version fields are out of sync with package.json. Run `bun run sync-version`.",
+    );
+    process.exit(1);
+  }
+
+  // Rewrite only the files that actually drifted, preserving 4-space style.
+  const drifted = new Set(drift.map((d) => d.path));
+  for (const target of TARGETS) {
+    if (!drifted.has(target.path)) continue;
+    const full = join(ROOT, target.path);
+    const doc = JSON.parse(readFileSync(full, "utf8"));
+    for (const field of target.fields(doc)) field.set();
+    writeFileSync(full, `${JSON.stringify(doc, null, 4)}\n`);
+  }
+}
+
+if (import.meta.main) main();

package/server/index.ts

@@ -9,8 +9,12 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
+import { REACT_REASONS, normalizeReactArgs } from "./react-args.ts";
 import { existsSync } from "fs";
 import { join, resolve, dirname } from "path";
+// The version advertised in the MCP handshake. Imported rather than written
+// as a literal so it cannot drift from the published package (it had, to 0.6.0).
+import pkg from "../package.json" with { type: "json" };
 
 import { generateBones,
 generatePersonality,
@@ -125,7 +129,7 @@ function getInstructions(): string {
 const server = new McpServer(
   {
     name: "coding-buddy",
-    version: "0.6.0",
+    version: pkg.version,
   },
   {
     instructions: getInstructions(),
@@ -301,33 +305,33 @@ server.tool(
   {
     comment: z
       .string()
-      .min(1)
-      .max(150)
+      .optional()
       .describe(
-        "The buddy's comment, written in-character (1 short sentence, max 150 chars). Use *asterisks* for actions.",
+        "The buddy's comment, written in-character (1 short sentence, max 150 chars; longer text is shortened). Use *asterisks* for actions. Always send it: a call with no comment returns an error.",
       ),
+    reaction: z
+      .string()
+      .optional()
+      .describe("Deprecated alias for `comment`. Send `comment` instead."),
     reason: z
-      .enum([
-        "error", "test-fail", "large-diff", "turn",
-        "commit", "push", "merge-conflict", "branch", "rebase", "stash", "tag",
-        "late-night", "early-morning", "long-session", "marathon", "friday", "weekend", "monday",
-        "regex-file", "css-file", "sql-file", "docker-file", "ci-file", "lock-file",
-        "env-file", "test-file", "doc-file", "config-file", "binary-file", "gitignore",
-        "makefile", "readme", "package-file", "proto-file",
-        "lint-fail", "type-error", "build-fail", "security-warning", "deprecation",
-        "frustrated", "happy", "stuck", "sarcastic",
-        "many-edits", "delete-file", "large-file", "create-file",
-        "all-green", "deploy", "release", "coverage",
-        "debug-loop", "write-spree", "search-heavy",
-        "recovery-from-error", "recovery-from-test-fail",
-        "recovery-from-build-fail", "recovery-from-merge-conflict",
-      ])
+      .string()
       .optional()
-      .describe("What triggered the reaction"),
+      .describe(
+        `What triggered the reaction. One of: ${REACT_REASONS.join(", ")}. Defaults to "turn"; unknown values are treated as "turn".`,
+      ),
   },
-  async ({ comment, reason }) => {
+  async (raw) => {
+    const { comment, reason } = normalizeReactArgs(raw);
+    if (comment === null) {
+      return {
+        isError: true,
+        content: [
+          { type: "text", text: 'buddy_react needs a non-empty `comment` string, for example {"comment": "*nods* clean diff", "reason": "turn"}.' },
+        ],
+      };
+    }
     const companion = ensureCompanion();
-    saveReaction(comment, reason ?? "turn", "tool");
+    saveReaction(comment, reason, "tool");
     incrementEvent("reactions_given", 1, activeSlot());
 
     const newAch = checkAndAward(activeSlot());

package/server/react-args.ts

@@ -0,0 +1,64 @@
+/**
+ * Argument handling for the buddy_react tool.
+ *
+ * Agents often call buddy_react without having read its schema: the tool is
+ * deferred in Claude Code, so the model guesses argument names. A strict
+ * schema turned those guesses into MCP -32602 errors and agents then reported
+ * the buddy as unavailable. The tool accepts the common guesses instead and
+ * normalizes them here.
+ */
+
+export const REACT_REASONS = [
+  "error", "test-fail", "large-diff", "turn",
+  "commit", "push", "merge-conflict", "branch", "rebase", "stash", "tag",
+  "late-night", "early-morning", "long-session", "marathon", "friday", "weekend", "monday",
+  "regex-file", "css-file", "sql-file", "docker-file", "ci-file", "lock-file",
+  "env-file", "test-file", "doc-file", "config-file", "binary-file", "gitignore",
+  "makefile", "readme", "package-file", "proto-file",
+  "lint-fail", "type-error", "build-fail", "security-warning", "deprecation",
+  "frustrated", "happy", "stuck", "sarcastic",
+  "many-edits", "delete-file", "large-file", "create-file",
+  "all-green", "deploy", "release", "coverage",
+  "debug-loop", "write-spree", "search-heavy",
+  "recovery-from-error", "recovery-from-test-fail",
+  "recovery-from-build-fail", "recovery-from-merge-conflict",
+] as const;
+
+export type ReactReason = (typeof REACT_REASONS)[number];
+
+export const DEFAULT_REACT_REASON: ReactReason = "turn";
+export const MAX_REACT_COMMENT_LENGTH = 150;
+
+export interface RawReactArgs {
+  comment?: string;
+  /** Alias agents guess when they have not loaded the schema. */
+  reaction?: string;
+  reason?: string;
+}
+
+export interface ReactArgs {
+  /** Null when the caller sent no usable comment under any accepted name. */
+  comment: string | null;
+  reason: ReactReason;
+}
+
+function isReactReason(value: string): value is ReactReason {
+  return (REACT_REASONS as readonly string[]).includes(value);
+}
+
+function clampComment(text: string): string {
+  const chars = Array.from(text);
+  if (chars.length <= MAX_REACT_COMMENT_LENGTH) return text;
+  return `${chars.slice(0, MAX_REACT_COMMENT_LENGTH - 1).join("")}…`;
+}
+
+export function normalizeReactArgs(raw: RawReactArgs): ReactArgs {
+  const text = [raw.comment, raw.reaction]
+    .map((value) => (typeof value === "string" ? value.trim() : ""))
+    .find((value) => value.length > 0);
+  const reason = typeof raw.reason === "string" ? raw.reason.trim() : "";
+  return {
+    comment: text ? clampComment(text) : null,
+    reason: isReactReason(reason) ? reason : DEFAULT_REACT_REASON,
+  };
+}

package/skills/buddy/SKILL.md

@@ -74,7 +74,11 @@ Based on `$ARGUMENTS`:
 
 ## CRITICAL OUTPUT RULES
 
-The MCP tools return pre-formatted ASCII art with ANSI colors, box-drawing characters, stat bars, and species art. This is the companion's visual identity.
+Different buddy tools return different shapes of output. The rules below keep the companion's visual identity intact while making sure plain-text replies actually reach the user.
+
+### Visual-card outputs — strict verbatim
+
+These tools return pre-formatted ASCII art with ANSI colors, box-drawing characters, stat bars, and species art: `buddy_show`, `buddy_stats`, `buddy_pet`, `buddy_achievements`, `buddy_summon`, `buddy_pick`. This is the companion's visual identity.
 
 **You MUST output the tool result text EXACTLY as returned — character for character, line for line.** Do NOT:
 
@@ -86,6 +90,20 @@ The MCP tools return pre-formatted ASCII art with ANSI colors, box-drawing chara
 
 **Just output the raw text content from the tool result. Nothing else.** The ASCII art IS the response.
 
+### Plain-text outputs — verbatim and visible
+
+These tools return plain text, not ASCII art: `buddy_help`, `buddy_mute`, `buddy_unmute`, `buddy_frequency`, `buddy_style`, `buddy_statusline`, `buddy_list`, `buddy_rename`, `buddy_save`, `buddy_dismiss`, `buddy_set_personality`.
+
+**The visible reply MUST include the tool result text verbatim — every time, on every call, even on repeated calls in the same session.** Treat each invocation as a fresh request from the user, not a "they have seen it before" signal. Tool results are not rendered in the user's transcript; only what you write in your own reply reaches the screen.
+
+You MAY add a one-sentence confirmation before or after if it clarifies what changed, but do NOT paraphrase the text itself.
+
+**Hard floor for the plain-text commands above:** a reply that contains no visible text of its own is broken. A `buddy_react` call is not visible output — it reaches the user only through the statusline bubble — so a turn whose only content is a tool call renders blank. If you have nothing else to say, the tool result text alone is the correct reply.
+
+**Self-check for the plain-text commands above:** does your visible reply contain that command's result text? If not, paste it in. Never paste the result of `buddy_react`. The end-of-turn `buddy_react` call is _additional_, never _instead of_.
+
+### Reactions — statusline only
+
 If the user mentions the buddy's name in normal conversation, call `buddy_react` with reason "turn". Do NOT echo or quote the tool result — the reaction reaches the user only via the statusline speech bubble.
 
 ## Uninstall Orchestration