@memfork/cli 0.1.25 → 0.1.27

package/dist/branch.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Branch resolution for CLI commands.
+ *
+ * Memory in MemForks is namespaced per branch. Every CLI command needs to
+ * answer the same question — "which branch am I operating on?" — and they must
+ * all answer it the same way. This module is the single source of that answer.
+ *
+ * Precedence (highest wins):
+ *   1. explicit  — the `--branch` / `--from` flag passed on the command line
+ *   2. env       — MEMFORK_BRANCH (CI / headless override)
+ *   3. git       — the current git branch (the dynamic default for humans)
+ *   4. config    — `defaultBranch` from .memfork/config.json (non-git fallback)
+ *   5. "main"    — last resort
+ *
+ * IMPORTANT: this lives in the CLI layer ONLY. The core MemForksClient and the
+ * framework adapters (@memfork/langgraph, @memfork/vercel-ai) take an explicit
+ * `branch` argument and have no git awareness. Keeping git resolution out of
+ * the core guarantees those integrations are unaffected by this logic.
+ */
+/**
+ * Read the current git branch, or undefined when there is no usable answer.
+ *
+ * Returns undefined when:
+ *   - not inside a git repo (command fails)
+ *   - detached HEAD / mid-rebase / mid-bisect (returns the literal "HEAD")
+ *
+ * In those cases the caller falls through to the next precedence source rather
+ * than writing memory into a bogus namespace literally named "HEAD".
+ */
+export declare function gitBranch(cwd?: string): string | undefined;
+export interface BranchSources {
+    /** --branch / --from flag (highest priority). */
+    explicit?: string;
+    /** MEMFORK_BRANCH env var. */
+    env?: string;
+    /** Current git branch (already guarded against detached HEAD). */
+    git?: string;
+    /** defaultBranch from project config (non-git fallback). */
+    configDefault?: string;
+}
+/**
+ * Pure precedence resolver — no I/O. Exposed separately so the precedence
+ * rules can be unit-tested exhaustively without a git repo or env mutation.
+ *
+ * A whitespace-only source is treated as absent.
+ */
+export declare function pickBranch(sources: BranchSources): string;
+/**
+ * Resolve the branch a command should operate on, applying the full
+ * precedence chain (reads MEMFORK_BRANCH and the current git branch).
+ */
+export declare function resolveBranch(opts?: {
+    explicit?: string;
+    configDefault?: string;
+    cwd?: string;
+}): string;

package/dist/branch.js

@@ -0,0 +1,74 @@
+/**
+ * Branch resolution for CLI commands.
+ *
+ * Memory in MemForks is namespaced per branch. Every CLI command needs to
+ * answer the same question — "which branch am I operating on?" — and they must
+ * all answer it the same way. This module is the single source of that answer.
+ *
+ * Precedence (highest wins):
+ *   1. explicit  — the `--branch` / `--from` flag passed on the command line
+ *   2. env       — MEMFORK_BRANCH (CI / headless override)
+ *   3. git       — the current git branch (the dynamic default for humans)
+ *   4. config    — `defaultBranch` from .memfork/config.json (non-git fallback)
+ *   5. "main"    — last resort
+ *
+ * IMPORTANT: this lives in the CLI layer ONLY. The core MemForksClient and the
+ * framework adapters (@memfork/langgraph, @memfork/vercel-ai) take an explicit
+ * `branch` argument and have no git awareness. Keeping git resolution out of
+ * the core guarantees those integrations are unaffected by this logic.
+ */
+import { execSync } from "node:child_process";
+/**
+ * Read the current git branch, or undefined when there is no usable answer.
+ *
+ * Returns undefined when:
+ *   - not inside a git repo (command fails)
+ *   - detached HEAD / mid-rebase / mid-bisect (returns the literal "HEAD")
+ *
+ * In those cases the caller falls through to the next precedence source rather
+ * than writing memory into a bogus namespace literally named "HEAD".
+ */
+export function gitBranch(cwd = process.cwd()) {
+    try {
+        const out = execSync("git rev-parse --abbrev-ref HEAD", {
+            encoding: "utf8",
+            cwd,
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        if (!out || out === "HEAD")
+            return undefined;
+        return out;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Pure precedence resolver — no I/O. Exposed separately so the precedence
+ * rules can be unit-tested exhaustively without a git repo or env mutation.
+ *
+ * A whitespace-only source is treated as absent.
+ */
+export function pickBranch(sources) {
+    const clean = (s) => {
+        const t = s?.trim();
+        return t ? t : undefined;
+    };
+    return (clean(sources.explicit) ??
+        clean(sources.env) ??
+        clean(sources.git) ??
+        clean(sources.configDefault) ??
+        "main");
+}
+/**
+ * Resolve the branch a command should operate on, applying the full
+ * precedence chain (reads MEMFORK_BRANCH and the current git branch).
+ */
+export function resolveBranch(opts = {}) {
+    return pickBranch({
+        explicit: opts.explicit,
+        env: process.env["MEMFORK_BRANCH"],
+        git: gitBranch(opts.cwd),
+        configDefault: opts.configDefault,
+    });
+}

package/dist/commands/ops.js

@@ -7,6 +7,7 @@ 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 { resolveBranch } from "../branch.js";
 import { MemForksClient } from "@memfork/core";
 // ─── Shared helpers ───────────────────────────────────────────────────────────
 async function getClient() {
@@ -14,34 +15,6 @@ async function getClient() {
     const client = await MemForksClient.connect(toClientConfig(cfg));
     return { client, cfg };
 }
-function isTransientSuiError(e) {
-    const msg = String(e);
-    return (msg.includes("needs to be rebuilt") ||
-        msg.includes("unavailable for consumption") ||
-        msg.includes("object version"));
-}
-async function withRetry(fn, retries = 2, delayMs = 1500) {
-    for (let attempt = 1;; attempt++) {
-        try {
-            return await fn();
-        }
-        catch (e) {
-            if (isTransientSuiError(e) && attempt < retries) {
-                await new Promise((r) => setTimeout(r, delayMs));
-                continue;
-            }
-            throw e;
-        }
-    }
-}
-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();
@@ -49,16 +22,18 @@ export async function cmdStatus() {
     console.log("");
     console.log(chalk.bold("MemForks status"));
     console.log("");
+    const currentBranch = resolveBranch({ configDefault: cfg.defaultBranch });
     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(`  Branch    ${chalk.green(currentBranch)}`);
+    console.log(`  Tree dflt ${chalk.dim(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();
+    const branch = resolveBranch({ explicit: opts.branch, configDefault: cfg.defaultBranch });
     console.log("");
     console.log(`${chalk.bold("memfork log")} ${chalk.dim("branch:")} ${chalk.green(branch)}`);
     console.log("");
@@ -94,7 +69,7 @@ export async function cmdLog(opts) {
 // ─── recall ───────────────────────────────────────────────────────────────────
 export async function cmdRecall(query, opts) {
     const { client, cfg } = await getClient();
-    const branch = opts.branch ?? currentGitBranch();
+    const branch = resolveBranch({ explicit: opts.branch, configDefault: cfg.defaultBranch });
     const results = await client.recall(query, { branch, limit: opts.limit ?? 5 });
     if (opts.json) {
         console.log(JSON.stringify(results));
@@ -118,7 +93,7 @@ export async function cmdRecall(query, opts) {
 // ─── commit ───────────────────────────────────────────────────────────────────
 export async function cmdCommit(opts) {
     const { client, cfg } = await getClient();
-    const branch = opts.branch ?? currentGitBranch();
+    const branch = resolveBranch({ explicit: opts.branch, configDefault: cfg.defaultBranch });
     let facts = opts.facts ?? [];
     // --from-response + --auto-extract: stub for LLM extraction
     // In production this calls the configured LLM to distil durable facts.
@@ -132,7 +107,7 @@ export async function cmdCommit(opts) {
         console.error(chalk.red("No facts to commit. Pass --facts or --from-response."));
         process.exit(1);
     }
-    const { blobId } = await withRetry(() => client.commit(branch, { facts, message: opts.message }));
+    const { blobId } = await client.commit(branch, { facts, message: opts.message });
     const out = { blobId, branch };
     if (process.stdout.isTTY) {
         console.log("");
@@ -158,7 +133,7 @@ export async function cmdMerge(from, into, opts) {
     process.stdout.write(chalk.dim(`Merging ${chalk.green(from)} → ${chalk.green(into)}`) +
         chalk.dim(governed ? "  (governed — awaiting resolver…)" : "  (LWW — self-finalizing…)") +
         "  ");
-    const { digest, mergedCount, blobId, proposalId } = await withRetry(() => client.merge(from, into));
+    const { digest, mergedCount, blobId, proposalId } = await client.merge(from, into);
     console.log(chalk.green("done"));
     console.log("");
     console.log(chalk.dim(`  facts merged: ${mergedCount}`));
@@ -308,7 +283,12 @@ export async function cmdPrComment(opts) {
     }
     catch { /* non-critical */ }
     // Get the decided fact from the into_branch via recall.
-    const targetBranch = opts.branch ?? intoBranch ?? currentGitBranch();
+    // The proposal's into_branch is the most specific target, so it is treated
+    // as an explicit selection (ranking above the current git branch).
+    const targetBranch = resolveBranch({
+        explicit: opts.branch ?? intoBranch,
+        configDefault: cfg.defaultBranch,
+    });
     let decision = `Use ${fromBranch || "winning branch"} approach.`;
     try {
         const results = await client.recall("decided", { branch: targetBranch, limit: 1 });
@@ -375,7 +355,12 @@ export async function cmdUi(opts = {}) {
         console.log(chalk.dim("Build the app manually: cd apps/visualizer && npm run build"));
         return;
     }
-    const distDir = path.join(appDir, "dist");
+    // Two layouts: the published bundle (packages/cli/ui/) holds index.html +
+    // assets/ directly, while the monorepo source (apps/visualizer/) builds into
+    // a dist/ subdir. Detect which one we resolved to.
+    const distDir = fs.existsSync(path.join(appDir, "index.html"))
+        ? appDir
+        : path.join(appDir, "dist");
     const indexHtml = path.join(distDir, "index.html");
     // ── Share mode: build → publish to Walrus Site ──────────────────────────
     if (opts.share) {
@@ -592,9 +577,9 @@ export async function cmdRevoke(address) {
 // ─── branch ───────────────────────────────────────────────────────────────────
 export async function cmdBranch(name, opts = {}) {
     const { client, cfg } = await getClient();
-    const from = opts.from ?? cfg.defaultBranch ?? currentGitBranch();
+    const from = resolveBranch({ explicit: opts.from, configDefault: cfg.defaultBranch });
     process.stdout.write(chalk.dim(`Creating branch ${chalk.green(name)} from ${chalk.green(from)} …  `));
-    const digest = await withRetry(() => client.branch(name, { from }));
+    const digest = await client.branch(name, { from });
     console.log(chalk.green("done"));
     console.log("");
     console.log(chalk.dim(`  tx: ${digest}`));

package/dist/index.d.ts

@@ -7,3 +7,5 @@
  * The CLI binary entry point is src/cli.ts → dist/cli.js
  */
 export { resolveConfig, toClientConfig, readProjectConfig, writeProjectConfig, readCredentials, writeCredentials, upsertCredential, setDefaultTree, projectConfigPath, credentialsPath, ConfigError, } from "./config.js";
+export { resolveBranch, pickBranch, gitBranch } from "./branch.js";
+export type { BranchSources } from "./branch.js";

package/dist/index.js

@@ -7,3 +7,4 @@
  * The CLI binary entry point is src/cli.ts → dist/cli.js
  */
 export { resolveConfig, toClientConfig, readProjectConfig, writeProjectConfig, readCredentials, writeCredentials, upsertCredential, setDefaultTree, projectConfigPath, credentialsPath, ConfigError, } from "./config.js";
+export { resolveBranch, pickBranch, gitBranch } from "./branch.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memfork/cli",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "description": "MemForks CLI — init, commit, recall, merge, install plugins",
   "repository": {
     "type": "git",
@@ -35,7 +35,7 @@
   ],
   "dependencies": {
     "@inquirer/prompts": "^8.5.2",
-    "@memfork/core": "^0.1.10",
+    "@memfork/core": "^0.1.11",
     "chalk": "^5.6.2",
     "commander": "^15.0.0"
   },

package/plugins/codex/skills/memforks-status/SKILL.md

@@ -27,11 +27,12 @@ Use this after significant architectural decisions — not for routine facts.
 
 ```bash
 memfork commit \
-  --branch $(git rev-parse --abbrev-ref HEAD) \
   --message "decided: <one-line summary>" \
   --facts "<fact 1>" "<fact 2>"
 ```
 
+The CLI auto-detects the current Git branch; pass `--branch <name>` only to target a different one.
+
 ## Merge branches
 
 When two branches need to reconcile their memory:

package/plugins/cursor/rules/memforks.mdc

@@ -54,11 +54,13 @@ a non-trivial problem, also anchor it on-chain for immutable versioning:
 
 ```bash
 memfork commit \
-  --branch $(git rev-parse --abbrev-ref HEAD) \
   --message "decided: <one-line summary>" \
   --facts "<fact 1>" "<fact 2>"
 ```
 
+The CLI auto-detects the current Git branch, so you do not pass `--branch`
+unless you want to target a different branch.
+
 This creates a cryptographically verifiable commit on Sui — not just a blob.
 Use it for decisions that matter for audit trail, not routine facts.
 
@@ -66,9 +68,10 @@ Use it for decisions that matter for audit trail, not routine facts.
 
 ## Branch awareness
 
-- Memory is scoped to the current Git branch via the `namespace` parameter
-- When the user switches branches, recall from the new branch namespace
-- Use `memfork status` to see the on-chain tree state and open merge proposals
+- The `memfork` CLI auto-detects the current Git branch; pass `--branch` only to override it.
+- The `memwal_*` MCP tools have no Git context, so pass `namespace="branch/<current-branch>"` explicitly.
+- When the user switches branches, recall from the new branch namespace.
+- Use `memfork status` to see the current branch, on-chain tree state, and open merge proposals.
 
 ---
 
@@ -81,10 +84,12 @@ 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)
+memfork branch dev/<hypothesis-a>
+memfork branch dev/<hypothesis-b>
 ```
 
+Both fork from the current Git branch by default; add `--from <branch>` to fork from another.
+
 Use short kebab-case names (`dev/redis-first`, `dev/bcrypt-cost`).
 
 **Step 2 — investigate each path and commit evidence:**