@balacode/mental 0.2.0

package/bin/lib/hooks.mjs

@@ -0,0 +1,144 @@
+/**
+ * Optional session hooks. Default off. Merge Mental's command into user hook
+ * files without deleting other entries. Never enable from `mental install`.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { PKG_ROOT } from "./pkg.mjs";
+
+export const HOOK_MARKER = "mental status --json";
+export const HOOK_SCRIPT = join(PKG_ROOT, "hooks", "session-start.sh");
+
+function readJson(file, fallback) {
+  if (!existsSync(file)) return fallback;
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function writeJson(file, data) {
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`);
+}
+
+function isMentalCommand(cmd) {
+  return (
+    typeof cmd === "string" &&
+    (cmd.includes("mental status") || cmd.includes("session-start.sh"))
+  );
+}
+
+function isMentalEntry(entry) {
+  const cmd = typeof entry === "string" ? entry : entry?.command || entry?.hooks?.[0]?.command;
+  return isMentalCommand(cmd);
+}
+
+/**
+ * @param {string} home
+ */
+export function cursorHooksPath(home) {
+  return join(home, ".cursor", "hooks.json");
+}
+
+/**
+ * @param {string} home
+ */
+export function claudeSettingsPath(home) {
+  return join(home, ".claude", "settings.json");
+}
+
+/**
+ * @param {string} home
+ */
+export function enableHooks(home) {
+  /** @type {string[]} */
+  const written = [];
+
+  const cursorFile = cursorHooksPath(home);
+  const cursor = readJson(cursorFile, { version: 1, hooks: {} });
+  if (!cursor) {
+    return { ok: false, error: { code: "hooks-parse", message: `Could not parse ${cursorFile}` } };
+  }
+  cursor.version = cursor.version || 1;
+  cursor.hooks = cursor.hooks || {};
+  const sessionStart = Array.isArray(cursor.hooks.sessionStart) ? cursor.hooks.sessionStart : [];
+  if (!sessionStart.some(isMentalEntry)) {
+    sessionStart.push({ command: `${HOOK_SCRIPT}` });
+  }
+  cursor.hooks.sessionStart = sessionStart;
+  writeJson(cursorFile, cursor);
+  written.push(cursorFile);
+
+  const claudeFile = claudeSettingsPath(home);
+  const claude = readJson(claudeFile, {});
+  if (!claude) {
+    return { ok: false, error: { code: "hooks-parse", message: `Could not parse ${claudeFile}` } };
+  }
+  claude.hooks = claude.hooks || {};
+  const session = Array.isArray(claude.hooks.SessionStart) ? claude.hooks.SessionStart : [];
+  const hasMental = session.some((block) =>
+    (block.hooks || []).some((h) => isMentalCommand(h.command)),
+  );
+  if (!hasMental) {
+    session.push({
+      matcher: "",
+      hooks: [{ type: "command", command: `${HOOK_SCRIPT}` }],
+    });
+  }
+  claude.hooks.SessionStart = session;
+  const compact = Array.isArray(claude.hooks.PreCompact) ? claude.hooks.PreCompact : [];
+  const hasCompact = compact.some((block) =>
+    (block.hooks || []).some((h) => isMentalCommand(h.command)),
+  );
+  if (!hasCompact) {
+    compact.push({
+      matcher: "",
+      hooks: [{ type: "command", command: `${HOOK_SCRIPT}` }],
+    });
+  }
+  claude.hooks.PreCompact = compact;
+  writeJson(claudeFile, claude);
+  written.push(claudeFile);
+
+  return { ok: true, written, script: HOOK_SCRIPT };
+}
+
+/**
+ * Remove only Mental hook entries. Leave the rest of the files intact.
+ * @param {string} home
+ */
+export function disableHooks(home) {
+  /** @type {string[]} */
+  const written = [];
+
+  const cursorFile = cursorHooksPath(home);
+  const cursor = readJson(cursorFile, null);
+  if (cursor?.hooks?.sessionStart) {
+    cursor.hooks.sessionStart = cursor.hooks.sessionStart.filter((e) => !isMentalEntry(e));
+    writeJson(cursorFile, cursor);
+    written.push(cursorFile);
+  }
+
+  const claudeFile = claudeSettingsPath(home);
+  const claude = readJson(claudeFile, null);
+  if (claude?.hooks) {
+    for (const key of ["SessionStart", "PreCompact"]) {
+      if (!Array.isArray(claude.hooks[key])) continue;
+      claude.hooks[key] = claude.hooks[key]
+        .map((block) => {
+          if (!Array.isArray(block.hooks)) return block;
+          return {
+            ...block,
+            hooks: block.hooks.filter((h) => !isMentalCommand(h.command)),
+          };
+        })
+        .filter((block) => !Array.isArray(block.hooks) || block.hooks.length > 0);
+    }
+    writeJson(claudeFile, claude);
+    written.push(claudeFile);
+  }
+
+  return { ok: true, written };
+}

package/bin/lib/ignore.mjs

@@ -0,0 +1,122 @@
+/**
+ * Private-by-default git ignore for `.mental/` and `.mental-id`.
+ *
+ * v1: user global excludes only, via `mental doctor --fix-ignore`.
+ * Agents must never edit `.gitignore`. Pattern inspired by Balakit's
+ * exclude helpers; comments and product name are Mental's.
+ */
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { spawnSync } from "node:child_process";
+
+export const MENTAL_IGNORE_LINE = ".mental/";
+export const MENTAL_ID_IGNORE_LINE = ".mental-id";
+export const MENTAL_IGNORE_COMMENT =
+  "# mental: private continuity — never commit";
+
+/**
+ * @param {string[]} args
+ * @param {{ env?: NodeJS.ProcessEnv }} [opts]
+ */
+export function runGitGlobal(args, { env = process.env } = {}) {
+  return spawnSync("git", args, { encoding: "utf8", env });
+}
+
+export function gitAvailable({ env = process.env } = {}) {
+  const r = runGitGlobal(["--version"], { env });
+  return !r.error && r.status === 0;
+}
+
+export function expandHome(p, home) {
+  if (p === "~") return home;
+  if (p.startsWith("~/") || p.startsWith("~\\")) return join(home, p.slice(2));
+  return p;
+}
+
+export function defaultExcludesFile(home, env = process.env) {
+  const xdg = env.XDG_CONFIG_HOME;
+  const base = xdg && xdg.trim() ? xdg : join(home, ".config");
+  return join(base, "git", "ignore");
+}
+
+/**
+ * Resolve the active global excludes file.
+ * Honors existing `core.excludesfile` (never overwrites the user's choice).
+ */
+export function resolveGlobalExcludesFile({
+  create = false,
+  home = homedir(),
+  env = process.env,
+} = {}) {
+  if (!gitAvailable({ env })) return null;
+  const configured = (runGitGlobal(["config", "--global", "--get", "core.excludesfile"], { env }).stdout || "").trim();
+  if (configured) return { file: expandHome(configured, home), created: false };
+  if (!create) return { file: defaultExcludesFile(home, env), created: false, unset: true };
+  const file = defaultExcludesFile(home, env);
+  runGitGlobal(["config", "--global", "core.excludesfile", file.split("\\").join("/")], { env });
+  return { file, created: true };
+}
+
+function fileHasLine(cur, line) {
+  return cur.split(/\r?\n/).some((l) => l.trim() === line);
+}
+
+/**
+ * Idempotently append Mental ignore lines to the machine-wide git excludes.
+ */
+export function ensureMentalExcluded({ home = homedir(), env = process.env } = {}) {
+  const resolved = resolveGlobalExcludesFile({ create: true, home, env });
+  if (!resolved) return { ok: false, reason: "git-unavailable" };
+  const { file, created } = resolved;
+  let cur = "";
+  try {
+    cur = readFileSync(file, "utf8");
+  } catch {
+    cur = "";
+  }
+  const needBundle = !fileHasLine(cur, MENTAL_IGNORE_LINE);
+  const needId = !fileHasLine(cur, MENTAL_ID_IGNORE_LINE);
+  if (needBundle || needId) {
+    mkdirSync(dirname(file), { recursive: true });
+    const gap = cur && !cur.endsWith("\n") ? "\n" : "";
+    const bits = [MENTAL_IGNORE_COMMENT];
+    if (needBundle) bits.push(MENTAL_IGNORE_LINE);
+    if (needId) bits.push(MENTAL_ID_IGNORE_LINE);
+    writeFileSync(file, `${cur}${gap}${bits.join("\n")}\n`);
+  }
+  return { ok: true, file, created, appended: needBundle || needId };
+}
+
+/**
+ * Live check: is `.mental/` ignored in this worktree?
+ */
+export function checkMentalIgnored({ cwd, env = process.env } = {}) {
+  if (!gitAvailable({ env })) return { ok: false, liveIgnored: null, reason: "git-unavailable" };
+  const ci = spawnSync("git", ["-C", cwd, "check-ignore", "-q", "--", ".mental/probe"], {
+    encoding: "utf8",
+    env,
+  });
+  if (ci.status === 128) return { ok: false, liveIgnored: null, reason: "not-a-repo" };
+  const liveIgnored = ci.status === 0;
+  return { ok: liveIgnored, liveIgnored };
+}
+
+/**
+ * Refuse to create a project-local `./.mental/` unless git will ignore it.
+ * @param {string} cwd
+ * @param {{ env?: NodeJS.ProcessEnv }} [opts]
+ */
+export function assertLocalIgnorable(cwd, { env = process.env } = {}) {
+  const check = checkMentalIgnored({ cwd, env });
+  if (check.liveIgnored === true) return { ok: true };
+  if (check.reason === "not-a-repo") return { ok: true };
+  return {
+    ok: false,
+    error: {
+      code: "not-ignored",
+      message:
+        "./.mental/ is not gitignored. Run `mental doctor --fix-ignore`, then retry. Mental will not create a project-local bundle that git would track.",
+    },
+  };
+}

package/bin/lib/import-legacy.mjs

@@ -0,0 +1,183 @@
+/**
+ * Ingest leftover Balakit `./.mental` into the home UUID slice.
+ *
+ * Not a raw copy: files are classified onto canonical OKF paths and
+ * frontmatter is normalized (`type`, `title`, `status`, `timestamp`, `tags`).
+ * Source is never deleted. Dest files that already exist are not overwritten.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { parseFrontmatter, slugify, stringifyFrontmatter } from "./okf.mjs";
+
+/** Written by `mental local`. Leftover Balakit bundles do not have this. */
+export const LOCAL_STORE_MARKER = ".mental-local";
+
+const SKIP_NAMES = new Set([LOCAL_STORE_MARKER, ".DS_Store"]);
+const SKIP_DIR_NAMES = new Set(["status"]);
+
+const DEFAULT_STATUS = {
+  Note: "active",
+  Journal: "active",
+  Decision: "decided",
+  Attention: "open",
+  Status: "active",
+};
+
+/**
+ * @param {string} dir absolute path to a `.mental` directory
+ */
+export function isOptedInLocal(dir) {
+  return existsSync(join(dir, LOCAL_STORE_MARKER));
+}
+
+/**
+ * Mark `./.mental` as the explicit project-local store (`mental local`).
+ * @param {string} dir
+ */
+export function markOptedInLocal(dir) {
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, LOCAL_STORE_MARKER), "local\n");
+}
+
+/**
+ * @param {string} rel posix relative path from leftover root
+ * @returns {{ dest: string, type: string } | null}
+ */
+export function classifyLegacyPath(rel) {
+  const posix = rel.split("\\").join("/");
+  const top = posix.split("/")[0];
+  if (SKIP_NAMES.has(top) || SKIP_DIR_NAMES.has(top)) return null;
+  if (!posix.endsWith(".md")) return null;
+  if (posix === "index.md") return { dest: "index.md", type: "Status" };
+  if (posix.startsWith("notes/")) return { dest: posix, type: "Note" };
+  if (posix.startsWith("decisions/")) return { dest: posix, type: "Decision" };
+  if (posix.startsWith("attention/")) return { dest: posix, type: "Attention" };
+  if (posix.startsWith("journal/")) return { dest: posix, type: "Journal" };
+  if (posix === "journal.md") return { dest: "journal/imported-root.md", type: "Journal" };
+  if (!posix.includes("/")) return { dest: `notes/${posix}`, type: "Note" };
+  return { dest: posix, type: "Note" };
+}
+
+function titleFrom(data, body, dest) {
+  if (data.title) return String(data.title);
+  const h = body.match(/^#\s+(.+)$/m);
+  if (h) return h[1].trim();
+  const base = dest.split("/").pop() || dest;
+  return slugify(base.replace(/\.md$/, "")).replace(/-/g, " ");
+}
+
+/**
+ * @param {string} type
+ * @param {Record<string, string | string[]>} data
+ * @param {string} body
+ * @param {string} dest
+ * @param {Date} now
+ */
+export function normalizeLegacyMarkdown(type, data, body, dest, now = new Date()) {
+  const title = titleFrom(data, body, dest);
+  /** @type {Record<string, string | string[] | undefined>} */
+  const next = {
+    type,
+    title,
+    description: data.description ? String(data.description) : title,
+    tags: Array.isArray(data.tags)
+      ? data.tags
+      : data.tags
+        ? [String(data.tags)]
+        : type === "Journal"
+          ? ["journal"]
+          : type === "Status"
+            ? ["index"]
+            : [],
+    timestamp: data.timestamp ? String(data.timestamp) : now.toISOString(),
+    status: String(data.status || DEFAULT_STATUS[type] || "active"),
+  };
+  for (const [k, v] of Object.entries(data)) {
+    if (next[k] == null && v != null) next[k] = v;
+  }
+  return stringifyFrontmatter(next, body);
+}
+
+/**
+ * @param {string} src leftover bundle directory
+ * @param {string} dest `~/.mental/projects/<uuid>`
+ * @param {{ now?: Date }} [opts]
+ * @returns {{ from: string, to: string, copied: string[], skipped: number }}
+ */
+export function importLegacyBundle(src, dest, { now = new Date() } = {}) {
+  const from = resolve(src);
+  const to = resolve(dest);
+  if (from === to) return { from, to, copied: [], skipped: 0 };
+  mkdirSync(to, { recursive: true });
+  const files = listMd(from);
+  files.sort((a, b) => rank(a) - rank(b) || a.localeCompare(b));
+  /** @type {string[]} */
+  const copied = [];
+  let skipped = 0;
+  const claimed = new Set();
+  for (const rel of files) {
+    const classified = classifyLegacyPath(rel);
+    if (!classified) continue;
+    if (claimed.has(classified.dest) || existsSync(join(to, classified.dest))) {
+      skipped += 1;
+      continue;
+    }
+    const text = readFileSync(join(from, rel), "utf8");
+    const { data, body } = parseFrontmatter(text);
+    const type = String(data.type || classified.type);
+    const markdown = normalizeLegacyMarkdown(type, data, body, classified.dest, now);
+    const destFile = join(to, classified.dest);
+    mkdirSync(dirname(destFile), { recursive: true });
+    writeFileSync(destFile, markdown);
+    copied.push(classified.dest);
+    claimed.add(classified.dest);
+  }
+  return { from, to, copied, skipped };
+}
+
+function rank(rel) {
+  const p = rel.split("\\").join("/");
+  if (p.startsWith("notes/")) return 0;
+  if (p.startsWith("decisions/")) return 1;
+  if (p.startsWith("attention/")) return 2;
+  if (p.startsWith("journal/")) return 3;
+  if (p === "index.md") return 4;
+  return 4;
+}
+
+/**
+ * @param {string} dir
+ * @returns {string[]} posix relative paths
+ */
+function listMd(dir) {
+  /** @type {string[]} */
+  const out = [];
+  walk(dir, dir, out);
+  return out;
+}
+
+function walk(base, dir, out) {
+  let names;
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const name of names) {
+    const abs = join(dir, name);
+    const rel = relative(base, abs).split("\\").join("/");
+    const top = rel.split("/")[0];
+    if (SKIP_NAMES.has(name) || SKIP_NAMES.has(top) || SKIP_DIR_NAMES.has(top)) continue;
+    let st;
+    try {
+      st = statSync(abs);
+    } catch {
+      continue;
+    }
+    if (st.isDirectory()) {
+      walk(base, abs, out);
+      continue;
+    }
+    if (name.endsWith(".md")) out.push(rel);
+  }
+}