@memfork/cli 0.1.0

package/dist/commands/ops.js

@@ -0,0 +1,444 @@
+/**
+ * Operational commands: status, log, recall, commit, merge, proposals.
+ * All resolve config via the layered config system — no env vars needed.
+ */
+import { execSync, exec } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import chalk from "chalk";
+import { resolveConfig, toClientConfig, readProjectConfig, writeProjectConfig, MEMWAL_CONSTANTS, } from "../config.js";
+import { MemForksClient } from "@memfork/core";
+// ─── Shared helpers ───────────────────────────────────────────────────────────
+async function getClient() {
+    const cfg = resolveConfig();
+    const client = await MemForksClient.connect(toClientConfig(cfg));
+    return { client, cfg };
+}
+function currentGitBranch() {
+    try {
+        return execSync("git rev-parse --abbrev-ref HEAD", { encoding: "utf8" }).trim();
+    }
+    catch {
+        return "main";
+    }
+}
+// ─── status ───────────────────────────────────────────────────────────────────
+export async function cmdStatus() {
+    const { client, cfg } = await getClient();
+    const tree = await client.getTree();
+    console.log("");
+    console.log(chalk.bold("MemForks status"));
+    console.log("");
+    console.log(`  Tree      ${chalk.cyan(cfg.treeId)}`);
+    console.log(`  Network   ${cfg.network}`);
+    console.log(`  Branch    ${chalk.green(String(tree["default_branch"] ?? cfg.defaultBranch))}`);
+    console.log(`  Signer    ${client.keypair.toSuiAddress()}`);
+    console.log("");
+}
+// ─── log ──────────────────────────────────────────────────────────────────────
+export async function cmdLog(opts) {
+    const { client, cfg } = await getClient();
+    const branch = opts.branch ?? currentGitBranch();
+    console.log("");
+    console.log(`${chalk.bold("memfork log")} ${chalk.dim("branch:")} ${chalk.green(branch)}`);
+    console.log("");
+    // Model A: commits are off-chain Walrus blobs. Use recall() with empty
+    // query to list the most recent memories as a commit log approximation.
+    try {
+        const results = await client.recall("", { branch, limit: opts.limit ?? 20 });
+        if (results.length === 0) {
+            console.log(chalk.dim(`  No commits yet on branch "${branch}"`));
+        }
+        else {
+            for (const r of results) {
+                const blobShort = r.blobId.slice(0, 10) + "…";
+                let preview = r.text;
+                try {
+                    const p = JSON.parse(r.text);
+                    const delta = p["delta"];
+                    const facts = delta?.["facts"] ?? [];
+                    preview = facts[0] ?? r.text;
+                }
+                catch { /* not JSON */ }
+                console.log(`  ${chalk.yellow(blobShort)}  ` +
+                    chalk.dim(`dist:${r.distance.toFixed(3)}`) + "  " +
+                    chalk.white(preview.slice(0, 80)));
+            }
+        }
+    }
+    catch {
+        console.log(chalk.dim(`  No commits yet on branch "${branch}"`));
+    }
+    console.log("");
+}
+// ─── recall ───────────────────────────────────────────────────────────────────
+export async function cmdRecall(query, opts) {
+    const { client, cfg } = await getClient();
+    const branch = opts.branch ?? currentGitBranch();
+    const results = await client.recall(query, { branch, limit: opts.limit ?? 5 });
+    if (opts.json) {
+        console.log(JSON.stringify(results));
+        return;
+    }
+    console.log("");
+    if (results.length === 0) {
+        console.log(chalk.dim(`  No results for "${query}" on branch ${branch}`));
+    }
+    else {
+        console.log(`${chalk.bold("recall")} ${chalk.dim('"' + query + '"')}  ${chalk.dim("branch:")} ${chalk.green(branch)}`);
+        console.log("");
+        for (const r of results) {
+            const bar = r.distance < 0.2 ? chalk.green("███") :
+                r.distance < 0.35 ? chalk.yellow("██░") : chalk.dim("█░░");
+            console.log(`  ${bar}  ${chalk.dim(r.distance.toFixed(3))}  ${r.text}`);
+        }
+    }
+    console.log("");
+}
+// ─── commit ───────────────────────────────────────────────────────────────────
+export async function cmdCommit(opts) {
+    const { client, cfg } = await getClient();
+    const branch = opts.branch ?? currentGitBranch();
+    let facts = opts.facts ?? [];
+    // --from-response + --auto-extract: stub for LLM extraction
+    // In production this calls the configured LLM to distil durable facts.
+    if (opts.fromResponse && opts.autoExtract) {
+        facts = extractFacts(opts.fromResponse);
+    }
+    else if (opts.fromResponse) {
+        facts = [opts.fromResponse];
+    }
+    if (facts.length === 0) {
+        console.error(chalk.red("No facts to commit. Pass --facts or --from-response."));
+        process.exit(1);
+    }
+    const { blobId } = await client.commit(branch, { facts, message: opts.message });
+    const out = { blobId, branch };
+    if (process.stdout.isTTY) {
+        console.log("");
+        console.log(chalk.green("✓") + " Committed to " + chalk.bold(branch));
+        console.log(chalk.dim(`  blob: ${blobId}`));
+        console.log("");
+    }
+    else {
+        console.log(JSON.stringify(out));
+    }
+}
+// ─── merge ────────────────────────────────────────────────────────────────────
+export async function cmdMerge(from, into, opts) {
+    const { client } = await getClient();
+    process.stdout.write(chalk.dim(`Proposing merge ${chalk.green(from)} → ${chalk.green(into)} …  `));
+    const digest = await client.proposeMerge({
+        fromBranch: from,
+        intoBranch: into,
+        resolverId: opts.resolver,
+        ttlMs: opts.ttl ?? 86_400_000,
+    });
+    console.log(chalk.green("done"));
+    console.log("");
+    console.log(chalk.dim(`  tx: ${digest}`));
+    console.log("");
+    console.log(chalk.dim("The resolver runtime will handle attestation and finalization automatically."));
+    console.log(chalk.dim("Use `memfork proposals` to monitor progress."));
+    console.log("");
+}
+// ─── 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).
+    console.log("");
+    console.log(chalk.bold("Open merge proposals"));
+    console.log(chalk.dim("  (live status in the visualizer: memfork ui)"));
+    console.log("");
+    console.log(chalk.dim("  Tree: " + cfg.treeId));
+    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("");
+    console.log(chalk.cyan("  →") + " Run " + chalk.bold("memfork ui") + " for the full live proposal view.");
+    console.log("");
+}
+// ─── ui ───────────────────────────────────────────────────────────────────────
+export async function cmdUi(opts = {}) {
+    const appDir = findAppDir();
+    if (!appDir) {
+        console.log(chalk.yellow("Could not find the MemForks app directory."));
+        console.log(chalk.dim("Build the app manually: cd app && npm run build"));
+        return;
+    }
+    const distDir = path.join(appDir, "dist");
+    const indexHtml = path.join(distDir, "index.html");
+    // ── Share mode: build → publish to Walrus Site ──────────────────────────
+    if (opts.share) {
+        console.log("");
+        console.log(chalk.bold("memfork ui --share") + chalk.dim("  →  Walrus Site"));
+        console.log("");
+        console.log(chalk.dim("Building app for Walrus Site…"));
+        execSync("npm run build", {
+            cwd: appDir,
+            stdio: "inherit",
+            env: { ...process.env, VITE_WALRUS_MODE: "true" },
+        });
+        console.log("");
+        console.log(chalk.dim("Publishing to Walrus…"));
+        try {
+            execSync(`site-builder deploy --epochs 10 ${distDir}`, { stdio: "inherit" });
+        }
+        catch {
+            console.log("");
+            console.log(chalk.yellow("site-builder not found."));
+            console.log("");
+            console.log("Install it with suiup, then run the deploy manually:");
+            console.log(chalk.dim("  curl -sSfL https://raw.githubusercontent.com/Mystenlabs/suiup/main/install.sh | sh"));
+            console.log(chalk.dim("  suiup install site-builder@mainnet"));
+            console.log(chalk.dim(`  site-builder deploy --epochs 10 ${distDir}`));
+            console.log("");
+            console.log(chalk.dim("The build is ready in: " + distDir));
+        }
+        return;
+    }
+    // ── Local mode: serve pre-built bundle + /api/* routes ──────────────────
+    if (!fs.existsSync(indexHtml)) {
+        console.log(chalk.dim("Building app (first run — takes ~10s)…"));
+        execSync("npm run build", { cwd: appDir, stdio: "inherit" });
+    }
+    const port = opts.port ?? 4242;
+    console.log("");
+    console.log(chalk.bold("MemForks") + chalk.dim("  →  starting local server…"));
+    console.log("");
+    const { startUiServer } = await import("./ui-server.js");
+    const server = startUiServer(distDir, port);
+    // Open browser after a short delay.
+    setTimeout(() => {
+        const url = `http://localhost:${port}`;
+        const cmd = process.platform === "darwin" ? `open ${url}` :
+            process.platform === "win32" ? `start ${url}` :
+                `xdg-open ${url}`;
+        exec(cmd);
+        console.log(chalk.dim("  Press Ctrl+C to stop."));
+        console.log("");
+    }, 400);
+    // Block until the user presses Ctrl+C.
+    await new Promise((resolve) => {
+        process.on("SIGINT", () => {
+            server.close(() => resolve());
+            console.log(chalk.dim("\n  Server stopped."));
+        });
+    });
+}
+// ─── show ─────────────────────────────────────────────────────────────────────
+/**
+ * `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 async function cmdShow(anchorId) {
+    const { client } = await getClient();
+    const anchor = await client.getMergeAnchor(anchorId);
+    const parents = anchor.parents ?? [];
+    console.log("");
+    console.log(chalk.bold("merge anchor ") + chalk.yellow(anchorId));
+    console.log(chalk.dim("tree:           ") + chalk.dim(String(anchor.tree_id ?? "")));
+    if (parents.length > 0) {
+        console.log(chalk.dim("parent blobs:   ") + parents.map((p) => chalk.cyan(p.slice(0, 20) + "…")).join("  "));
+    }
+    console.log(chalk.dim("resolved_blob:  ") + chalk.cyan(String(anchor.memwal_blob_id ?? "")));
+    console.log(chalk.dim("namespace:      ") + chalk.dim(String(anchor.memwal_namespace ?? "")));
+    console.log("");
+}
+// ─── diff ─────────────────────────────────────────────────────────────────────
+export async function cmdDiff(fromRef, toRef) {
+    const { client } = await getClient();
+    console.log("");
+    console.log(chalk.bold("diff") + "  " +
+        chalk.green(fromRef) + chalk.dim("..") + chalk.green(toRef));
+    console.log("");
+    // Model A: diff is based on recalled facts from each branch namespace.
+    const fromBranch = fromRef;
+    const toBranch = toRef;
+    if (fromBranch !== toBranch) {
+        const [fromFacts, toFacts] = await Promise.all([
+            client.recall("", { branch: fromBranch, limit: 50 }),
+            client.recall("", { branch: toBranch, limit: 50 }),
+        ]);
+        const fromKeys = new Set(fromFacts.map((f) => f.text));
+        const toKeys = new Set(toFacts.map((f) => f.text));
+        const added = toFacts.filter((f) => !fromKeys.has(f.text));
+        const removed = fromFacts.filter((f) => !toKeys.has(f.text));
+        if (added.length > 0) {
+            console.log(chalk.green("  + Facts added in " + toBranch + ":"));
+            for (const f of added) {
+                console.log(chalk.green("  + ") + f.text.slice(0, 100));
+            }
+            console.log("");
+        }
+        if (removed.length > 0) {
+            console.log(chalk.red("  - Facts only in " + fromBranch + ":"));
+            for (const f of removed) {
+                console.log(chalk.red("  - ") + f.text.slice(0, 100));
+            }
+            console.log("");
+        }
+        if (added.length === 0 && removed.length === 0) {
+            console.log(chalk.dim("  No fact differences between the two branches."));
+            console.log("");
+        }
+    }
+    else {
+        console.log(chalk.dim("  Same branch — commit-level diff not yet supported."));
+        console.log(chalk.dim("  Use memfork log --branch " + fromBranch + " to see history."));
+        console.log("");
+    }
+}
+// ─── delegates ────────────────────────────────────────────────────────────────
+export async function cmdDelegates() {
+    const { client, cfg } = await getClient();
+    const tree = await client.getTree();
+    const delegates = tree["delegates"] ?? [];
+    console.log("");
+    console.log(chalk.bold("Delegates") + chalk.dim("  tree: " + cfg.treeId.slice(0, 12) + "…"));
+    console.log("");
+    if (delegates.length === 0) {
+        console.log(chalk.dim("  No delegates (only the owner can commit)."));
+    }
+    else {
+        for (const d of delegates) {
+            const addr = String(d["address"] ?? d["sui_address"] ?? "");
+            const perms = String(d["permissions"] ?? "0xFF");
+            const expiry = d["expiry_ms"]
+                ? new Date(Number(d["expiry_ms"])).toISOString().slice(0, 10)
+                : "never";
+            console.log(`  ${chalk.cyan(addr.slice(0, 14) + "…")}` +
+                chalk.dim(`  perms: ${perms}  expiry: ${expiry}`));
+        }
+    }
+    console.log("");
+}
+// ─── grant ────────────────────────────────────────────────────────────────────
+export async function cmdGrant(opts) {
+    const { client } = await getClient();
+    const permissions = opts.permissions ? parseInt(opts.permissions, 16) : 0xFF;
+    const expiryMs = opts.expiry ?? Number.MAX_SAFE_INTEGER;
+    process.stdout.write(chalk.dim(`Granting delegate to ${chalk.cyan(opts.address)} …  `));
+    const digest = await client.grantDelegate(opts.address, {
+        perms: permissions,
+        expiresEpoch: BigInt(expiryMs),
+        branches: opts.branches,
+    });
+    console.log(chalk.green("done"));
+    console.log(chalk.dim(`  tx: ${digest}`));
+    console.log("");
+}
+// ─── grant-memwal ─────────────────────────────────────────────────────────────
+/**
+ * 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 async function cmdGrantMemwal(opts) {
+    const { cfg } = await getClient();
+    const { addDelegateKey } = await import("@mysten-incubation/memwal/account");
+    const { JsonRpcHTTPTransport, SuiJsonRpcClient, getJsonRpcFullnodeUrl } = await import("@mysten/sui/jsonRpc");
+    const network = cfg.network ?? "testnet";
+    const consts = MEMWAL_CONSTANTS[network === "mainnet" ? "mainnet" : "testnet"];
+    const rpcUrl = getJsonRpcFullnodeUrl(network);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const suiClient = new SuiJsonRpcClient({ transport: new JsonRpcHTTPTransport({ url: rpcUrl }), network });
+    const pubkeyBytes = Uint8Array.from(Buffer.from(opts.pubkey, "hex"));
+    process.stdout.write(chalk.dim(`Registering MemWal delegate key for ${chalk.cyan(opts.agent.slice(0, 14) + "…")} …  `));
+    try {
+        await addDelegateKey({
+            packageId: consts.packageId,
+            accountId: cfg.memwalAccountId,
+            publicKey: pubkeyBytes,
+            label: `memfork-join-${opts.agent.slice(0, 8)}`,
+            suiPrivateKey: cfg.privateKey,
+            suiClient,
+        });
+        console.log(chalk.green("done"));
+        console.log("");
+        console.log(chalk.dim(`  The key is now registered on the MemWal account.`));
+        console.log(chalk.dim(`  Tell ${opts.agent.slice(0, 14)}… to run: memfork doctor`));
+        console.log("");
+    }
+    catch (e) {
+        const msg = String(e);
+        if (msg.includes("EDelegateKeyAlreadyExists")) {
+            console.log(chalk.dim("already registered"));
+            console.log("");
+        }
+        else {
+            console.log(chalk.red("failed"));
+            throw new Error(`MemWal key registration failed: ${msg}`);
+        }
+    }
+}
+// ─── revoke ───────────────────────────────────────────────────────────────────
+export async function cmdRevoke(address) {
+    const { client } = await getClient();
+    process.stdout.write(chalk.dim(`Revoking delegate ${chalk.cyan(address)} …  `));
+    const digest = await client.revokeDelegate(address);
+    console.log(chalk.green("done"));
+    console.log(chalk.dim(`  tx: ${digest}`));
+    console.log("");
+}
+// ─── branch ───────────────────────────────────────────────────────────────────
+export async function cmdBranch(name, opts = {}) {
+    const { client, cfg } = await getClient();
+    const from = opts.from ?? cfg.defaultBranch ?? currentGitBranch();
+    process.stdout.write(chalk.dim(`Creating branch ${chalk.green(name)} from ${chalk.green(from)} …  `));
+    const digest = await client.branch(name, { from });
+    console.log(chalk.green("done"));
+    console.log("");
+    console.log(chalk.dim(`  tx: ${digest}`));
+    console.log(chalk.dim(`  Run ${chalk.white("memfork checkout " + name)} to switch to it.`));
+    console.log("");
+}
+// ─── checkout ─────────────────────────────────────────────────────────────────
+export async function cmdCheckout(name) {
+    const { client, cfg } = await getClient();
+    // Verify the branch exists on-chain before switching.
+    // The on-chain branches field is a Move Table — its keys live in dynamic
+    // fields. We use getBranchHead as the existence check (it throws on miss).
+    try {
+        await client.getBranchHead(name);
+    }
+    catch {
+        console.error(chalk.red(`\n  Branch "${name}" not found on tree.`) +
+            chalk.dim("\n  Use `memfork branch " + name + "` to create it first.\n"));
+        process.exit(1);
+    }
+    // Persist the new default branch in the project config.
+    const project = readProjectConfig() ?? {};
+    writeProjectConfig({ ...project, defaultBranch: name });
+    console.log("");
+    console.log(chalk.green("✓") + " Switched to " + chalk.bold(name));
+    console.log(chalk.dim("  (updated .memfork/config.json)"));
+    console.log("");
+}
+// ─── Fact extraction stub ─────────────────────────────────────────────────────
+// Production implementation: calls the configured LLM with a system prompt that
+// extracts durable facts from the turn response. Stub version pulls sentences.
+function extractFacts(response) {
+    return response
+        .split(/[.!?\n]/)
+        .map((s) => s.trim())
+        .filter((s) => s.length > 30 && s.length < 500);
+}
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+function findAppDir() {
+    const candidates = [
+        new URL("../../../app", import.meta.url).pathname,
+        new URL("../../../../app", import.meta.url).pathname,
+    ];
+    for (const c of candidates) {
+        try {
+            if (fs.existsSync(c + "/package.json"))
+                return c;
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}

package/dist/commands/provision.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Auto-provisioning for `memfork init --quick`.
+ *
+ * Goes from zero to a fully configured memory tree in one shot:
+ *
+ *   1. Generate a fresh Ed25519 keypair  (or reuse an existing one)
+ *   2. Fund it from the Sui testnet faucet
+ *   3. Create a MemWal account on-chain  → accountId
+ *   4. Generate a delegate keypair
+ *   5. Register the delegate key with MemWal
+ *   6. Create a MemoryTree                → treeId
+ *
+ * Tested against MemWal SDK:
+ *   createAccount({ packageId, registryId, suiPrivateKey, suiClient })
+ *   generateDelegateKey() → { privateKey: hex, publicKey: Uint8Array, suiAddress }
+ *   addDelegateKey({ packageId, accountId, publicKey, suiAddress, label, suiPrivateKey, suiClient })
+ *
+ * We always pass `suiClient` explicitly because @mysten/sui v2 renames SuiClient
+ * to SuiJsonRpcClient, and the MemWal SDK's internal auto-init would fail on v2.
+ */
+export interface ProvisionResult {
+    treeId: string;
+    privateKey: string;
+    memwalAccountId: string;
+    memwalKey: string;
+    network: "testnet" | "mainnet";
+}
+export declare function autoProvision(opts: {
+    network: "testnet" | "mainnet";
+    existingKey?: string;
+    defaultBranch?: string;
+}): Promise<ProvisionResult>;

package/dist/commands/provision.js

@@ -0,0 +1,173 @@
+/**
+ * Auto-provisioning for `memfork init --quick`.
+ *
+ * Goes from zero to a fully configured memory tree in one shot:
+ *
+ *   1. Generate a fresh Ed25519 keypair  (or reuse an existing one)
+ *   2. Fund it from the Sui testnet faucet
+ *   3. Create a MemWal account on-chain  → accountId
+ *   4. Generate a delegate keypair
+ *   5. Register the delegate key with MemWal
+ *   6. Create a MemoryTree                → treeId
+ *
+ * Tested against MemWal SDK:
+ *   createAccount({ packageId, registryId, suiPrivateKey, suiClient })
+ *   generateDelegateKey() → { privateKey: hex, publicKey: Uint8Array, suiAddress }
+ *   addDelegateKey({ packageId, accountId, publicKey, suiAddress, label, suiPrivateKey, suiClient })
+ *
+ * We always pass `suiClient` explicitly because @mysten/sui v2 renames SuiClient
+ * to SuiJsonRpcClient, and the MemWal SDK's internal auto-init would fail on v2.
+ */
+import chalk from "chalk";
+import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";
+import { decodeSuiPrivateKey } from "@mysten/sui/cryptography";
+import { JsonRpcHTTPTransport, SuiJsonRpcClient, getJsonRpcFullnodeUrl } from "@mysten/sui/jsonRpc";
+import { createAccount, addDelegateKey, generateDelegateKey, } from "@mysten-incubation/memwal/account";
+import { MemForksClient } from "@memfork/core";
+import { MEMWAL_CONSTANTS, } from "../config.js";
+function step(n, msg) {
+    process.stdout.write(`  ${chalk.dim(`[${n}/6]`)} ${msg}…  `);
+}
+function done() { console.log(chalk.green("done")); }
+function skip(reason) { console.log(chalk.dim("skip  " + reason)); }
+export async function autoProvision(opts) {
+    const network = opts.network;
+    const consts = MEMWAL_CONSTANTS[network];
+    const rpcUrl = getJsonRpcFullnodeUrl(network);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const suiClient = new SuiJsonRpcClient({ transport: new JsonRpcHTTPTransport({ url: rpcUrl }), network });
+    // ── 1. Keypair ──────────────────────────────────────────────────────────────
+    step(1, "Generating Sui keypair");
+    let keypair;
+    if (opts.existingKey) {
+        keypair = opts.existingKey.startsWith("suiprivkey")
+            ? Ed25519Keypair.fromSecretKey(decodeSuiPrivateKey(opts.existingKey).secretKey)
+            : Ed25519Keypair.fromSecretKey(Uint8Array.from(Buffer.from(opts.existingKey, "hex")));
+        skip("reusing existing key");
+    }
+    else {
+        keypair = new Ed25519Keypair();
+        done();
+    }
+    const address = keypair.toSuiAddress();
+    const privateKey = keypair.getSecretKey(); // bech32 suiprivkey1…
+    console.log(chalk.dim(`      address: ${address}`));
+    // ── 2. Faucet (testnet only) ─────────────────────────────────────────────────
+    if (network === "testnet") {
+        step(2, "Requesting SUI from testnet faucet");
+        try {
+            const res = await fetch("https://faucet.testnet.sui.io/v1/gas", {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ FixedAmountRequest: { recipient: address } }),
+                signal: AbortSignal.timeout(20_000),
+            });
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status}`);
+            done();
+            // Wait for faucet tx to land before we submit our transactions.
+            await new Promise(r => setTimeout(r, 4_000));
+        }
+        catch (e) {
+            console.log(chalk.yellow("failed"));
+            console.log(chalk.yellow(`      ⚠ Faucet error: ${String(e)}`));
+            console.log(chalk.yellow(`      Fund manually → https://faucet.testnet.sui.io`));
+            console.log(chalk.yellow(`      Address: ${address}`));
+            console.log(chalk.yellow(`      Then re-run: memfork init --quick`));
+            throw new Error("Faucet unavailable — fund the address above and retry.");
+        }
+    }
+    else {
+        step(2, "Mainnet — faucet not available");
+        skip("fund your wallet before re-running");
+    }
+    // ── 3. MemWal account ────────────────────────────────────────────────────────
+    step(3, "Creating MemWal account on-chain");
+    let accountId;
+    try {
+        const result = await createAccount({
+            packageId: consts.packageId,
+            registryId: consts.registryId,
+            suiPrivateKey: privateKey,
+            suiClient,
+        });
+        accountId = result.accountId;
+        done();
+        console.log(chalk.dim(`      accountId: ${accountId}`));
+    }
+    catch (e) {
+        const msg = String(e);
+        if (msg.includes("EAccountAlreadyExists") || msg.includes("MoveAbort") && msg.includes(", 3)")) {
+            // Error code 3 = EAccountAlreadyExists — fine, just fetch the existing one.
+            console.log(chalk.dim("already exists"));
+            accountId = await resolveExistingMemwalAccount(suiClient, consts.packageId, address);
+            console.log(chalk.dim(`      accountId: ${accountId}`));
+        }
+        else {
+            console.log(chalk.red("failed"));
+            throw new Error(`MemWal account creation failed: ${msg}`);
+        }
+    }
+    // ── 4 + 5. Delegate key ───────────────────────────────────────────────────────
+    step(4, "Generating MemWal delegate key");
+    const delegate = await generateDelegateKey();
+    done();
+    step(5, "Registering delegate key with MemWal");
+    try {
+        await addDelegateKey({
+            packageId: consts.packageId,
+            accountId,
+            publicKey: delegate.publicKey,
+            label: `memfork-cli-${new Date().toISOString().slice(0, 10)}`,
+            suiPrivateKey: privateKey,
+            suiClient,
+        });
+        done();
+    }
+    catch (e) {
+        const msg = String(e);
+        if (msg.includes("EDelegateKeyAlreadyExists") || msg.includes("MoveAbort") && msg.includes(", 0)")) {
+            skip("key already registered");
+        }
+        else {
+            console.log(chalk.red("failed"));
+            throw new Error(`Failed to register delegate key: ${msg}`);
+        }
+    }
+    // ── 6. MemoryTree ────────────────────────────────────────────────────────────
+    step(6, "Creating MemoryTree on Sui");
+    const memClient = await MemForksClient.connect({
+        treeId: "0x" + "0".repeat(64), // placeholder — initTree creates the object
+        signer: privateKey,
+        network,
+        memwal: {
+            accountId,
+            delegateKey: delegate.privateKey,
+            serverUrl: consts.relayer,
+        },
+    });
+    const { treeId, digest } = await memClient.initTree(accountId, opts.defaultBranch ?? "main");
+    done();
+    console.log(chalk.dim(`      treeId: ${treeId}`));
+    console.log(chalk.dim(`      tx:     ${digest}`));
+    return {
+        treeId,
+        privateKey,
+        memwalAccountId: accountId,
+        memwalKey: delegate.privateKey,
+        network,
+    };
+}
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+async function resolveExistingMemwalAccount(suiClient, packageId, owner) {
+    const objs = await suiClient.getOwnedObjects({
+        owner,
+        filter: { StructType: `${packageId}::account::MemWalAccount` },
+        options: { showContent: false },
+    });
+    const first = objs.data?.[0];
+    if (!first?.data?.objectId) {
+        throw new Error("Could not find existing MemWal account for this address.");
+    }
+    return first.data.objectId;
+}

package/dist/commands/ui-server.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `memfork ui` — local HTTP server.
+ *
+ * Serves the pre-built React app from app/dist/ as static files and
+ * exposes two API routes so the React app can discover the current tree
+ * config and recall MemWal facts without exposing credentials in the
+ * browser bundle.
+ *
+ *   GET /api/config   → { treeId, packageId, network, rpcUrl, hasMemwal }
+ *   GET /api/facts    → { facts: MemWal results[] }  (proxied server-side)
+ *   GET /*            → index.html (SPA fallback)
+ *   GET /assets/*     → static file
+ */
+import http from "node:http";
+export declare function startUiServer(distDir: string, port?: number): http.Server;