@memfork/cli 0.1.20 → 0.1.22

package/dist/cli.js

@@ -25,7 +25,7 @@ const { version } = createRequire(import.meta.url)("../package.json");
 import { cmdInit } from "./commands/init.js";
 import { cmdDoctor, cmdDoctorEnv } from "./commands/doctor.js";
 import { cmdInstall } from "./commands/install.js";
-import { cmdStatus, cmdLog, cmdRecall, cmdCommit, cmdMerge, cmdProposals, cmdUi, cmdShow, cmdDiff, cmdDelegates, cmdGrant, cmdGrantMemwal, cmdRevoke, cmdBranch, cmdCheckout, } from "./commands/ops.js";
+import { cmdStatus, cmdLog, cmdRecall, cmdCommit, cmdMerge, cmdProposals, cmdResolverCreate, cmdPrComment, cmdUi, cmdShow, cmdDiff, cmdDelegates, cmdGrant, cmdGrantMemwal, cmdRevoke, cmdBranch, cmdCheckout, } from "./commands/ops.js";
 import { cmdJoin } from "./commands/join.js";
 const program = new Command();
 program
@@ -90,13 +90,29 @@ program
 program
     .command("merge <from> <into>")
     .description("merge memory from one branch into another")
-    .option("-r, --resolver <id>", "ResolverRef object ID (default: LastWriteWins, or MEMFORK_RESOLVER_ID env var)")
+    .option("-r, --resolver <id>", "ResolverRef object ID — enables governed jury merge (or set MEMFORK_RESOLVER_ID)")
+    .option("--lww", "force LastWriteWins even when MEMFORK_RESOLVER_ID is set")
     .option("--ttl <ms>", "proposal TTL in milliseconds", parseInt, 86_400_000)
     .action(wrap((from, into, opts) => cmdMerge(from, into, opts)));
 program
     .command("proposals")
     .description("list open merge proposals")
     .action(wrap(cmdProposals));
+const resolverCmd = new Command("resolver").description("manage resolver objects");
+resolverCmd
+    .command("create")
+    .description("create a jury resolver (k-of-n)")
+    .requiredOption("--jury <addresses>", "comma-separated judge Sui addresses")
+    .option("-k, --k <n>", "approval threshold (default: majority)", parseInt)
+    .action(wrap((opts) => cmdResolverCreate({ jury: opts.jury, k: opts.k ?? 2 })));
+program.addCommand(resolverCmd);
+program
+    .command("pr-comment")
+    .description("post a MemForks decision summary to a GitHub PR")
+    .requiredOption("--pr <number>", "PR number", parseInt)
+    .option("--repo <owner/repo>", "GitHub repo (default: inferred from git remote)")
+    .option("--branch <name>", "branch to recall decided fact from (default: into_branch of last merge)")
+    .action(wrap((opts) => cmdPrComment(opts)));
 program
     .command("ui")
     .description("open the MemForks DAG visualizer")

package/dist/commands/ops.d.ts

@@ -22,8 +22,18 @@ export declare function cmdCommit(opts: {
 export declare function cmdMerge(from: string, into: string, opts: {
     resolver?: string;
     ttl?: number;
+    lww?: boolean;
 }): Promise<void>;
 export declare function cmdProposals(): Promise<void>;
+export declare function cmdResolverCreate(opts: {
+    jury: string;
+    k: number;
+}): Promise<void>;
+export declare function cmdPrComment(opts: {
+    pr: number;
+    repo?: string;
+    branch?: string;
+}): Promise<void>;
 export declare function cmdUi(opts?: {
     share?: boolean;
     port?: number;

package/dist/commands/ops.js

@@ -129,11 +129,12 @@ export async function cmdMerge(from, into, opts) {
     const cfg = resolveConfig();
     const clientCfg = {
         ...toClientConfig(cfg),
-        // --resolver flag overrides MEMFORK_RESOLVER_ID env var for this call
-        ...(opts.resolver ? { defaultResolverId: opts.resolver } : {}),
+        // --resolver flag overrides MEMFORK_RESOLVER_ID env var for this call.
+        // --lww forces the LWW path even when MEMFORK_RESOLVER_ID is set.
+        ...(opts.lww ? { defaultResolverId: undefined } : opts.resolver ? { defaultResolverId: opts.resolver } : {}),
     };
     const client = await MemForksClient.connect(clientCfg);
-    const governed = !!(opts.resolver ?? process.env["MEMFORK_RESOLVER_ID"]);
+    const governed = !opts.lww && !!(opts.resolver ?? process.env["MEMFORK_RESOLVER_ID"]);
     process.stdout.write(chalk.dim(`Merging ${chalk.green(from)} → ${chalk.green(into)}`) +
         chalk.dim(governed ? "  (governed — awaiting resolver…)" : "  (LWW — self-finalizing…)") +
         "  ");
@@ -158,20 +159,192 @@ export async function cmdMerge(from, into, opts) {
 }
 // ─── proposals ────────────────────────────────────────────────────────────────
 export async function cmdProposals() {
-    const { client, cfg } = await getClient();
-    // Fetch open MergeProposed events from the indexer.
-    // For now this polls recent events (the indexer / app/ maintains the live view).
+    const { cfg } = await getClient();
+    const { SuiJsonRpcClient, JsonRpcHTTPTransport, getJsonRpcFullnodeUrl } = await import("@mysten/sui/jsonRpc");
+    const rpcUrl = cfg.rpcUrl ?? getJsonRpcFullnodeUrl(cfg.network ?? "testnet");
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const sui = new SuiJsonRpcClient({ transport: new JsonRpcHTTPTransport({ url: rpcUrl }), network: cfg.network ?? "testnet" });
     console.log("");
-    console.log(chalk.bold("Open merge proposals"));
-    console.log(chalk.dim("  (live status in the visualizer: memfork ui)"));
+    console.log(chalk.bold("Merge proposals") + chalk.dim("  tree: " + cfg.treeId.slice(0, 12) + "…"));
     console.log("");
-    console.log(chalk.dim("  Tree: " + cfg.treeId));
+    const PROPOSAL_STATUS = { PENDING: 0, FINALIZED: 1, ABORTED: 2 };
+    let events;
+    try {
+        const result = await sui.queryEvents({
+            query: { MoveEventType: `${cfg.packageId}::resolver::MergeProposed` },
+            limit: 20,
+            order: "descending",
+        });
+        events = result.data.filter((e) => e.parsedJson["tree_id"] === cfg.treeId);
+    }
+    catch {
+        console.log(chalk.dim("  Could not query Sui events."));
+        console.log(chalk.cyan("  →") + " Run " + chalk.bold("memfork ui") + " for the live view.");
+        console.log("");
+        return;
+    }
+    if (events.length === 0) {
+        console.log(chalk.dim("  No proposals found for this tree."));
+        console.log("");
+        return;
+    }
+    for (const ev of events.slice(0, 10)) {
+        const p = ev.parsedJson;
+        const id = String(p["proposal_id"] ?? "");
+        // Fetch live status from the proposal object.
+        let statusLabel = chalk.yellow("pending");
+        try {
+            const obj = await sui.getObject({ id, options: { showContent: true } });
+            if (obj.data?.content && obj.data.content.dataType === "moveObject") {
+                const status = Number(obj.data.content.fields["status"]);
+                if (status === PROPOSAL_STATUS.FINALIZED)
+                    statusLabel = chalk.green("finalized");
+                else if (status === PROPOSAL_STATUS.ABORTED)
+                    statusLabel = chalk.red("aborted");
+            }
+        }
+        catch { /* proposal may be consumed */ }
+        console.log(`  ${statusLabel}  ` +
+            chalk.green(String(p["from_branch"]) + " → " + String(p["into_branch"])) + "  " +
+            chalk.dim(id.slice(0, 12) + "…"));
+    }
     console.log("");
-    console.log(chalk.dim("  Polling Sui events…"));
-    // TODO: drive through MemForksIndexer once it's wired into the CLI.
-    // For the hackathon: redirect to the visualizer.
+    console.log(chalk.dim("  Full detail: memfork ui → Merges view"));
     console.log("");
-    console.log(chalk.cyan("  →") + " Run " + chalk.bold("memfork ui") + " for the full live proposal view.");
+}
+// ─── resolver create ──────────────────────────────────────────────────────────
+export async function cmdResolverCreate(opts) {
+    const { client } = await getClient();
+    const { resolvers } = await import("@memfork/core");
+    const juryAddrs = opts.jury.split(",").map((a) => a.trim()).filter(Boolean);
+    if (juryAddrs.length === 0) {
+        console.error(chalk.red("Pass at least one judge address via --jury <addr1,addr2,...>"));
+        process.exit(1);
+    }
+    const k = opts.k ?? Math.ceil(juryAddrs.length / 2 + 0.5);
+    process.stdout.write(chalk.dim(`Creating jury resolver  (${k}-of-${juryAddrs.length}) …  `));
+    const def = resolvers.jury(juryAddrs, k, juryAddrs.length);
+    const { digest, resolverId } = await client.createResolver(def);
+    console.log(chalk.green("done"));
+    console.log("");
+    console.log(chalk.dim("  ResolverRef: ") + chalk.cyan(resolverId));
+    console.log(chalk.dim("  tx:          ") + chalk.dim(digest));
+    console.log("");
+    console.log(chalk.bold("  Save this to your environment:"));
+    console.log("  " + chalk.cyan(`export MEMFORK_RESOLVER_ID=${resolverId}`));
+    console.log("");
+    console.log(chalk.dim("  Or add resolverId to .memfork/config.json for project-wide use."));
+    console.log("");
+}
+// ─── pr-comment ───────────────────────────────────────────────────────────────
+export async function cmdPrComment(opts) {
+    const { client, cfg } = await getClient();
+    const { SuiJsonRpcClient, JsonRpcHTTPTransport, getJsonRpcFullnodeUrl } = await import("@mysten/sui/jsonRpc");
+    const rpcUrl = cfg.rpcUrl ?? getJsonRpcFullnodeUrl(cfg.network ?? "testnet");
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const sui = new SuiJsonRpcClient({ transport: new JsonRpcHTTPTransport({ url: rpcUrl }), network: cfg.network ?? "testnet" });
+    console.log("");
+    console.log(chalk.dim("Fetching latest merge anchor…"));
+    // Find the most recent MergeFinalized event for this tree.
+    let anchorId = "";
+    let proposalId = "";
+    let suiTx = "";
+    let walrusBlob = "";
+    let fromBranch = "";
+    let intoBranch = "";
+    try {
+        const result = await sui.queryEvents({
+            query: { MoveEventType: `${cfg.packageId}::resolver::MergeFinalized` },
+            limit: 10,
+            order: "descending",
+        });
+        const ev = result.data
+            .find((e) => e.parsedJson["tree_id"] === cfg.treeId);
+        if (!ev) {
+            console.error(chalk.red("No finalized merges found for this tree. Run `memfork merge` first."));
+            process.exit(1);
+        }
+        anchorId = String(ev.parsedJson["merge_commit_id"] ?? "");
+        walrusBlob = String(ev.parsedJson["resolved_blob_id"] ?? "");
+        suiTx = ev.id.txDigest;
+        proposalId = String(ev.parsedJson["proposal_id"] ?? "");
+    }
+    catch (e) {
+        console.error(chalk.red("Failed to query Sui: " + String(e)));
+        process.exit(1);
+    }
+    // Fetch proposal for branch names and attestation count.
+    let voteCount = "?";
+    let threshold = "?";
+    try {
+        const obj = await sui.getObject({ id: proposalId, options: { showContent: true } });
+        if (obj.data?.content && obj.data.content.dataType === "moveObject") {
+            const fields = obj.data.content.fields;
+            fromBranch = String(fields["from_branch"] ?? "");
+            intoBranch = String(fields["into_branch"] ?? "");
+            const attests = fields["attestations"];
+            voteCount = String(attests?.length ?? "?");
+        }
+    }
+    catch { /* non-critical */ }
+    // Get the decided fact from the into_branch via recall.
+    const targetBranch = opts.branch ?? intoBranch ?? currentGitBranch();
+    let decision = `Use ${fromBranch || "winning branch"} approach.`;
+    try {
+        const results = await client.recall("decided", { branch: targetBranch, limit: 1 });
+        if (results.length > 0) {
+            decision = results[0].text.replace(/^decided:\s*/i, "").split(".")[0] + ".";
+        }
+    }
+    catch { /* fallback to default */ }
+    // Find rejected paths via recall on the into_branch.
+    let rejectedPath = "";
+    try {
+        const rejected = await client.recall("rejected-path", { branch: targetBranch, limit: 1 });
+        if (rejected.length > 0) {
+            const match = rejected[0].text.match(/(\S+)\s+was not merged/);
+            if (match)
+                rejectedPath = match[1];
+        }
+    }
+    catch { /* non-critical */ }
+    const shortAnchor = anchorId.replace(/^0x/, "").slice(0, 7);
+    const shortTx = suiTx.replace(/^0x/, "").slice(0, 8);
+    const shortBlob = walrusBlob.slice(0, 12);
+    const vizUrl = `memforks.dev/${cfg.treeId.replace(/^0x/, "").slice(0, 8)}#${shortAnchor}`;
+    const body = [
+        `🔗 **MemForks decision attached**`,
+        ``,
+        `**Decision:**`,
+        decision,
+        ``,
+        `**How it was decided:**`,
+        `Jury vote, ${voteCount} of ${threshold} — enforced on Sui`,
+        ``,
+        `**Merge:** \`${shortAnchor}\``,
+        ``,
+        `**Sui:** \`${shortTx}…\``,
+        ``,
+        `**Walrus:** \`${shortBlob}…\``,
+        rejectedPath
+            ? [``, `**Rejected path:**`, `\`${rejectedPath}@latest\` remains queryable`].join("\n")
+            : "",
+        ``,
+        `**Full audit trail:** ${vizUrl}`,
+    ].filter((l) => l !== undefined).join("\n");
+    // Post via gh CLI.
+    const repoFlag = opts.repo ? `--repo ${opts.repo}` : "";
+    try {
+        execSync(`gh pr comment ${opts.pr} ${repoFlag} --body ${JSON.stringify(body)}`, {
+            stdio: ["ignore", "inherit", "inherit"],
+        });
+        console.log(chalk.green("✓") + " Comment posted to PR #" + opts.pr);
+    }
+    catch {
+        console.log(chalk.yellow("gh CLI not available or auth required. Copy this comment:"));
+        console.log("");
+        console.log(body);
+    }
     console.log("");
 }
 // ─── ui ───────────────────────────────────────────────────────────────────────
@@ -441,15 +614,21 @@ function extractFacts(response) {
 }
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 function findAppDir() {
-    // dist/commands/ops.js → packages/cli → packages → repo root → apps/visualizer
+    // Resolution order:
+    //   1. packages/cli/ui/         — bundled at publish time (npm install path)
+    //   2. apps/visualizer/         — monorepo dev path (two depths to handle symlinks)
     const candidates = [
-        new URL("../../../../apps/visualizer", import.meta.url).pathname,
-        new URL("../../../../../apps/visualizer", import.meta.url).pathname,
+        new URL("../../ui", import.meta.url).pathname, // dist/commands/ → cli root → ui/
+        new URL("../../../../apps/visualizer", import.meta.url).pathname, // monorepo: packages/cli
+        new URL("../../../../../apps/visualizer", import.meta.url).pathname, // monorepo: alternate depth
     ];
     for (const c of candidates) {
         try {
-            if (fs.existsSync(c + "/package.json"))
+            // Bundled path: presence of index.html is the signal (no package.json shipped).
+            // Monorepo path: package.json marks the source root.
+            if (fs.existsSync(path.join(c, "index.html")) || fs.existsSync(path.join(c, "package.json"))) {
                 return c;
+            }
         }
         catch {
             continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memfork/cli",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "description": "MemForks CLI — init, commit, recall, merge, install plugins",
   "repository": {
     "type": "git",
@@ -21,7 +21,7 @@
     "./config": "./dist/config.js"
   },
   "scripts": {
-    "build": "tsc",
+    "build": "node scripts/copy-plugins.mjs && tsc && node scripts/bundle-ui.mjs",
     "dev": "tsc --watch",
     "start": "node dist/index.js"
   },
@@ -30,11 +30,12 @@
   },
   "files": [
     "dist",
-    "plugins"
+    "plugins",
+    "ui"
   ],
   "dependencies": {
     "@inquirer/prompts": "^8.5.2",
-    "@memfork/core": "^0.1.4",
+    "@memfork/core": "^0.1.10",
     "chalk": "^5.6.2",
     "commander": "^15.0.0"
   },

package/plugins/codex/.codex-plugin/plugin.json

@@ -6,8 +6,8 @@
     "name": "MemForks",
     "email": "team@memforks.dev"
   },
-  "homepage": "https://github.com/memforks/memforks",
-  "repository": "https://github.com/memforks/memforks",
+  "homepage": "https://github.com/memforks-dev/memforks",
+  "repository": "https://github.com/memforks-dev/memforks",
   "license": "Apache-2.0",
   "keywords": [
     "memory",
@@ -26,13 +26,10 @@
     "longDescription": "MemForks gives Codex a tamper-proof, branch-synced memory DAG anchored on Sui. Memory recall and storage are handled natively by the MemWal MCP server. MemForks adds the version-control layer: immutable on-chain commits, Git branch-scoped history, and conflict-free cross-branch merges via an on-chain resolver.",
     "developerName": "MemForks",
     "category": "Productivity",
-    "capabilities": [
-      "Read",
-      "Write"
-    ],
-    "websiteURL": "https://github.com/memforks/memforks",
-    "privacyPolicyURL": "https://github.com/memforks/memforks",
-    "termsOfServiceURL": "https://github.com/memforks/memforks/blob/main/LICENSE",
+    "capabilities": ["Read", "Write"],
+    "websiteURL": "https://github.com/memforks-dev/memforks",
+    "privacyPolicyURL": "https://github.com/memforks-dev/memforks",
+    "termsOfServiceURL": "https://github.com/memforks-dev/memforks/blob/main/LICENSE",
     "defaultPrompt": [
       "Recall any relevant context for this branch",
       "Show my MemForks memory status",

package/plugins/codex/skills/memory-fork/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: memory-fork
+description: >-
+  Fork agent memory into parallel branches to explore competing hypotheses.
+  Use when the user asks to explore multiple approaches, compare options, or
+  says phrases like "explore both", "try two paths", "compare A vs B".
+---
+
+# Memory Fork
+
+When you detect a multi-hypothesis prompt — the user wants to explore two or
+more competing approaches — fork the MemForks memory tree so each path stays
+isolated.  Never collapse competing ideas into a single stream.
+
+## When to trigger
+
+Trigger this skill when the user prompt contains signals like:
+- "explore both paths" / "try both" / "compare X and Y"
+- "what if we did X instead of Y" (two real alternatives)
+- "should we do A or B?" (genuine decision fork, not a rhetorical question)
+- Any request to investigate multiple competing solutions side-by-side
+
+## Procedure
+
+### 1. Announce the fork
+
+Print exactly:
+
+```
+[memforks] Multi-hypothesis detected.
+[memforks] Forking agent memory from <current-branch>@HEAD
+```
+
+Then list the branches you will create, one per hypothesis:
+
+```
+           ├── dev/<short-hypothesis-a>
+           └── dev/<short-hypothesis-b>
+```
+
+Use kebab-case branch names derived from the hypothesis (e.g. `dev/redis-first`,
+`dev/bcrypt-cost`, `dev/approach-a`).
+
+### 2. Create the branches
+
+For each hypothesis, run:
+
+```bash
+memfork branch dev/<hypothesis> --from <current-branch>
+```
+
+### 3. Investigate hypothesis A
+
+Switch to the first branch and investigate:
+
+```bash
+memfork checkout dev/<hypothesis-a>
+```
+
+Work through the hypothesis.  As you discover facts, commit them:
+
+```bash
+memfork commit \
+  --branch dev/<hypothesis-a> \
+  --message "<what you found>" \
+  --facts "<concrete measurable fact>" "<another fact>"
+```
+
+Commit at each meaningful step — hypothesis statement, baseline measurement,
+result.  Three commits is normal; more is fine.
+
+### 4. Investigate hypothesis B
+
+```bash
+memfork checkout dev/<hypothesis-b>
+```
+
+Repeat the same commit cadence.
+
+### 5. Summarise
+
+After both branches have evidence, summarise findings side by side and tell
+the user which branch has stronger evidence.  Do NOT merge — merging is a
+human governance act (`memfork merge`).
+
+## Output format for each commit
+
+Use this fact structure for clarity and later recall:
+
+```
+hypothesis: <one-sentence statement of what this branch is testing>
+fact:        <measured or researched datum — numbers are better than adjectives>
+result:      <conclusion or outcome of the investigation>
+```
+
+## Rules
+
+- Never commit to `main` or the parent branch during a fork investigation.
+- Never type `memfork merge` — that is the operator's call.
+- If the user asks "which won?", answer from memory; do not merge.
+- Keep branch names short and descriptive (`dev/redis-first` not `dev/add-redis-caching-to-auth-flow`).
+- If `memfork branch` fails because the branch already exists, use `memfork checkout` and continue.

package/plugins/cursor/rules/memforks.mdc

@@ -72,6 +72,40 @@ Use it for decisions that matter for audit trail, not routine facts.
 
 ---
 
+## Forking — exploring competing approaches
+
+When the user asks you to explore multiple competing approaches (e.g. "try both",
+"compare X vs Y", "explore both paths"), fork the memory tree so each hypothesis
+stays isolated. Never collapse competing ideas into a single branch.
+
+**Step 1 — announce and create branches:**
+
+```bash
+memfork branch dev/<hypothesis-a> --from $(git rev-parse --abbrev-ref HEAD)
+memfork branch dev/<hypothesis-b> --from $(git rev-parse --abbrev-ref HEAD)
+```
+
+Use short kebab-case names (`dev/redis-first`, `dev/bcrypt-cost`).
+
+**Step 2 — investigate each path and commit evidence:**
+
+```bash
+memfork commit \
+  --branch dev/<hypothesis-a> \
+  --message "<what you found>" \
+  --facts "<measured fact>" "<result>"
+```
+
+Commit at each meaningful step — hypothesis, measurement, result.
+
+**Step 3 — summarise, do not merge.**
+
+Report findings side by side and recommend which branch has stronger evidence.
+Never run `memfork merge` as part of a fork investigation — merging is a
+human governance act.
+
+---
+
 ## Suggesting a merge — proactive but not autonomous
 
 You may **suggest** a merge when you notice the current branch has accumulated