@balacode/mental 0.2.0

package/bin/lib/bindings.mjs

@@ -0,0 +1,404 @@
+/**
+ * UUID bindings: identity survives path change. Origin is a hint, not the id.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+import { normalizeOrigin } from "./git.mjs";
+
+export const BINDINGS_VERSION = 1;
+
+/**
+ * @param {string} home
+ */
+export function userMentalDir(home) {
+  return join(home, ".mental");
+}
+
+/**
+ * @param {string} home
+ */
+export function bindingsPath(home) {
+  return join(userMentalDir(home), "bindings.json");
+}
+
+/**
+ * @param {string} home
+ * @param {string} id
+ */
+export function projectSliceDir(home, id) {
+  return join(userMentalDir(home), "projects", id);
+}
+
+/**
+ * @param {string} home
+ * @returns {{ version: number, bindings: Array<{
+ *   id: string,
+ *   name: string,
+ *   origins: string[],
+ *   paths: string[],
+ *   updatedAt: string,
+ * }> }}
+ */
+export function loadBindings(home) {
+  const file = bindingsPath(home);
+  if (!existsSync(file)) {
+    return { version: BINDINGS_VERSION, bindings: [] };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    throw new Error(`Corrupt bindings file: ${file}`);
+  }
+  if (!parsed || parsed.version !== BINDINGS_VERSION || !Array.isArray(parsed.bindings)) {
+    throw new Error(`Unsupported bindings.json in ${file}`);
+  }
+  return parsed;
+}
+
+/**
+ * @param {string} home
+ * @param {{ version: number, bindings: object[] }} data
+ */
+export function saveBindings(home, data) {
+  const file = bindingsPath(home);
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`);
+}
+
+/**
+ * Record that leftover `./.mental` was copied into this project's home slice.
+ * @param {string} home
+ * @param {string} id
+ * @param {string} from
+ * @param {{ copied?: string[], now?: string }} [opts]
+ */
+export function recordLegacyImport(home, id, from, { copied = [], now = nowIso() } = {}) {
+  const data = loadBindings(home);
+  const binding = data.bindings.find((b) => b.id === id);
+  if (!binding) return false;
+  const abs = resolve(from);
+  let changed = false;
+  if (binding.legacyImportedFrom !== abs) {
+    binding.legacyImportedFrom = abs;
+    changed = true;
+  }
+  if (copied.length > 0 || !binding.legacyImportedAt) {
+    binding.legacyImportedAt = now;
+    changed = true;
+  }
+  if (changed) {
+    binding.updatedAt = now;
+    saveBindings(home, data);
+  }
+  return changed;
+}
+
+/**
+ * @param {string} home
+ * @param {string} id
+ * @param {"home" | "local"} store
+ */
+export function setBindingStore(home, id, store) {
+  const data = loadBindings(home);
+  const binding = data.bindings.find((b) => b.id === id);
+  if (!binding) return false;
+  if (binding.store === store) return false;
+  binding.store = store;
+  binding.updatedAt = nowIso();
+  saveBindings(home, data);
+  return true;
+}
+
+/**
+ * Read optional `.mental-id` (uuid only) from a directory.
+ * @param {string} dir
+ * @returns {string | null}
+ */
+export function readMentalId(dir) {
+  const file = join(dir, ".mental-id");
+  if (!existsSync(file)) return null;
+  const id = readFileSync(file, "utf8").trim();
+  return id || null;
+}
+
+/**
+ * Write `.mental-id` at git root. Callers must not commit it (doctor ignore).
+ * @param {string} dir
+ * @param {string} id
+ */
+export function writeMentalId(dir, id) {
+  writeFileSync(join(dir, ".mental-id"), `${id}\n`);
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function matchesPath(binding, absPath) {
+  const want = resolve(absPath);
+  return (binding.paths || []).some((p) => resolve(p) === want);
+}
+
+/**
+ * Resolve (and possibly create) a UUID binding for a git worktree.
+ *
+ * @param {{
+ *   gitRoot: string,
+ *   origin?: string | null,
+ *   upstream?: string | null,
+ *   home: string,
+ *   write?: boolean,
+ *   now?: string,
+ *   newId?: () => string,
+ * }} opts
+ * @returns {{
+ *   ok: true,
+ *   id: string,
+ *   created: boolean,
+ *   reason: string,
+ *   binding: object,
+ * } | {
+ *   ok: false,
+ *   code: string,
+ *   message: string,
+ *   fromId?: string,
+ * }}
+ */
+export function resolveOrCreateBinding({
+  gitRoot,
+  origin = null,
+  upstream = null,
+  home,
+  write = true,
+  now = nowIso(),
+  newId = () => randomUUID(),
+}) {
+  const data = loadBindings(home);
+  const bindings = data.bindings;
+  const absRoot = resolve(gitRoot);
+  const originN = normalizeOrigin(origin);
+  const upstreamN = normalizeOrigin(upstream);
+  const mentalId = readMentalId(absRoot);
+
+  const byId = (id) => bindings.find((b) => b.id === id);
+
+  if (mentalId) {
+    const hit = byId(mentalId);
+    if (hit) {
+      const changed = appendHints(hit, { origin: originN, path: absRoot, now });
+      if (write && changed) saveBindings(home, data);
+      return { ok: true, id: hit.id, created: false, reason: "matched .mental-id", binding: hit };
+    }
+    // Stale .mental-id that matches nothing: fall through rather than inventing
+    // a binding for a dead uuid (user can remap). Continue other heuristics.
+  }
+
+  if (originN) {
+    const hits = bindings.filter((b) => (b.origins || []).includes(originN));
+    const here = hits.filter((b) => matchesPath(b, absRoot));
+    if (hits.length > 1 && here.length !== 1) {
+      return {
+        ok: false,
+        code: "ambiguous-origin",
+        message: `Multiple bindings share origin ${originN}. Run mental remap --to <id>.`,
+      };
+    }
+    if (here.length === 1 || hits.length === 1) {
+      const hit = here[0] || hits[0];
+      const changed = appendHints(hit, { origin: originN, path: absRoot, now });
+      const reclaimed = reclaimPath(data, hit.id, absRoot, now);
+      if (write && (changed || reclaimed)) saveBindings(home, data);
+      return {
+        ok: true,
+        id: hit.id,
+        created: false,
+        reason: here.length === 1 ? `matched origin ${originN} at path` : `matched origin ${originN}`,
+        binding: hit,
+      };
+    }
+  }
+
+  const pathHits = bindings.filter((b) => matchesPath(b, absRoot));
+  if (pathHits.length > 1) {
+    return {
+      ok: false,
+      code: "ambiguous-path",
+      message: `Multiple bindings share path ${absRoot}. Run mental remap.`,
+    };
+  }
+  if (pathHits.length === 1) {
+    const hit = pathHits[0];
+    const changed = appendHints(hit, { origin: originN, path: absRoot, now });
+    if (write && changed) saveBindings(home, data);
+    return {
+      ok: true,
+      id: hit.id,
+      created: false,
+      reason: "matched path",
+      binding: hit,
+    };
+  }
+
+  // Fork heuristic: new origin, but upstream matches an existing origin.
+  if (originN && upstreamN && originN !== upstreamN) {
+    const upHits = bindings.filter((b) => (b.origins || []).includes(upstreamN));
+    if (upHits.length === 1) {
+      return {
+        ok: false,
+        code: "fork",
+        message: `Origin ${originN} looks like a fork of ${upHits[0].name} (${upHits[0].id}). Run mental remap --from ${upHits[0].id} or mental split.`,
+        fromId: upHits[0].id,
+      };
+    }
+  }
+
+  if (!write) {
+    return {
+      ok: true,
+      id: null,
+      created: false,
+      reason: "no binding yet (read-only)",
+      binding: null,
+    };
+  }
+
+  const id = newId();
+  const name = absRoot.split(/[/\\]/).filter(Boolean).pop() || id;
+  const binding = {
+    id,
+    name,
+    origins: originN ? [originN] : [],
+    paths: [absRoot],
+    updatedAt: now,
+  };
+  bindings.push(binding);
+  saveBindings(home, data);
+  // Do not write `.mental-id` here: `where` must not drop files into a
+  // worktree that may be public. Identity lives in bindings.json; remap
+  // (phase 5) may write the optional hint after ignore is in place.
+  return {
+    ok: true,
+    id,
+    created: true,
+    reason: originN ? `new binding for ${originN}` : "new binding for path",
+    binding,
+  };
+}
+
+/**
+ * When origin later matches an existing binding, drop this path from other
+ * bindings (git-init-by-path orphan) so identity merges instead of forking.
+ * @returns {boolean} whether anything changed
+ */
+function reclaimPath(data, keepId, absPath, now) {
+  const want = resolve(absPath);
+  let changed = false;
+  data.bindings = data.bindings.filter((b) => {
+    if (b.id === keepId) return true;
+    const before = (b.paths || []).length;
+    b.paths = (b.paths || []).filter((p) => resolve(p) !== want);
+    if (b.paths.length !== before) {
+      b.updatedAt = now;
+      changed = true;
+    }
+    if ((b.paths || []).length === 0 && (b.origins || []).length === 0) {
+      changed = true;
+      return false;
+    }
+    return true;
+  });
+  return changed;
+}
+
+/**
+ * @returns {boolean} whether the binding mutated
+ */
+function appendHints(binding, { origin, path, now }) {
+  let changed = false;
+  if (origin && !(binding.origins || []).includes(origin)) {
+    binding.origins = [...(binding.origins || []), origin];
+    changed = true;
+  }
+  if (path) {
+    const abs = resolve(path);
+    const has = (binding.paths || []).some((p) => resolve(p) === abs);
+    if (!has) {
+      binding.paths = [...(binding.paths || []), abs];
+      changed = true;
+    }
+  }
+  if (changed) binding.updatedAt = now;
+  return changed;
+}
+
+/**
+ * Drop `absPath` from every binding. Used by remap/split.
+ * @returns {boolean}
+ */
+export function detachPath(home, absPath, { now = nowIso() } = {}) {
+  const data = loadBindings(home);
+  const want = resolve(absPath);
+  let changed = false;
+  for (const b of data.bindings) {
+    const before = (b.paths || []).length;
+    b.paths = (b.paths || []).filter((p) => resolve(p) !== want);
+    if (b.paths.length !== before) {
+      b.updatedAt = now;
+      changed = true;
+    }
+  }
+  if (changed) saveBindings(home, data);
+  return changed;
+}
+
+/**
+ * Point this git root at an existing UUID. Writes `.mental-id`.
+ * @param {{ home: string, gitRoot: string, toId: string, origin?: string | null }} opts
+ */
+export function remapToBinding({ home, gitRoot, toId, origin = null, now = nowIso() }) {
+  const data = loadBindings(home);
+  const hit = data.bindings.find((b) => b.id === toId);
+  if (!hit) {
+    return { ok: false, code: "unknown-id", message: `No binding ${toId}. Run mental remap to list.` };
+  }
+  const abs = resolve(gitRoot);
+  detachPath(home, abs, { now });
+  const fresh = loadBindings(home);
+  const binding = fresh.bindings.find((b) => b.id === toId);
+  appendHints(binding, { origin: normalizeOrigin(origin), path: abs, now });
+  saveBindings(home, fresh);
+  writeMentalId(abs, toId);
+  return { ok: true, id: toId, binding };
+}
+
+/**
+ * This clone gets a new UUID. Other clones keep the old one.
+ * @param {{ home: string, gitRoot: string, origin?: string | null, copyRoot?: string | null, newId?: () => string }} opts
+ */
+export function splitBinding({
+  home,
+  gitRoot,
+  origin = null,
+  now = nowIso(),
+  newId = () => randomUUID(),
+}) {
+  const abs = resolve(gitRoot);
+  const id = newId();
+  const originN = normalizeOrigin(origin);
+  detachPath(home, abs, { now });
+  const data = loadBindings(home);
+  const name = abs.split(/[/\\]/).filter(Boolean).pop() || id;
+  const binding = {
+    id,
+    name,
+    origins: originN ? [originN] : [],
+    paths: [abs],
+    updatedAt: now,
+  };
+  data.bindings.push(binding);
+  saveBindings(home, data);
+  writeMentalId(abs, id);
+  return { ok: true, id, binding, dest: projectSliceDir(home, id) };
+}

package/bin/lib/entry.mjs

@@ -0,0 +1,35 @@
+/**
+ * Detect whether this module is the Node process entry point.
+ */
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+function sameResolvedPath(a, b) {
+  let left = a;
+  let right = b;
+  try {
+    left = realpathSync(a);
+  } catch {
+    // argv[1] may be missing on disk in tests; keep the raw path.
+  }
+  try {
+    right = realpathSync(b);
+  } catch {
+    // Keep the raw module path when realpath fails.
+  }
+  if (process.platform === "win32") {
+    return left.toLowerCase() === right.toLowerCase();
+  }
+  return left === right;
+}
+
+/**
+ * True when `argv1` points at the CLI module (direct invoke or npm/npx bin shim).
+ *
+ * @param {string} importMetaUrl
+ * @param {string | undefined} [argv1]
+ */
+export function isCliEntry(importMetaUrl, argv1 = process.argv[1]) {
+  if (!argv1) return false;
+  return sameResolvedPath(argv1, fileURLToPath(importMetaUrl));
+}

package/bin/lib/git.mjs

@@ -0,0 +1,149 @@
+/**
+ * Git helpers: origin identity, worktree root, lightweight snapshots.
+ *
+ * Origin is a *hint* for Mental bindings, never the id. Canonical form is
+ * `host/owner/repo` (no scheme, no `.git`, no userinfo).
+ */
+import { existsSync, statSync } from "node:fs";
+import { dirname, join, parse, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+
+/**
+ * @param {string} cwd
+ * @param {string[]} args
+ * @param {{ env?: NodeJS.ProcessEnv }} [opts]
+ */
+export function runGit(cwd, args, { env = process.env } = {}) {
+  return spawnSync("git", ["-C", cwd, ...args], {
+    encoding: "utf8",
+    env,
+  });
+}
+
+export function gitAvailable() {
+  const r = spawnSync("git", ["--version"], { encoding: "utf8" });
+  return !r.error && r.status === 0;
+}
+
+/**
+ * Strip a trailing `.git` (case-insensitive) and slashes from a path segment.
+ * @param {string} path
+ */
+function stripGitSuffix(path) {
+  return path.replace(/\/+$/, "").replace(/\.git$/i, "").replace(/\/+$/, "");
+}
+
+/**
+ * Normalize a git remote URL to `host/owner/repo` (or `host/path`).
+ * `git@github.com:org/repo.git` ≡ `https://github.com/org/repo`.
+ *
+ * @param {string | null | undefined} input
+ * @returns {string | null}
+ */
+export function normalizeOrigin(input) {
+  if (input == null) return null;
+  let s = String(input).trim();
+  if (!s) return null;
+
+  const hasScheme = /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(s);
+
+  // SCP-like: [user@]host:path  (not a URL, not a Windows drive)
+  if (!hasScheme && !/^[A-Za-z]:[\\/]/.test(s)) {
+    const scp = /^(?:[^@]+@)?([^:]+):(.+)$/;
+    const m = s.match(scp);
+    if (m && m[2] != null && !m[2].startsWith("//")) {
+      const host = m[1].toLowerCase();
+      const path = stripGitSuffix(m[2].replace(/^\/+/, ""));
+      return path ? `${host}/${path}` : host;
+    }
+  }
+
+  let urlStr = s;
+  if (!hasScheme) urlStr = `https://${s}`;
+
+  let u;
+  try {
+    u = new URL(urlStr);
+  } catch {
+    return null;
+  }
+
+  const host = (u.hostname || "").toLowerCase();
+  if (!host) return null;
+  let path = stripGitSuffix((u.pathname || "").replace(/^\/+/, ""));
+  return path ? `${host}/${path}` : host;
+}
+
+/**
+ * Walk from `cwd` to the filesystem root looking for `.git` (dir or file).
+ * Prefer `git rev-parse --show-toplevel` when git works (correct for worktrees).
+ *
+ * @param {string} cwd
+ * @param {{ env?: NodeJS.ProcessEnv }} [opts]
+ * @returns {string | null}
+ */
+export function findGitRoot(cwd, { env = process.env } = {}) {
+  const start = resolve(cwd);
+  if (gitAvailable()) {
+    const r = runGit(start, ["rev-parse", "--show-toplevel"], { env });
+    if (r.status === 0) {
+      const top = (r.stdout || "").trim();
+      if (top) return resolve(top);
+    }
+  }
+  let dir = start;
+  const { root } = parse(dir);
+  while (true) {
+    const gitPath = join(dir, ".git");
+    if (existsSync(gitPath)) {
+      try {
+        const st = statSync(gitPath);
+        if (st.isDirectory() || st.isFile()) return dir;
+      } catch {
+        // ignore
+      }
+    }
+    if (dir === root) return null;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * @param {string} cwd
+ * @param {string} [name]
+ * @param {{ env?: NodeJS.ProcessEnv }} [opts]
+ * @returns {string | null}
+ */
+export function getRemoteUrl(cwd, name = "origin", { env = process.env } = {}) {
+  const r = runGit(cwd, ["remote", "get-url", name], { env });
+  if (r.status !== 0) return null;
+  const url = (r.stdout || "").trim();
+  return url || null;
+}
+
+/**
+ * Lightweight git snapshot for `mental status`. Missing git → null fields.
+ *
+ * @param {string | null} gitRoot
+ * @param {{ env?: NodeJS.ProcessEnv }} [opts]
+ */
+export function gitSnapshot(gitRoot, { env = process.env } = {}) {
+  if (!gitRoot || !gitAvailable()) {
+    return { branch: null, dirty: false, porcelain: "", recent: [] };
+  }
+  const branchR = runGit(gitRoot, ["rev-parse", "--abbrev-ref", "HEAD"], { env });
+  const branch = branchR.status === 0 ? (branchR.stdout || "").trim() || null : null;
+  const st = runGit(gitRoot, ["status", "--porcelain"], { env });
+  const porcelain = st.status === 0 ? st.stdout || "" : "";
+  const log = runGit(gitRoot, ["log", "-5", "--oneline"], { env });
+  const recent =
+    log.status === 0
+      ? (log.stdout || "")
+          .split(/\r?\n/)
+          .map((l) => l.trim())
+          .filter(Boolean)
+      : [];
+  return { branch, dirty: porcelain.trim().length > 0, porcelain, recent };
+}

package/bin/lib/heartbeat.mjs

@@ -0,0 +1,118 @@
+/**
+ * TTY no-args surface: print where you left off, then exit.
+ * Not a standing session. UUID / root / index live on `where` and `doctor`.
+ */
+import { resolveBundle } from "./resolve.mjs";
+import { gitSnapshot } from "./git.mjs";
+import {
+  ATTENTION_HEARTBEAT_CAP,
+  latestJournalHandoff,
+  listOpenAttention,
+  listOpenDecisions,
+  localDate,
+} from "./okf.mjs";
+import { brandMark } from "./output.mjs";
+
+export { ATTENTION_HEARTBEAT_CAP };
+
+/**
+ * Home mode without a UUID is `~/.mental/projects` (parent), not a bundle.
+ * @param {{ id?: string | null, mode?: string }} where
+ */
+export function isBundleRoot(where) {
+  if (where.mode === "env" || where.mode === "local" || where.mode === "personal") return true;
+  return Boolean(where.id);
+}
+
+/**
+ * @param {{ date: string, time?: string | null }} when
+ * @param {Date} [now]
+ */
+export function formatWhen(when, now = new Date()) {
+  if (!when?.date) return null;
+  const today = localDate(now);
+  if (when.date === today) return when.time || "today";
+  const [y, m, d] = when.date.split("-").map(Number);
+  const then = new Date(y, m - 1, d);
+  const start = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+  const days = Math.round((start.getTime() - then.getTime()) / 86400000);
+  if (days === 1) return "yesterday";
+  if (days > 1 && days < 14) return `${days}d ago`;
+  return when.date;
+}
+
+/**
+ * @param {object} args
+ */
+export function collectHeartbeat(args) {
+  const resolved = resolveBundle({
+    cwd: args.cwd ?? process.cwd(),
+    home: args.home ?? process.env.HOME ?? process.env.USERPROFILE ?? null,
+    env: args.env ?? process.env,
+    dir: args.dir ?? null,
+    write: false,
+  });
+  if (!resolved.ok) return { ok: false, error: resolved.error };
+
+  const where = resolved.data;
+  const git = gitSnapshot(where.gitRoot, { env: args.env ?? process.env });
+  const root = isBundleRoot(where) ? where.root : null;
+  const handoff = root
+    ? latestJournalHandoff(root)
+    : { resume: null, outcome: null, file: null, when: null, against: null };
+  const openDecisions = root ? listOpenDecisions(root) : [];
+  const attention = root ? listOpenAttention(root) : [];
+
+  return {
+    ok: true,
+    data: {
+      git,
+      gitRoot: where.gitRoot,
+      handoff,
+      against: handoff.against ?? null,
+      attention,
+      openDecisions,
+    },
+  };
+}
+
+function formatAirItem(a) {
+  const tag = a.status === "later" ? "later" : a.kind || a.status || "open";
+  return `  [${tag}] ${a.title}`;
+}
+
+/**
+ * @param {Extract<ReturnType<typeof collectHeartbeat>, { ok: true }>["data"]} data
+ * @param {Date} [now]
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+export function formatHeartbeat(data, now = new Date(), env = process.env) {
+  const resume =
+    data.handoff.resume ||
+    "No journal yet — start work, then `mental journal` at the task boundary.";
+  const outcome = data.handoff.outcome || "—";
+  const stale = data.handoff.when ? formatWhen(data.handoff.when, now) : null;
+  const nowLine = stale ? `${outcome}  (${stale})` : outcome;
+  const gitLine = data.gitRoot
+    ? `${data.git.branch || "(unknown)"} ${data.git.dirty ? "(dirty)" : "(clean)"}`
+    : "not a git repo";
+  const recent = data.git.recent?.[0] ? `\n        ${data.git.recent[0]}` : "";
+  const against = data.against || data.handoff?.against;
+  const attention = data.attention ?? [];
+  const shown = attention.slice(0, ATTENTION_HEARTBEAT_CAP);
+  const extra =
+    attention.length > ATTENTION_HEARTBEAT_CAP
+      ? `\n  (+${attention.length - ATTENTION_HEARTBEAT_CAP} more)`
+      : "";
+  const air =
+    attention.length === 0 ? "  none" : shown.map(formatAirItem).join("\n") + extra;
+  const open =
+    (data.openDecisions ?? []).length === 0
+      ? "  none"
+      : data.openDecisions.map((d) => `  [${d.status}] ${d.title}`).join("\n");
+
+  const lines = [`${brandMark(env)} ${resume}`];
+  if (against) lines.push(`Against ${against}`);
+  lines.push("", `Now     ${nowLine}`, `Git     ${gitLine}${recent}`, "In the air", air, "Unsettled", open);
+  return lines.join("\n");
+}