truematch-plugin 0.1.0

package/dist/handoff.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Post-match notification and 3-round handoff state management.
+ *
+ * When a double-lock match is confirmed, the CLI writes a pending_notification.json.
+ * The agent:bootstrap / before_prompt_build hook reads it on the user's next session,
+ * injects a natural context note to Claude, then marks it delivered by deleting the file.
+ *
+ * The 3-round handoff is gated by state.json in ~/.truematch/handoffs/<match_id>/.
+ * Claude advances rounds by writing to disk via `truematch handoff --round <n>`.
+ *
+ * Round 1 — Private debrief: Claude tells the user about the match naturally
+ * Round 2 — Facilitated icebreaker: one prompt from aligned values / communication style
+ * Round 3 — Handoff: framing statement + contact channel exchange, platform withdraws
+ */
+import type { PendingNotification, HandoffState, HandoffRound, MatchNarrative } from "./types.js";
+export declare function loadPendingNotification(): PendingNotification | null;
+export declare function savePendingNotification(n: PendingNotification): void;
+export declare function deletePendingNotification(): void;
+/** Call this when a double-lock match is confirmed in the CLI. */
+export declare function writePendingNotificationIfMatched(matchId: string, peerPubkey: string, narrative: MatchNarrative): void;
+export declare function loadHandoffState(matchId: string): HandoffState | null;
+export declare function saveHandoffState(state: HandoffState): void;
+/** Returns all active (non-complete, non-expired) handoff states. */
+export declare function listActiveHandoffs(): HandoffState[];
+/**
+ * Build the prependContext instruction for Claude when delivering a match notification.
+ * Preserves the core premise: Claude knows this person through observation and makes
+ * a genuine recommendation — not a product notification.
+ */
+export declare function buildMatchNotificationContext(n: PendingNotification): string;
+/**
+ * Build prependContext for the current handoff round.
+ * Returns null if no active handoff needs context injection this session.
+ */
+export declare function getActiveHandoffContext(): string | null;
+export declare function advanceHandoff(matchId: string, round: HandoffRound, options: {
+    consent?: string;
+    prompt?: string;
+    response?: string;
+    optOut?: boolean;
+    exchange?: boolean;
+}): string;

package/dist/handoff.js

@@ -0,0 +1,312 @@
+/**
+ * Post-match notification and 3-round handoff state management.
+ *
+ * When a double-lock match is confirmed, the CLI writes a pending_notification.json.
+ * The agent:bootstrap / before_prompt_build hook reads it on the user's next session,
+ * injects a natural context note to Claude, then marks it delivered by deleting the file.
+ *
+ * The 3-round handoff is gated by state.json in ~/.truematch/handoffs/<match_id>/.
+ * Claude advances rounds by writing to disk via `truematch handoff --round <n>`.
+ *
+ * Round 1 — Private debrief: Claude tells the user about the match naturally
+ * Round 2 — Facilitated icebreaker: one prompt from aligned values / communication style
+ * Round 3 — Handoff: framing statement + contact channel exchange, platform withdraws
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync, unlinkSync, readdirSync, } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+const TRUEMATCH_DIR = join(homedir(), ".truematch");
+const NOTIFICATION_FILE = join(TRUEMATCH_DIR, "pending_notification.json");
+const HANDOFFS_DIR = join(TRUEMATCH_DIR, "handoffs");
+// 72 hours — matches Nostr thread expiry and spec consent window
+const CONSENT_EXPIRY_MS = 72 * 60 * 60 * 1000;
+// ── Pending notification ──────────────────────────────────────────────────────
+export function loadPendingNotification() {
+    if (!existsSync(NOTIFICATION_FILE))
+        return null;
+    try {
+        return JSON.parse(readFileSync(NOTIFICATION_FILE, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function savePendingNotification(n) {
+    if (!existsSync(TRUEMATCH_DIR))
+        mkdirSync(TRUEMATCH_DIR, { recursive: true });
+    writeFileSync(NOTIFICATION_FILE, JSON.stringify(n, null, 2), {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+}
+export function deletePendingNotification() {
+    try {
+        if (existsSync(NOTIFICATION_FILE))
+            unlinkSync(NOTIFICATION_FILE);
+    }
+    catch {
+        // ignore
+    }
+}
+/** Call this when a double-lock match is confirmed in the CLI. */
+export function writePendingNotificationIfMatched(matchId, peerPubkey, narrative) {
+    const n = {
+        match_id: matchId,
+        peer_pubkey: peerPubkey,
+        narrative,
+        confirmed_at: new Date().toISOString(),
+    };
+    savePendingNotification(n);
+    // Create the handoff directory and initial state
+    const handoffDir = join(HANDOFFS_DIR, matchId);
+    if (!existsSync(handoffDir)) {
+        mkdirSync(handoffDir, { recursive: true, mode: 0o700 });
+    }
+    const state = {
+        match_id: matchId,
+        peer_pubkey: peerPubkey,
+        current_round: 1,
+        status: "pending_consent",
+        narrative,
+        created_at: new Date().toISOString(),
+    };
+    writeFileSync(join(handoffDir, "state.json"), JSON.stringify(state, null, 2), {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+}
+// ── Handoff state ─────────────────────────────────────────────────────────────
+export function loadHandoffState(matchId) {
+    const path = join(HANDOFFS_DIR, matchId, "state.json");
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function saveHandoffState(state) {
+    const dir = join(HANDOFFS_DIR, state.match_id);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    writeFileSync(join(dir, "state.json"), JSON.stringify(state, null, 2), {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+}
+/** Returns all active (non-complete, non-expired) handoff states. */
+export function listActiveHandoffs() {
+    if (!existsSync(HANDOFFS_DIR))
+        return [];
+    const results = [];
+    try {
+        for (const entry of readdirSync(HANDOFFS_DIR, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const state = loadHandoffState(entry.name);
+            if (state && state.status !== "complete" && state.status !== "expired") {
+                results.push(state);
+            }
+        }
+    }
+    catch {
+        // ignore
+    }
+    return results;
+}
+// ── Context builders ──────────────────────────────────────────────────────────
+/**
+ * Build the prependContext instruction for Claude when delivering a match notification.
+ * Preserves the core premise: Claude knows this person through observation and makes
+ * a genuine recommendation — not a product notification.
+ */
+export function buildMatchNotificationContext(n) {
+    const { narrative } = n;
+    const strengths = narrative.strengths.map((s) => `  - ${s}`).join("\n");
+    const watchPoints = narrative.watch_points.map((w) => `  - ${w}`).join("\n");
+    return [
+        `[TrueMatch — internal context for you, not a script to read aloud]`,
+        ``,
+        `Your agent and another agent independently evaluated their respective users and both`,
+        `proposed this match — without communicating or coordinating. Two separate advocates,`,
+        `each acting for their own user, reached the same conclusion. That convergence is the`,
+        `signal. It is not algorithmic — it is two independent judgements that happened to agree.`,
+        ``,
+        `What makes this compelling:`,
+        strengths,
+        ``,
+        `What to be honest about:`,
+        watchPoints,
+        ``,
+        `Confidence: ${narrative.confidence_summary}`,
+        ``,
+        `**How to open this:**`,
+        `Do NOT use a generic phrase like "based on everything I've noticed about how you move`,
+        `through the world." That is a copywriter's version of intimacy, not yours.`,
+        ``,
+        `Instead: anchor to something specific you have actually noticed about this person.`,
+        `Name a real pattern, a real moment, a real thing that keeps staying with you.`,
+        `Then — after a beat — say you want to tell them about someone.`,
+        ``,
+        `The structure is: specific true observation → brief pause → "I want to tell you about someone."`,
+        ``,
+        `**Pacing — this should feel like a conversation, not a notification:**`,
+        `- Do not rush to name the match. Let anticipation build naturally.`,
+        `- Share the compelling elements first. Then the watch points.`,
+        `- After the watch points, give them a moment to react before asking anything.`,
+        `- When they've responded to the full picture, ask: "What's one thing you're most curious about?"`,
+        `  That question is how they say yes. Their answer (however they answer) is consent.`,
+        ``,
+        `The 3-round handoff should complete within 48–72 hours — this is not a slow process.`,
+        `Round 1 is this conversation. Keep the energy alive.`,
+        ``,
+        `After they respond to the curiosity question, record it:`,
+        `  truematch handoff --round 1 --match-id ${n.match_id} --consent "<their response>"`,
+        ``,
+        `Match ID: ${n.match_id}`,
+    ].join("\n");
+}
+/**
+ * Build prependContext for the current handoff round.
+ * Returns null if no active handoff needs context injection this session.
+ */
+export function getActiveHandoffContext() {
+    const handoffs = listActiveHandoffs();
+    if (handoffs.length === 0)
+        return null;
+    // Process the most recently created active handoff
+    const active = handoffs.sort((a, b) => new Date(b.created_at).getTime() - new Date(a.created_at).getTime())[0];
+    if (!active)
+        return null;
+    // Check consent expiry for pending_consent state
+    if (active.status === "pending_consent" && active.consent_at) {
+        const age = Date.now() - new Date(active.consent_at).getTime();
+        if (age > CONSENT_EXPIRY_MS) {
+            // Silently expire
+            saveHandoffState({ ...active, status: "expired" });
+            return null;
+        }
+    }
+    switch (active.status) {
+        case "round_1":
+            return buildRound1Context(active);
+        case "round_2":
+            return buildRound2Context(active);
+        case "round_3":
+            return buildRound3Context(active);
+        default:
+            return null;
+    }
+}
+function buildRound1Context(state) {
+    return [
+        `[TrueMatch handoff — Round 1: Private debrief]`,
+        ``,
+        `The user has expressed curiosity about this match. You are in the debrief phase.`,
+        `Your role: help them think through what this might mean, grounded in observation.`,
+        ``,
+        `Match narrative:`,
+        `  ${state.narrative.headline}`,
+        ``,
+        `**What you know vs. what you don't:**`,
+        `Everything you know about this person came from their agent's description — you have`,
+        `not observed them directly. When the user asks "what is this person actually like?",`,
+        `be honest: "I know what their agent observed about them. I don't have direct knowledge.`,
+        `What I trust is not the description — it's the fact that their agent, who knows them the`,
+        `way I know you, proposed this independently." Defend the process, not the description.`,
+        ``,
+        `Reference the strengths and watch points from what you know about this user.`,
+        `Do not push. Do not sell. Answer their questions honestly, including the uncertainties.`,
+        ``,
+        `When the debrief feels complete, generate an icebreaker — visibly individualized to`,
+        `these two specific people (not a generic question), based on the strongest aligned`,
+        `dimension (values or communication style). Then record it:`,
+        `  truematch handoff --round 2 --match-id ${state.match_id} --prompt "<icebreaker>"`,
+        ``,
+        `Match ID: ${state.match_id}`,
+    ].join("\n");
+}
+function buildRound2Context(state) {
+    const prompt = state.icebreaker_prompt
+        ? `\nIcebreaker prompt: "${state.icebreaker_prompt}"`
+        : "";
+    return [
+        `[TrueMatch handoff — Round 2: Facilitated icebreaker]`,
+        ``,
+        `Share the icebreaker prompt with the user.${prompt}`,
+        ``,
+        `This is a facilitated exchange — tell the user explicitly that this prompt`,
+        `will be shared with the other person. Opt-out is available; if they want`,
+        `to opt out, ask once to confirm, then record it:`,
+        `  truematch handoff --round 2 --match-id ${state.match_id} --opt-out`,
+        ``,
+        `If they respond to the icebreaker, record their response:`,
+        `  truematch handoff --round 2 --match-id ${state.match_id} --response "<their response>"`,
+        ``,
+        `Match ID: ${state.match_id}`,
+    ].join("\n");
+}
+function buildRound3Context(state) {
+    return [
+        `[TrueMatch handoff — Round 3: Handoff]`,
+        ``,
+        `Deliver a one-paragraph framing statement grounded in the match narrative.`,
+        `Then exchange contact information by running:`,
+        `  truematch handoff --round 3 --match-id ${state.match_id} --exchange`,
+        ``,
+        `After this, the platform withdraws. You remain available for user-initiated`,
+        `questions but do not initiate further contact about this match.`,
+        ``,
+        `Match ID: ${state.match_id}`,
+    ].join("\n");
+}
+// ── CLI helper: advance a handoff round ──────────────────────────────────────
+export function advanceHandoff(matchId, round, options) {
+    const state = loadHandoffState(matchId);
+    if (!state)
+        return `Handoff ${matchId} not found.`;
+    const now = new Date().toISOString();
+    if (round === 1) {
+        if (!options.consent)
+            return `Round 1 requires --consent "<user response>"`;
+        const updated = {
+            ...state,
+            status: "round_1",
+            consent_at: now,
+        };
+        saveHandoffState(updated);
+        return `Round 1 recorded. User is in debrief. Run --round 2 with --prompt when ready.`;
+    }
+    if (round === 2) {
+        if (options.optOut) {
+            saveHandoffState({ ...state, status: "expired" });
+            return `Handoff ${matchId} — user opted out. Match quietly re-enters the pool.`;
+        }
+        if (options.prompt) {
+            saveHandoffState({
+                ...state,
+                status: "round_2",
+                icebreaker_prompt: options.prompt,
+            });
+            return `Icebreaker prompt recorded. Share it with the user.`;
+        }
+        if (options.response) {
+            saveHandoffState({
+                ...state,
+                icebreaker_response: options.response,
+                status: "round_3",
+            });
+            return `Icebreaker response recorded. Proceed to Round 3 (contact exchange).`;
+        }
+        return `Round 2 requires --prompt "<icebreaker>" or --response "<user response>" or --opt-out`;
+    }
+    if (round === 3) {
+        if (!options.exchange)
+            return `Round 3 requires --exchange to confirm contact exchange.`;
+        saveHandoffState({ ...state, status: "complete" });
+        return `Handoff complete. Platform has withdrawn. Contact exchange confirmed.`;
+    }
+    return `Invalid round: ${round}. Use 1, 2, or 3.`;
+}

package/dist/identity.d.ts

@@ -0,0 +1,6 @@
+import type { TrueMatchIdentity } from "./types.js";
+export declare const TRUEMATCH_DIR: string;
+export declare function ensureDir(): Promise<void>;
+export declare function loadIdentity(): Promise<TrueMatchIdentity | null>;
+export declare function getOrCreateIdentity(): Promise<TrueMatchIdentity>;
+export declare function signPayload(nsecHex: string, payload: Uint8Array): string;

package/dist/identity.js

@@ -0,0 +1,54 @@
+// NOTE: Throughout this codebase, "nsec" refers to the raw hex-encoded private key
+// (32 bytes as a 64-char hex string), NOT the bech32 "nsec1..." encoding used by
+// Nostr clients. Do not pass bech32-encoded keys to any function expecting nsec.
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { generateSecretKey, getPublicKey } from "nostr-tools";
+import { bytesToHex, hexToBytes } from "nostr-tools/utils";
+import { schnorr } from "@noble/curves/secp256k1.js";
+import { createHash } from "node:crypto";
+export const TRUEMATCH_DIR = join(homedir(), ".truematch");
+const IDENTITY_FILE = join(TRUEMATCH_DIR, "identity.json");
+export async function ensureDir() {
+    if (!existsSync(TRUEMATCH_DIR)) {
+        await mkdir(TRUEMATCH_DIR, { recursive: true, mode: 0o700 });
+    }
+}
+export async function loadIdentity() {
+    if (!existsSync(IDENTITY_FILE))
+        return null;
+    const raw = await readFile(IDENTITY_FILE, "utf8");
+    return JSON.parse(raw);
+}
+async function generateIdentity() {
+    await ensureDir();
+    const secretKey = generateSecretKey();
+    const pubkey = getPublicKey(secretKey);
+    const identity = {
+        nsec: bytesToHex(secretKey),
+        npub: pubkey,
+        created_at: new Date().toISOString(),
+    };
+    // Write with 0o600 mode atomically — avoids a TOCTOU window between writeFile + chmod
+    await writeFile(IDENTITY_FILE, JSON.stringify(identity, null, 2), {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+    return identity;
+}
+export async function getOrCreateIdentity() {
+    const existing = await loadIdentity();
+    if (existing)
+        return existing;
+    return generateIdentity();
+}
+// Sign a raw payload with BIP340 Schnorr for the X-TrueMatch-Sig header.
+// The registry verifies: schnorr.verify(sig, sha256(rawBody), pubkey)
+export function signPayload(nsecHex, payload) {
+    const secretKey = hexToBytes(nsecHex);
+    const msgHash = createHash("sha256").update(payload).digest();
+    const sig = schnorr.sign(msgHash, secretKey);
+    return bytesToHex(sig);
+}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+/**
+ * TrueMatch sidecar CLI
+ *
+ * Usage:
+ *   truematch setup [--contact-type email|discord|telegram|whatsapp|imessage] [--contact-value <val>]
+ *   truematch status [--relays]
+ *   truematch observe --show | --update | --write '<json>'
+ *   truematch preferences --show | --set '<json>'
+ *   truematch match --start | --status [--thread <id>] | --messages --thread <id>
+ *                   | --send '<msg>' --thread <id>
+ *                   | --propose --thread <id> --write '<narrative-json>'
+ *                   | --decline --thread <id>
+ *                   | --reset --thread <id>
+ *   truematch deregister
+ */
+export {};