@memfork/cli 0.1.0

package/dist/commands/install.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `memfork install <target>`
+ *
+ * Installs MemForks into an IDE client. Two responsibilities:
+ *
+ *   1. Configure the MemWal MCP server (Streamable HTTP) using the credentials
+ *      that `memfork init` already provisioned — no browser login needed.
+ *
+ *   2. Install the MemForks rule/skill that tells the agent:
+ *        - use memwal_recall / memwal_remember for memory (via MCP)
+ *        - use memfork commit / merge for the on-chain DAG
+ *
+ * Targets:
+ *   cursor   — ~/.cursor/mcp.json  +  .cursor/rules/memforks.mdc
+ *   codex    — ~/.codex/config.toml  +  installs plugin into this project
+ */
+export declare function cmdInstall(target: string): void;

package/dist/commands/install.js

@@ -0,0 +1,196 @@
+/**
+ * `memfork install <target>`
+ *
+ * Installs MemForks into an IDE client. Two responsibilities:
+ *
+ *   1. Configure the MemWal MCP server (Streamable HTTP) using the credentials
+ *      that `memfork init` already provisioned — no browser login needed.
+ *
+ *   2. Install the MemForks rule/skill that tells the agent:
+ *        - use memwal_recall / memwal_remember for memory (via MCP)
+ *        - use memfork commit / merge for the on-chain DAG
+ *
+ * Targets:
+ *   cursor   — ~/.cursor/mcp.json  +  .cursor/rules/memforks.mdc
+ *   codex    — ~/.codex/config.toml  +  installs plugin into this project
+ */
+import chalk from "chalk";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { readCredentials, readProjectConfig, MEMWAL_CONSTANTS } from "../config.js";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PLUGIN_ROOT = path.resolve(__dirname, "..", "..", "..", "plugins");
+function ok(s) { return chalk.green("✓") + " " + s; }
+function warn(s) { return chalk.yellow("⚠") + " " + s; }
+function tip(s) { return chalk.cyan("→") + " " + s; }
+function dim(s) { return chalk.dim(s); }
+function resolveMcpCreds() {
+    const project = readProjectConfig();
+    if (!project)
+        return null;
+    if (!project.treeId)
+        return null;
+    const creds = readCredentials();
+    const tree = creds.trees[project.treeId];
+    if (!tree?.memwalAccountId || !tree?.memwalKey)
+        return null;
+    const rawNetwork = project.network ?? "testnet";
+    const network = (rawNetwork === "mainnet" ? "mainnet" : "testnet");
+    const relayer = MEMWAL_CONSTANTS[network].relayer;
+    return {
+        relayerUrl: relayer + "/api/mcp",
+        accountId: tree.memwalAccountId,
+        delegateKey: tree.memwalKey,
+    };
+}
+// ─── Cursor ───────────────────────────────────────────────────────────────────
+function installCursor(cwd) {
+    console.log("");
+    console.log(chalk.bold("Installing MemForks — Cursor") + dim("  →  " + cwd));
+    console.log("");
+    // ── 1. MemWal MCP → ~/.cursor/mcp.json ────────────────────────────────────
+    const mcpJsonPath = path.join(os.homedir(), ".cursor", "mcp.json");
+    const mcpCreds = resolveMcpCreds();
+    if (mcpCreds) {
+        upsertCursorMcp(mcpJsonPath, mcpCreds);
+        console.log(ok(`MemWal MCP: ${dim(mcpJsonPath)}`));
+        console.log(dim(`    endpoint:   ${mcpCreds.relayerUrl}`));
+        console.log(dim(`    account:    ${mcpCreds.accountId.slice(0, 18)}…`));
+        console.log(dim(`    auth:       Bearer (delegate key)`));
+    }
+    else {
+        console.log(warn("MemWal MCP skipped — run `memfork init` first to provision credentials."));
+        console.log(dim("    You can manually run `memfork install cursor` again after init."));
+    }
+    // ── 2. Cursor rule → .cursor/rules/memforks.mdc ───────────────────────────
+    const rulesDir = path.join(cwd, ".cursor", "rules");
+    fs.mkdirSync(rulesDir, { recursive: true });
+    const ruleSrc = path.join(PLUGIN_ROOT, "cursor", "rules", "memforks.mdc");
+    const ruleDst = path.join(rulesDir, "memforks.mdc");
+    fs.copyFileSync(ruleSrc, ruleDst);
+    console.log(ok(`Rule:  .cursor/rules/memforks.mdc`));
+    // ── Summary ────────────────────────────────────────────────────────────────
+    console.log("");
+    console.log(chalk.bold("Done.") + " Restart Cursor to pick up the MCP server.");
+    console.log("");
+    console.log(tip("The agent now has:"));
+    console.log(dim("    memwal_recall / memwal_remember  — memory storage via MemWal MCP"));
+    console.log(dim("    memwal_analyze                   — extract facts from conversation"));
+    console.log(dim("    memfork commit / merge           — on-chain DAG anchoring"));
+    console.log("");
+    console.log(tip("memfork doctor   — verify the full setup"));
+    console.log(tip("memfork status   — show current memory tree"));
+    console.log("");
+}
+function upsertCursorMcp(mcpJsonPath, creds) {
+    fs.mkdirSync(path.dirname(mcpJsonPath), { recursive: true });
+    let config = {};
+    if (fs.existsSync(mcpJsonPath)) {
+        try {
+            config = JSON.parse(fs.readFileSync(mcpJsonPath, "utf8"));
+        }
+        catch { /* start fresh if corrupt */ }
+    }
+    const mcpServers = (config.mcpServers ?? {});
+    mcpServers["memwal"] = {
+        url: creds.relayerUrl,
+        headers: {
+            "Authorization": `Bearer ${creds.delegateKey}`,
+            "x-memwal-account-id": creds.accountId,
+        },
+    };
+    config.mcpServers = mcpServers;
+    fs.writeFileSync(mcpJsonPath, JSON.stringify(config, null, 2) + "\n", "utf8");
+}
+// ─── Codex ────────────────────────────────────────────────────────────────────
+function installCodex(cwd) {
+    console.log("");
+    console.log(chalk.bold("Installing MemForks — Codex") + dim("  →  " + cwd));
+    console.log("");
+    // ── 1. MemWal MCP → ~/.codex/config.toml ─────────────────────────────────
+    const configTomlPath = path.join(os.homedir(), ".codex", "config.toml");
+    const mcpCreds = resolveMcpCreds();
+    if (mcpCreds) {
+        upsertCodexMcp(configTomlPath, mcpCreds);
+        console.log(ok(`MemWal MCP: ${dim(configTomlPath)}`));
+        console.log(dim(`    endpoint:   ${mcpCreds.relayerUrl}`));
+        console.log(dim(`    account:    ${mcpCreds.accountId.slice(0, 18)}…`));
+    }
+    else {
+        console.log(warn("MemWal MCP skipped — run `memfork init` first to provision credentials."));
+    }
+    // ── 2. Codex plugin (skills + metadata) ──────────────────────────────────
+    const pluginSrc = path.join(PLUGIN_ROOT, "codex");
+    const pluginDst = path.join(cwd, ".codex-plugin");
+    copyDir(pluginSrc, pluginDst);
+    console.log(ok("Plugin: .codex-plugin/  (skills + plugin.json)"));
+    // ── Summary ────────────────────────────────────────────────────────────────
+    console.log("");
+    console.log(chalk.bold("Done."));
+    console.log("");
+    console.log(tip("Register the plugin in Codex:"));
+    console.log(dim("    codex plugin add .codex-plugin"));
+    console.log("");
+    console.log(tip("The agent now has:"));
+    console.log(dim("    memwal_recall / memwal_remember  — memory storage via MemWal MCP"));
+    console.log(dim("    memwal_analyze                   — extract facts from conversation"));
+    console.log(dim("    memfork commit / merge           — on-chain DAG anchoring"));
+    console.log("");
+    console.log(tip("memfork doctor   — verify the full setup"));
+    console.log("");
+}
+function upsertCodexMcp(tomlPath, creds) {
+    fs.mkdirSync(path.dirname(tomlPath), { recursive: true });
+    // Read existing TOML as raw text — we do minimal surgery to avoid
+    // a full TOML parser dependency. We look for an existing [mcp_servers.memwal]
+    // block and replace it, or append if absent.
+    let existing = "";
+    if (fs.existsSync(tomlPath)) {
+        existing = fs.readFileSync(tomlPath, "utf8");
+    }
+    const block = `
+[mcp_servers.memwal]
+transport = "http"
+url = "${creds.relayerUrl}"
+headers = { Authorization = "Bearer ${creds.delegateKey}", x-memwal-account-id = "${creds.accountId}" }
+`;
+    if (existing.includes("[mcp_servers.memwal]")) {
+        // Replace the existing block — find from the header to the next blank line / EOF.
+        existing = existing.replace(/\[mcp_servers\.memwal\][^\[]*/s, block.trimStart());
+    }
+    else {
+        existing = existing.trimEnd() + "\n" + block;
+    }
+    fs.writeFileSync(tomlPath, existing, "utf8");
+}
+function copyDir(src, dst) {
+    fs.mkdirSync(dst, { recursive: true });
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+        const srcPath = path.join(src, entry.name);
+        const dstPath = path.join(dst, entry.name);
+        if (entry.isDirectory()) {
+            copyDir(srcPath, dstPath);
+        }
+        else {
+            fs.copyFileSync(srcPath, dstPath);
+        }
+    }
+}
+// ─── Command ──────────────────────────────────────────────────────────────────
+export function cmdInstall(target) {
+    const cwd = process.cwd();
+    switch (target.toLowerCase()) {
+        case "cursor":
+            installCursor(cwd);
+            break;
+        case "codex":
+            installCodex(cwd);
+            break;
+        default:
+            console.error(chalk.red(`Unknown install target: ${target}`));
+            console.error("Available targets: cursor, codex");
+            process.exit(1);
+    }
+}

package/dist/commands/join.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `memfork join`
+ *
+ * Onboards a new team member to an existing MemoryTree.
+ *
+ * Prerequisites:
+ *   - The repo has been cloned — .memfork/config.json is already present.
+ *   - The tree owner is reachable to run `memfork grant` after this completes.
+ *
+ * What this does:
+ *   1. Reads treeId from .memfork/config.json
+ *   2. Generates a fresh Sui Ed25519 keypair for this machine
+ *   3. Generates a MemWal delegate key for memory encryption/decryption
+ *   4. Saves both to ~/.memfork/credentials.json (chmod 600)
+ *   5. Prints copy-pasteable commands for the owner to run
+ */
+export declare function cmdJoin(): Promise<void>;

package/dist/commands/join.js

@@ -0,0 +1,125 @@
+/**
+ * `memfork join`
+ *
+ * Onboards a new team member to an existing MemoryTree.
+ *
+ * Prerequisites:
+ *   - The repo has been cloned — .memfork/config.json is already present.
+ *   - The tree owner is reachable to run `memfork grant` after this completes.
+ *
+ * What this does:
+ *   1. Reads treeId from .memfork/config.json
+ *   2. Generates a fresh Sui Ed25519 keypair for this machine
+ *   3. Generates a MemWal delegate key for memory encryption/decryption
+ *   4. Saves both to ~/.memfork/credentials.json (chmod 600)
+ *   5. Prints copy-pasteable commands for the owner to run
+ */
+import chalk from "chalk";
+import { select } from "@inquirer/prompts";
+import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";
+import { decodeSuiPrivateKey } from "@mysten/sui/cryptography";
+import { generateDelegateKey } from "@mysten-incubation/memwal/account";
+import { readProjectConfig, readCredentials, writeCredentials, } from "../config.js";
+function ok(s) { return chalk.green("✓") + " " + s; }
+function tip(s) { return chalk.cyan("→") + " " + chalk.white(s); }
+function dim(s) { return chalk.dim(s); }
+function step(n, total, msg) {
+    process.stdout.write(`  ${dim(`[${n}/${total}]`)} ${msg}…  `);
+}
+function done() { console.log(chalk.green("done")); }
+export async function cmdJoin() {
+    console.log("");
+    console.log(chalk.bold("MemForks join") + "  " + dim("onboard to an existing memory tree"));
+    console.log("");
+    // ── 1. Find tree from project config ────────────────────────────────────────
+    const project = readProjectConfig();
+    if (!project?.treeId) {
+        console.error(chalk.red("  ✗ No .memfork/config.json found in this directory tree.\n") +
+            chalk.dim("    Make sure you've cloned the repo and are running this\n") +
+            chalk.dim("    from inside the project directory.\n"));
+        process.exit(1);
+    }
+    const treeId = project.treeId;
+    const network = project.network ?? "testnet";
+    console.log(dim(`  Found .memfork/config.json`));
+    console.log(dim(`    tree:    ${treeId}`));
+    console.log(dim(`    network: ${network}`));
+    console.log("");
+    // ── 2. Check if credentials already exist for this tree ─────────────────────
+    const existing = readCredentials();
+    if (existing.trees[treeId]) {
+        const address = (() => {
+            try {
+                const kp = existing.trees[treeId].privateKey.startsWith("suiprivkey")
+                    ? Ed25519Keypair.fromSecretKey(decodeSuiPrivateKey(existing.trees[treeId].privateKey).secretKey)
+                    : Ed25519Keypair.fromSecretKey(Uint8Array.from(Buffer.from(existing.trees[treeId].privateKey, "hex")));
+                return kp.toSuiAddress();
+            }
+            catch {
+                return "unknown";
+            }
+        })();
+        console.log(chalk.yellow("  ⚠  Credentials already exist for this tree on this machine."));
+        console.log(dim(`     Sui address: ${address}`));
+        console.log("");
+        const action = await select({
+            message: "What would you like to do?",
+            choices: [
+                { value: "keep", name: "Keep existing credentials  " + dim("(recommended)") },
+                { value: "replace", name: "Generate new credentials    " + dim("(replaces the old ones)") },
+            ],
+        });
+        if (action === "keep") {
+            console.log("");
+            console.log(dim("  No changes made. Run `memfork doctor` to verify your access."));
+            console.log("");
+            return;
+        }
+        console.log("");
+    }
+    // ── 3. Generate Sui keypair ──────────────────────────────────────────────────
+    step(1, 2, "Generating Sui keypair");
+    const keypair = new Ed25519Keypair();
+    const privateKey = keypair.getSecretKey();
+    const address = keypair.toSuiAddress();
+    done();
+    console.log(dim(`       address: ${address}`));
+    // ── 4. Generate MemWal delegate key ─────────────────────────────────────────
+    step(2, 2, "Generating MemWal delegate key");
+    const delegate = await generateDelegateKey();
+    done();
+    console.log(dim(`       pubkey:  ${Buffer.from(delegate.publicKey).toString("hex").slice(0, 32)}…`));
+    // ── 5. Save credentials ──────────────────────────────────────────────────────
+    const creds = readCredentials();
+    creds.trees[treeId] = {
+        privateKey,
+        memwalAccountId: "", // populated after the owner grants access
+        memwalKey: delegate.privateKey,
+    };
+    if (!creds.default)
+        creds.default = treeId;
+    writeCredentials(creds);
+    // ── 6. Instructions for owner ────────────────────────────────────────────────
+    console.log("");
+    console.log(ok("Credentials saved to ~/.memfork/credentials.json"));
+    console.log("");
+    console.log("  " + chalk.bold("Next: share these two commands with the tree owner"));
+    console.log("");
+    console.log("  " + dim("① Grant you on-chain access (lets you branch, propose merges):"));
+    console.log("    " + chalk.cyan(`memfork grant --agent ${address}`));
+    console.log("");
+    console.log("  " + dim("② Register your MemWal key (lets you read/write branch memory):"));
+    console.log("    " + chalk.cyan(`memfork grant-memwal --agent ${address} --pubkey ${Buffer.from(delegate.publicKey).toString("hex")}`));
+    console.log("");
+    console.log("  " + dim("Or send the owner this full block to copy-paste:"));
+    console.log(chalk.dim("  ─────────────────────────────────────────────────────────────"));
+    console.log(`  memfork grant --agent ${address}`);
+    console.log(`  memfork grant-memwal --agent ${address} --pubkey ${Buffer.from(delegate.publicKey).toString("hex")}`);
+    console.log(chalk.dim("  ─────────────────────────────────────────────────────────────"));
+    console.log("");
+    console.log("  " + dim("Once the owner has run both commands, verify your access:"));
+    console.log("    " + tip("memfork doctor"));
+    console.log("");
+    console.log(chalk.dim("  Note: the MemWal account ID will be filled in automatically\n") +
+        chalk.dim("  when you run `memfork doctor` after access is granted.\n"));
+}

package/dist/commands/ops.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Operational commands: status, log, recall, commit, merge, proposals.
+ * All resolve config via the layered config system — no env vars needed.
+ */
+export declare function cmdStatus(): Promise<void>;
+export declare function cmdLog(opts: {
+    branch?: string;
+    limit?: number;
+}): Promise<void>;
+export declare function cmdRecall(query: string, opts: {
+    branch?: string;
+    limit?: number;
+    json?: boolean;
+}): Promise<void>;
+export declare function cmdCommit(opts: {
+    branch?: string;
+    message: string;
+    facts?: string[];
+    fromResponse?: string;
+    autoExtract?: boolean;
+}): Promise<void>;
+export declare function cmdMerge(from: string, into: string, opts: {
+    resolver: string;
+    ttl?: number;
+}): Promise<void>;
+export declare function cmdProposals(): Promise<void>;
+export declare function cmdUi(opts?: {
+    share?: boolean;
+    port?: number;
+}): Promise<void>;
+/**
+ * `memfork show <anchorId>` — show details of an on-chain merge anchor.
+ * For off-chain commit blobs, use `memfork recall` or the UI history view.
+ */
+export declare function cmdShow(anchorId: string): Promise<void>;
+export declare function cmdDiff(fromRef: string, toRef: string): Promise<void>;
+export declare function cmdDelegates(): Promise<void>;
+export declare function cmdGrant(opts: {
+    address: string;
+    permissions?: string;
+    expiry?: number;
+    branches?: string[];
+}): Promise<void>;
+/**
+ * Register a new team member's MemWal delegate key with the tree's MemWal account.
+ * Run by the tree owner after a teammate runs `memfork join`.
+ */
+export declare function cmdGrantMemwal(opts: {
+    agent: string;
+    pubkey: string;
+}): Promise<void>;
+export declare function cmdRevoke(address: string): Promise<void>;
+export declare function cmdBranch(name: string, opts?: {
+    from?: string;
+}): Promise<void>;
+export declare function cmdCheckout(name: string): Promise<void>;