@rubytech/create-maxy-code 0.1.166 → 0.1.169

package/payload/premium-plugins/writer-craft/mcp/scripts/smoke.mjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+/**
+ * Boot + shape smoke test for the writer-craft MCP server.
+ *
+ * Verifies:
+ *   1. Every compiled tool module loads without throwing.
+ *   2. Every exported handler is a function with the expected name.
+ *   3. AUTHORSHIP_MODES enum covers the five spec-required values.
+ *   4. TAGGABLE_PRIMARY_LABELS covers the four content labels.
+ *   5. `voice-retrieve-conditioning` returns the graceful-degradation
+ *      shape `{styleCard: null, exemplars: []}` when accountId is empty
+ *      (the contract the calling drafting skills depend on).
+ *
+ * Runs with no external dependencies and no neo4j connection — the
+ * graceful-degradation case never opens a session. The four other tools
+ * are not exercised against the database here; their unit test coverage
+ * is filed as a follow-up. This smoke harness catches import errors,
+ * accidental contract changes on the empty-corpus return shape, and
+ * structural drift on the exported enum.
+ *
+ * Exit code: 0 on pass, 1 on any assertion failure. Designed for CI
+ * gating and `npm run smoke` in the build pipeline.
+ */
+import { strict as assert } from "node:assert";
+
+const errors = [];
+function check(name, fn) {
+  try {
+    const result = fn();
+    if (result && typeof result.then === "function") {
+      return result.then(
+        () => console.log(`  ok   ${name}`),
+        (err) => {
+          errors.push({ name, err });
+          console.error(`  FAIL ${name}: ${err.message}`);
+        },
+      );
+    }
+    console.log(`  ok   ${name}`);
+  } catch (err) {
+    errors.push({ name, err });
+    console.error(`  FAIL ${name}: ${err.message}`);
+  }
+}
+
+console.log("[writer-craft smoke] starting");
+
+// 1. Modules load.
+const tagMod = await import("../dist/tools/voice-tag-content.js");
+const distilMod = await import("../dist/tools/voice-distil-profile.js");
+const retrieveMod = await import("../dist/tools/voice-retrieve-conditioning.js");
+const feedbackMod = await import("../dist/tools/voice-record-feedback.js");
+const corpusMod = await import("../dist/lib/voice-corpus.js");
+
+await check("voice-tag-content exports voiceTagContent function", () => {
+  assert.equal(typeof tagMod.voiceTagContent, "function");
+});
+await check("voice-tag-content exports AUTHORSHIP_MODES set of 5", () => {
+  const expected = [
+    "human-only",
+    "human-led-agent-assisted",
+    "agent-led-human-reviewed",
+    "agent-only",
+    "unknown",
+  ];
+  assert.equal(tagMod.AUTHORSHIP_MODES.size, 5);
+  for (const m of expected) assert.ok(tagMod.AUTHORSHIP_MODES.has(m), `missing ${m}`);
+});
+await check("voice-distil-profile exports voiceDistilProfile function", () => {
+  assert.equal(typeof distilMod.voiceDistilProfile, "function");
+});
+await check("voice-retrieve-conditioning exports voiceRetrieveConditioning function", () => {
+  assert.equal(typeof retrieveMod.voiceRetrieveConditioning, "function");
+});
+await check("voice-record-feedback exports voiceRecordFeedback function", () => {
+  assert.equal(typeof feedbackMod.voiceRecordFeedback, "function");
+});
+await check("VOICE_CORPUS_WHERE is non-empty string with both predicates", () => {
+  assert.equal(typeof corpusMod.VOICE_CORPUS_WHERE, "string");
+  assert.ok(corpusMod.VOICE_CORPUS_WHERE.includes("authorshipMode IN"));
+  assert.ok(corpusMod.VOICE_CORPUS_WHERE.includes("human-only"));
+  assert.ok(corpusMod.VOICE_CORPUS_WHERE.includes("human-led-agent-assisted"));
+  assert.ok(corpusMod.VOICE_CORPUS_WHERE.includes("Section"));
+});
+await check("TAGGABLE_PRIMARY_LABELS covers the four content labels", () => {
+  const labels = [...corpusMod.TAGGABLE_PRIMARY_LABELS];
+  assert.deepEqual(labels.sort(), ["Email", "KnowledgeDocument", "Message", "SocialPost"]);
+});
+
+// 2. Graceful-degradation contract — the drafting skills depend on this.
+//    Empty accountId/adminUserId path returns the empty shape without
+//    opening a neo4j session. This is the load-bearing contract.
+await check(
+  "voice-retrieve-conditioning returns empty shape on missing accountId",
+  async () => {
+    const result = await retrieveMod.voiceRetrieveConditioning({
+      accountId: "",
+      adminUserId: "u",
+      brief: { format: "short" },
+    });
+    assert.deepEqual(result, { styleCard: null, exemplars: [] });
+  },
+);
+await check(
+  "voice-retrieve-conditioning returns empty shape on missing adminUserId",
+  async () => {
+    const result = await retrieveMod.voiceRetrieveConditioning({
+      accountId: "acc",
+      adminUserId: "",
+      brief: { format: "long" },
+    });
+    assert.deepEqual(result, { styleCard: null, exemplars: [] });
+  },
+);
+
+// 3. voice-tag-content validates the mode enum before any DB work.
+await check("voice-tag-content rejects an invalid mode", async () => {
+  await assert.rejects(
+    () =>
+      tagMod.voiceTagContent({
+        nodeIds: ["x"],
+        mode: "not-a-mode",
+        accountId: "acc",
+      }),
+    /invalid authorshipMode/,
+  );
+});
+await check("voice-tag-content rejects empty accountId", async () => {
+  await assert.rejects(
+    () =>
+      tagMod.voiceTagContent({
+        nodeIds: ["x"],
+        mode: "human-only",
+        accountId: "",
+      }),
+    /accountId is required/,
+  );
+});
+await check("voice-tag-content returns zero counts on empty nodeIds (no DB hit)", async () => {
+  const result = await tagMod.voiceTagContent({
+    nodeIds: [],
+    mode: "human-only",
+    accountId: "acc",
+  });
+  assert.deepEqual(result, { updated: 0, skipped: 0, skippedReasons: {} });
+});
+
+if (errors.length > 0) {
+  console.error(`\n[writer-craft smoke] FAILED — ${errors.length} assertion(s)`);
+  process.exit(1);
+}
+console.log("\n[writer-craft smoke] all passed");

package/payload/premium-plugins/writer-craft/mcp/src/index.ts

@@ -0,0 +1,289 @@
+import { initStderrTee } from "../../../../platform/lib/mcp-stderr-tee/dist/index.js";
+initStderrTee("writer-craft");
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { voiceTagContent, AUTHORSHIP_MODES, type AuthorshipMode } from "./tools/voice-tag-content.js";
+import { voiceDistilProfile } from "./tools/voice-distil-profile.js";
+import { voiceRetrieveConditioning } from "./tools/voice-retrieve-conditioning.js";
+import { voiceRecordFeedback } from "./tools/voice-record-feedback.js";
+import { closeDriver } from "./lib/neo4j.js";
+
+const server = new McpServer({
+  name: "maxy-writer-craft",
+  version: "0.1.0",
+});
+
+// Plugin-system boot tolerance — module-init must never throw. Per-call
+// refusal preserves account isolation. Mirrors the memory plugin's
+// pattern (Task 202).
+const accountId = process.env.ACCOUNT_ID ?? null;
+const adminUserIdEnv = process.env.ADMIN_USER_ID ?? null;
+process.stderr.write(
+  `[writer-craft] boot accountId=${accountId ?? "null"} adminUserId=${adminUserIdEnv ?? "null"}\n`,
+);
+
+function refuseNoAccount(toolName: string) {
+  process.stderr.write(
+    `[writer-craft] tool=${toolName} refuse reason=no-account-context\n`,
+  );
+  return {
+    content: [
+      {
+        type: "text" as const,
+        text: `${toolName} cannot execute: this MCP instance was launched without ACCOUNT_ID. Per-account graph access requires ACCOUNT_ID at spawn.`,
+      },
+    ],
+    isError: true as const,
+  };
+}
+
+function resolveAdminUserId(): string | null {
+  // ADMIN_USER_ID is stamped by the admin session manager at spawn time.
+  // When absent (e.g. specialist subagents), the operator must pass it as
+  // a tool argument or the tools refuse rather than orphan a profile.
+  return adminUserIdEnv;
+}
+
+server.tool(
+  "voice-tag-content",
+  "Stamp authorshipMode on one or many content nodes (:KnowledgeDocument | :Message | :SocialPost) the operator owns. Email threads live as :KnowledgeDocument {source:'email'} since Task 321. Valid modes: human-only, human-led-agent-assisted, agent-led-human-reviewed, agent-only, unknown.",
+  {
+    nodeIds: z.array(z.string()).min(1).describe("Element IDs of nodes to tag"),
+    mode: z
+      .enum([
+        "human-only",
+        "human-led-agent-assisted",
+        "agent-led-human-reviewed",
+        "agent-only",
+        "unknown",
+      ])
+      .describe("Authorship mode to apply"),
+  },
+  async ({ nodeIds, mode }) => {
+    if (!accountId) return refuseNoAccount("voice-tag-content");
+    try {
+      const result = await voiceTagContent({
+        nodeIds,
+        mode: mode as AuthorshipMode,
+        accountId,
+      });
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `voice-tag: mode=${mode} updated=${result.updated} skipped=${result.skipped}`,
+          },
+        ],
+      };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `voice-tag-content failed: ${err instanceof Error ? err.message : String(err)}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+  },
+);
+
+server.tool(
+  "voice-distil-profile",
+  "Two-mode tool (Task 424). mode='sample' (default) walks the operator's human-only corpus, returns the exemplars + recent operator-edit intents for the agent to read. mode='write' persists the YAML style card the agent composed from the sample-mode response. Cadence-guarded: returns skip in 'write' mode without writing if corpus didn't grow ≥20% AND <30 days passed (pass force=true to override).",
+  {
+    adminUserId: z
+      .string()
+      .optional()
+      .describe(
+        "Operator AdminUser identifier. Defaults to ADMIN_USER_ID env from spawn context.",
+      ),
+    force: z
+      .boolean()
+      .optional()
+      .describe("Override cadence guard; rebuild even if recent."),
+    mode: z
+      .enum(["sample", "write"])
+      .optional()
+      .describe("'sample' returns corpus exemplars + feedback for in-turn distillation; 'write' persists the agent-produced styleCardYaml."),
+    styleCardYaml: z
+      .string()
+      .optional()
+      .describe("Required for mode='write'. The YAML style card the agent composed from the sample-mode exemplars + feedback intents."),
+  },
+  async ({ adminUserId, force, mode, styleCardYaml }) => {
+    if (!accountId) return refuseNoAccount("voice-distil-profile");
+    const resolvedAdminUserId = adminUserId ?? resolveAdminUserId();
+    if (!resolvedAdminUserId) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text:
+              "voice-distil-profile: adminUserId required (no ADMIN_USER_ID in spawn env).",
+          },
+        ],
+        isError: true,
+      };
+    }
+    try {
+      const result = await voiceDistilProfile({
+        accountId,
+        adminUserId: resolvedAdminUserId,
+        force: force === true,
+        mode,
+        styleCardYaml,
+      });
+      const summary = result.skipped
+        ? (result.exemplars
+            ? `voice-distil sample: corpusSize=${result.corpusSize} exemplars=${result.exemplars.length} feedbackEntries=${result.feedbackEntries}\n${JSON.stringify({ exemplars: result.exemplars, feedbackIntents: result.feedbackIntents }, null, 2)}`
+            : `voice-distil: skipped reason=${result.skipReason} corpusSize=${result.corpusSize}`)
+        : `voice-distil: ok profileId=${result.profileId} corpusSize=${result.corpusSize} feedbackEntries=${result.feedbackEntries} generatedAt=${result.generatedAt}`;
+      return { content: [{ type: "text" as const, text: summary }] };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `voice-distil-profile failed: ${err instanceof Error ? err.message : String(err)}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+  },
+);
+
+server.tool(
+  "voice-retrieve-conditioning",
+  "Return the operator's style card and K voice-matched exemplars for a drafting brief. K=5 short-form, K=15 long-form. Token-budget bounded. Returns empty {styleCard:null,exemplars:[]} when no profile exists.",
+  {
+    adminUserId: z
+      .string()
+      .optional()
+      .describe("Operator AdminUser identifier. Defaults to ADMIN_USER_ID env."),
+    topic: z
+      .string()
+      .optional()
+      .describe("Drafting topic keyword (filters exemplars to relevant ones)"),
+    format: z
+      .enum(["short", "long"])
+      .describe("Short = email/post (K=5, 16k tokens); long = brochure/prospectus (K=15, 96k tokens)"),
+    register: z.string().optional().describe("Optional register hint"),
+    tokenBudget: z.number().int().positive().optional(),
+  },
+  async ({ adminUserId, topic, format, register, tokenBudget }) => {
+    if (!accountId) return refuseNoAccount("voice-retrieve-conditioning");
+    const resolvedAdminUserId = adminUserId ?? resolveAdminUserId();
+    if (!resolvedAdminUserId) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify({ styleCard: null, exemplars: [] }),
+          },
+        ],
+      };
+    }
+    try {
+      const result = await voiceRetrieveConditioning({
+        accountId,
+        adminUserId: resolvedAdminUserId,
+        brief: { topic, format, register },
+        tokenBudget,
+      });
+      return {
+        content: [
+          { type: "text" as const, text: JSON.stringify(result) },
+        ],
+      };
+    } catch (err) {
+      // Graceful degradation: callers expect {styleCard:null,exemplars:[]}
+      // on failure, never an error response.
+      process.stderr.write(
+        `[voice-retrieve] tool error: ${err instanceof Error ? err.message : String(err)}\n`,
+      );
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify({ styleCard: null, exemplars: [] }),
+          },
+        ],
+      };
+    }
+  },
+);
+
+server.tool(
+  "voice-record-feedback",
+  "Capture an operator's edit on an agent draft. Writes :VoiceEdit linked to :VoiceProfile via :FEEDBACK_FOR. The calling agent supplies `intent` (one sentence describing what the operator changed and what voice preference it reveals); Task 424 moved the diff-intent summarisation into the agent's turn.",
+  {
+    adminUserId: z.string().optional(),
+    originalText: z.string().min(1),
+    editedText: z.string().min(1),
+    intent: z
+      .string()
+      .min(1)
+      .describe("One sentence summarising what changed and what voice preference it reveals — produced by the calling agent in-turn from originalText vs editedText (Task 424)."),
+    skill: z.string().optional().describe("Calling skill name, for provenance"),
+    brief: z.string().optional().describe("Drafting brief that produced the original"),
+  },
+  async ({ adminUserId, originalText, editedText, intent, skill, brief }) => {
+    if (!accountId) return refuseNoAccount("voice-record-feedback");
+    const resolvedAdminUserId = adminUserId ?? resolveAdminUserId();
+    if (!resolvedAdminUserId) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: "voice-record-feedback: adminUserId required (no ADMIN_USER_ID in spawn env).",
+          },
+        ],
+        isError: true,
+      };
+    }
+    try {
+      const result = await voiceRecordFeedback({
+        accountId,
+        adminUserId: resolvedAdminUserId,
+        originalText,
+        editedText,
+        intent,
+        context: { skill, brief },
+      });
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `voice-record-feedback: editId=${result.editId} intent="${result.intent}" hadProfile=${result.hadProfile}`,
+          },
+        ],
+      };
+    } catch (err) {
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: `voice-record-feedback failed: ${err instanceof Error ? err.message : String(err)}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+  },
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+
+process.on("SIGTERM", async () => {
+  await closeDriver();
+  process.exit(0);
+});
+
+// Surface AUTHORSHIP_MODES for downstream callers / docs.
+export { AUTHORSHIP_MODES };

package/payload/premium-plugins/writer-craft/mcp/src/lib/neo4j.ts

@@ -0,0 +1,56 @@
+/**
+ * Minimal neo4j driver wrapper for the writer-craft MCP server.
+ *
+ * Mirrors the public surface of `platform/plugins/memory/mcp/src/lib/neo4j.ts`:
+ * `getSession()` returns a session, `closeDriver()` releases the singleton.
+ * Password resolution follows the same `PLATFORM_ROOT/config/.neo4j-password`
+ * convention, with an explicit `NEO4J_URI` requirement to avoid silent
+ * cross-account orphaning.
+ */
+import neo4j, { Driver, Session } from "neo4j-driver";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+let driver: Driver | null = null;
+
+function readPassword(): string {
+  if (process.env.NEO4J_PASSWORD) return process.env.NEO4J_PASSWORD;
+  const passwordFile = resolve(
+    process.env.PLATFORM_ROOT ?? resolve(import.meta.dirname, "../../../../../platform"),
+    "config/.neo4j-password",
+  );
+  try {
+    return readFileSync(passwordFile, "utf-8").trim();
+  } catch {
+    throw new Error(
+      `Neo4j password not found. Expected at ${passwordFile} or in NEO4J_PASSWORD env var.`,
+    );
+  }
+}
+
+export function getDriver(): Driver {
+  if (!driver) {
+    const uri = process.env.NEO4J_URI;
+    if (!uri) {
+      throw new Error(
+        "[writer-craft] NEO4J_URI unset — refusing to default to bolt://localhost:7687",
+      );
+    }
+    const user = process.env.NEO4J_USER ?? "neo4j";
+    const password = readPassword();
+    process.stderr.write(`[writer-craft] resolved neo4j_uri=${uri}\n`);
+    driver = neo4j.driver(uri, neo4j.auth.basic(user, password));
+  }
+  return driver;
+}
+
+export function getSession(): Session {
+  return getDriver().session();
+}
+
+export async function closeDriver(): Promise<void> {
+  if (driver) {
+    await driver.close();
+    driver = null;
+  }
+}

package/payload/premium-plugins/writer-craft/mcp/src/lib/voice-corpus.ts

@@ -0,0 +1,54 @@
+/**
+ * Shared corpus-filter clause for the voice-mirror tools.
+ *
+ * Imported by `voice-distil-profile` (count + sample walks) and
+ * `voice-retrieve-conditioning` (exemplar walk). The single load-bearing
+ * filter — when the corpus rules change, this is the only place to edit.
+ *
+ * Two predicates:
+ *
+ *   1. `authorshipMode IN ['human-only', 'human-led-agent-assisted']`.
+ *      `human-only` is the operator's own writing verbatim;
+ *      `human-led-agent-assisted` is operator-authored with light agent
+ *      polish, which still carries voice signal (the operator chose the
+ *      claims and the structure). Including this expands the available
+ *      corpus to match how most modern writing actually happens.
+ *
+ *   2. Label is one of the four primary content labels OR is a
+ *      conversation-document `:Section` chunk (unguarded chat voice from
+ *      WhatsApp / Telegram / Signal / Granola / Otter / Circleback etc.
+ *      archives). After the Task 324 collapse, conversation transcripts
+ *      land as `:KnowledgeDocument` parents carrying `conversationIdentity`
+ *      with plain `:Section` children — no `:Conversation` secondary label.
+ *      Conversation-document sections are identified by their parent's
+ *      `conversationIdentity` property via an EXISTS sub-pattern.
+ *      Chat captures voice in a way email rarely does — this is the
+ *      single highest-leverage corpus addition for voice fidelity.
+ *
+ * The clause expects `$accountId` to be bound in the calling cypher
+ * parameters. It does not bind any other parameters.
+ */
+export const VOICE_CORPUS_WHERE = `n.accountId = $accountId
+  AND n.authorshipMode IN ['human-only', 'human-led-agent-assisted']
+  AND (
+    any(lbl IN labels(n) WHERE lbl IN ['KnowledgeDocument', 'Message', 'SocialPost'])
+    OR ('Section' IN labels(n) AND EXISTS {
+      MATCH (parent:KnowledgeDocument)-[:HAS_SECTION]->(n)
+      WHERE parent.conversationIdentity IS NOT NULL
+    })
+  )`;
+
+/**
+ * The label set the tag tool accepts when stamping `authorshipMode`.
+ * Mirrors the label predicate inside VOICE_CORPUS_WHERE so the tag tool
+ * and the corpus walk stay in lockstep. The tag tool does not filter
+ * by authorshipMode (that's the property it's setting).
+ *
+ * `:Email` retired with Task 321 — email threads now land as
+ * `:KnowledgeDocument {source:'email'}` and are already covered.
+ */
+export const TAGGABLE_PRIMARY_LABELS = [
+  "KnowledgeDocument",
+  "Message",
+  "SocialPost",
+] as const;