@balacode/mental 0.2.0

package/bin/lib/output.mjs

@@ -0,0 +1,112 @@
+/**
+ * Stable agent JSON envelope + human printers.
+ * Emoji is TTY-only. `--json` never includes a brand mark.
+ */
+
+/**
+ * `MENTAL_ASCII=1` for consoles that cannot render emoji (legacy cmd.exe).
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+export function useAsciiBrand(env = process.env) {
+  const v = env.MENTAL_ASCII;
+  return v === "1" || v === "true" || v === "yes";
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+export function brandMark(env = process.env) {
+  return useAsciiBrand(env) ? "[mental]" : "🧠";
+}
+
+const KIND_EMOJI = {
+  journal: "📓",
+  attention: "🚦",
+  decision: "🎯",
+  note: "📝",
+  read: "🔍",
+};
+
+const KIND_ASCII = {
+  journal: "[journal]",
+  attention: "[attention]",
+  decision: "[decision]",
+  note: "[note]",
+  read: "[read]",
+};
+
+/**
+ * Type mark for TTY writes/reads. `--json` must not call this.
+ * @param {"journal" | "attention" | "decision" | "note" | "read"} kind
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+export function kindMark(kind, env = process.env) {
+  if (useAsciiBrand(env)) return KIND_ASCII[kind] || "[mental]";
+  return KIND_EMOJI[kind] || brandMark(env);
+}
+
+/**
+ * @param {"journal" | "attention" | "decision" | "note" | "read"} kind
+ * @param {string} text
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+export function kindLine(kind, text, env = process.env) {
+  return `${kindMark(kind, env)} ${text}`;
+}
+
+/**
+ * Prefix a TTY success line with the Mental mark.
+ * @param {string} text
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+export function brandLine(text, env = process.env) {
+  return `${brandMark(env)} ${text}`;
+}
+
+/**
+ * @param {boolean} ok
+ * @param {object} [data]
+ * @param {{ code: string, message: string }} [error]
+ */
+export function envelope(ok, data, error) {
+  return ok ? { ok: true, data } : { ok: false, error };
+}
+
+/**
+ * @param {NodeJS.WritableStream} out
+ * @param {boolean} json
+ * @param {boolean} ok
+ * @param {object} [data]
+ * @param {{ code: string, message: string }} [error]
+ * @param {(data: object) => string} [format]
+ */
+export function printResult(out, json, ok, data, error, format) {
+  if (json) {
+    out.write(`${JSON.stringify(envelope(ok, data, error))}\n`);
+    return;
+  }
+  if (!ok) {
+    out.write(`${error?.message || "error"}\n`);
+    return;
+  }
+  out.write(`${format ? format(data) : JSON.stringify(data, null, 2)}\n`);
+}
+
+/** @param {import('./resolve.mjs').WhereData} data */
+export function formatWhere(data) {
+  const id = data.id ?? "—";
+  const lines = [
+    `root:    ${data.root}`,
+    `id:      ${id}`,
+    `mode:    ${data.mode}`,
+    `reason:  ${data.reason}`,
+    `gitRoot: ${data.gitRoot ?? "—"}`,
+  ];
+  if (data.imported?.copied?.length) {
+    lines.push(`imported: ${data.imported.copied.length} file(s) from ${data.imported.from}`);
+  }
+  if (data.indexed?.ok) {
+    lines.push(`index:    ${data.indexed.concepts} concept(s) → ${data.indexed.path}`);
+  }
+  return lines.join("\n");
+}

package/bin/lib/pkg.mjs

@@ -0,0 +1,22 @@
+/**
+ * Package identity shared across the CLI.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+/** Absolute path to the package root (parent of `bin/`). */
+export const PKG_ROOT = fileURLToPath(new URL("../..", import.meta.url));
+
+const pkg = JSON.parse(readFileSync(join(PKG_ROOT, "package.json"), "utf8"));
+
+export const NAME = pkg.name;
+export const CMD = Object.keys(pkg.bin ?? {})[0] ?? "mental";
+export const VERSION = pkg.version;
+
+export const SKILLS_DIR = join(PKG_ROOT, "skills");
+export const RULES_DIR = join(PKG_ROOT, "rules");
+
+/** Managed-block markers for user AGENTS.md / CLAUDE.md. */
+export const BEGIN = `<!-- BEGIN ${CMD} (managed — edits inside are overwritten on reinstall) -->`;
+export const END = `<!-- END ${CMD} -->`;

package/bin/lib/resolve.mjs

@@ -0,0 +1,302 @@
+/**
+ * Deterministic active-bundle resolution. Exclusive nearest-wins — no overlay.
+ *
+ * Order: --dir / MENTAL_DIR → opted-in ./.mental/ (`mental local`) → git binding
+ * → personal ~/.mental.
+ *
+ * Leftover Balakit `./.mental` (no `.mental-local` marker) is imported into
+ * `~/.mental/projects/<uuid>/` on write resolve. Source is never deleted.
+ */
+import { statSync } from "node:fs";
+import { dirname, join, parse, resolve } from "node:path";
+import { findGitRoot, getRemoteUrl } from "./git.mjs";
+import {
+  projectSliceDir,
+  recordLegacyImport,
+  resolveOrCreateBinding,
+  userMentalDir,
+} from "./bindings.mjs";
+import { importLegacyBundle, isOptedInLocal } from "./import-legacy.mjs";
+import { reindexBundle } from "./index.mjs";
+
+/**
+ * @typedef {'env' | 'local' | 'home' | 'personal'} ResolveMode
+ *
+ * @typedef {{
+ *   from: string,
+ *   to: string,
+ *   copied: string[],
+ *   skipped: number,
+ *   error?: string,
+ * }} ImportResult
+ *
+ * @typedef {{
+ *   root: string,
+ *   id: string | null,
+ *   mode: ResolveMode,
+ *   reason: string,
+ *   gitRoot: string | null,
+ *   imported?: ImportResult | null,
+ *   indexed?: { ok: boolean, path: string | null, concepts: number, backend: string, error?: string },
+ * }} WhereData
+ */
+
+function isDir(p) {
+  try {
+    return statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Walk cwd → git root (or filesystem root, stop at $HOME) for a project
+ * `.mental/` directory. Never treat the user store `~/.mental` as a local
+ * project bundle (that would silently overlay every non-git cwd under home).
+ *
+ * @param {string} cwd
+ * @param {{ home: string, gitRoot: string | null }} opts
+ * @returns {string | null} absolute path to the `.mental` directory
+ */
+export function findLocalMental(cwd, { home, gitRoot }) {
+  const start = resolve(cwd);
+  const homeAbs = resolve(home);
+  const userStore = resolve(userMentalDir(home));
+  const gitAbs = gitRoot ? resolve(gitRoot) : null;
+  const { root: fsRoot } = parse(start);
+
+  let dir = start;
+  while (true) {
+    const candidate = join(dir, ".mental");
+    if (isDir(candidate)) {
+      const abs = resolve(candidate);
+      if (abs !== userStore) return abs;
+    }
+
+    if (gitAbs && dir === gitAbs) break;
+    if (dir === homeAbs) break;
+    if (dir === fsRoot) break;
+
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+/**
+ * @param {{
+ *   gitRoot: string,
+ *   home: string,
+ *   env: NodeJS.ProcessEnv,
+ *   write: boolean,
+ * }} opts
+ */
+function bindGit({ gitRoot, home, env, write }) {
+  const origin = getRemoteUrl(gitRoot, "origin", { env });
+  const upstream = getRemoteUrl(gitRoot, "upstream", { env });
+  return resolveOrCreateBinding({
+    gitRoot,
+    origin,
+    upstream,
+    home,
+    write,
+  });
+}
+
+/**
+ * Copy leftover `./.mental` into the UUID slice. Fail open: import errors
+ * do not block resolve.
+ *
+ * @param {{ leftover: string, dest: string, home: string, id: string }} opts
+ * @returns {ImportResult}
+ */
+function importLeftover({ leftover, dest, home, id }) {
+  try {
+    const result = importLegacyBundle(leftover, dest);
+    recordLegacyImport(home, id, leftover, { copied: result.copied });
+    return result;
+  } catch (err) {
+    return {
+      from: leftover,
+      to: dest,
+      copied: [],
+      skipped: 0,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+/**
+ * @param {WhereData} data
+ * @param {{ write: boolean, home: string, env: NodeJS.ProcessEnv }} ctx
+ */
+function withIndex(data, { write, home, env }) {
+  if (write && data.id && home) {
+    data.indexed = reindexBundle({ root: data.root, id: data.id, home, env });
+  }
+  return { ok: true, data };
+}
+
+/**
+ * @param {{
+ *   cwd?: string,
+ *   home?: string | null,
+ *   env?: NodeJS.ProcessEnv,
+ *   dir?: string | null,
+ *   write?: boolean,
+ * }} [opts]
+ * @returns {{ ok: true, data: WhereData } | { ok: false, error: { code: string, message: string } }}
+ */
+export function resolveBundle({
+  cwd = process.cwd(),
+  home = process.env.HOME ?? process.env.USERPROFILE ?? null,
+  env = process.env,
+  dir = null,
+  write = true,
+} = {}) {
+  const gitRoot = findGitRoot(cwd, { env });
+
+  const dirOverride = dir || env.MENTAL_DIR || null;
+  if (dirOverride) {
+    const abs = resolve(cwd, dirOverride);
+    if (!isDir(abs)) {
+      return {
+        ok: false,
+        error: {
+          code: "env-dir-missing",
+          message: `MENTAL_DIR / --dir is not a directory: ${abs}`,
+        },
+      };
+    }
+    return {
+      ok: true,
+      data: {
+        root: abs,
+        id: null,
+        mode: "env",
+        reason: dir ? `--dir ${abs}` : `MENTAL_DIR=${abs}`,
+        gitRoot,
+      },
+    };
+  }
+
+  if (!home) {
+    return {
+      ok: false,
+      error: {
+        code: "no-home",
+        message: "HOME is unset; Mental will not write. Set HOME or MENTAL_DIR.",
+      },
+    };
+  }
+
+  const leftover = findLocalMental(cwd, { home, gitRoot });
+  const optedIn = Boolean(leftover && isOptedInLocal(leftover));
+
+  if (optedIn && leftover) {
+    let id = null;
+    let reason = `walk-up found opted-in ${leftover}`;
+    if (gitRoot) {
+      try {
+        const bound = bindGit({ gitRoot, home, env, write });
+        if (!bound.ok) {
+          return { ok: false, error: { code: bound.code, message: bound.message } };
+        }
+        if (bound.id) {
+          id = bound.id;
+          reason = `${reason}; ${bound.reason}`;
+        }
+      } catch (err) {
+        return {
+          ok: false,
+          error: {
+            code: "bindings",
+            message: err instanceof Error ? err.message : String(err),
+          },
+        };
+      }
+    }
+    return withIndex(
+      {
+        root: leftover,
+        id,
+        mode: "local",
+        reason,
+        gitRoot,
+      },
+      { write, home, env },
+    );
+  }
+
+  if (gitRoot) {
+    try {
+      const bound = bindGit({ gitRoot, home, env, write });
+      if (!bound.ok) {
+        return { ok: false, error: { code: bound.code, message: bound.message } };
+      }
+      if (!bound.id) {
+        return {
+          ok: true,
+          data: {
+            root: join(userMentalDir(home), "projects"),
+            id: null,
+            mode: "home",
+            reason: leftover
+              ? `${bound.reason}; leftover ${leftover} imports on next write`
+              : bound.reason,
+            gitRoot,
+          },
+        };
+      }
+      const dest = projectSliceDir(home, bound.id);
+      /** @type {ImportResult | null} */
+      let imported = null;
+      let reason = bound.reason;
+      if (write && leftover) {
+        imported = importLeftover({ leftover, dest, home, id: bound.id });
+        const n = imported.copied.length;
+        reason =
+          n > 0
+            ? `${bound.reason}; imported ${n} leftover file(s) from ${leftover}`
+            : imported.error
+              ? `${bound.reason}; leftover import failed: ${imported.error}`
+              : `${bound.reason}; leftover ${leftover} already imported`;
+      } else if (leftover) {
+        reason = `${bound.reason}; leftover ${leftover} imports on next write`;
+      }
+      return withIndex(
+        {
+          root: dest,
+          id: bound.id,
+          mode: "home",
+          reason,
+          gitRoot,
+          imported,
+        },
+        { write, home, env },
+      );
+    } catch (err) {
+      return {
+        ok: false,
+        error: {
+          code: "bindings",
+          message: err instanceof Error ? err.message : String(err),
+        },
+      };
+    }
+  }
+
+  return {
+    ok: true,
+    data: {
+      root: userMentalDir(home),
+      id: null,
+      mode: "personal",
+      reason: leftover
+        ? `not a git repo; leftover ${leftover} not imported (need a git root)`
+        : "not a git repo; personal ~/.mental",
+      gitRoot: null,
+    },
+  };
+}

package/bin/lib/uninstall.mjs

@@ -0,0 +1,56 @@
+/**
+ * Remove Mental skill+rule copies from user agent dirs. Never deletes OKF
+ * unless the uninstall command also gets `--delete-data DELETE`.
+ */
+import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { BEGIN, END } from "./pkg.mjs";
+import { userInstallTargets } from "./install-skills.mjs";
+
+function esc(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Strip the managed BEGIN/END block from AGENTS.md / CLAUDE.md.
+ * @param {string} file
+ */
+export function removeManaged(file) {
+  if (!existsSync(file)) return false;
+  const cur = readFileSync(file, "utf8");
+  if (!cur.includes(BEGIN) || !cur.includes(END)) return false;
+  const re = new RegExp(`\\n?${esc(BEGIN)}[\\s\\S]*?${esc(END)}\\n?`);
+  const next = cur.replace(re, "\n").replace(/^\n+/, "").replace(/\n{3,}/g, "\n\n");
+  writeFileSync(file, next);
+  return true;
+}
+
+/**
+ * @param {{ home: string, projectDir?: string | null }} opts
+ */
+export function uninstallSkills({ home, projectDir = null }) {
+  const targets = userInstallTargets(home);
+  /** @type {string[]} */
+  const removed = [];
+  for (const dest of targets.skills) {
+    if (existsSync(dest)) {
+      rmSync(dest, { recursive: true, force: true });
+      removed.push(dest);
+    }
+  }
+  if (existsSync(targets.cursorRule)) {
+    rmSync(targets.cursorRule, { force: true });
+    removed.push(targets.cursorRule);
+  }
+  for (const doc of targets.managedDocs) {
+    if (removeManaged(doc)) removed.push(doc);
+  }
+  if (projectDir) {
+    const vendored = join(projectDir, ".github", "skills", "mental");
+    if (existsSync(vendored)) {
+      rmSync(vendored, { recursive: true, force: true });
+      removed.push(vendored);
+    }
+  }
+  return { ok: true, removed };
+}

package/hooks/session-start.sh

@@ -0,0 +1,4 @@
+#!/bin/sh
+# Optional session-start hook. Default off — enable later with `mental hooks on`.
+# Caps output so agent context stays small.
+mental status --json 2>/dev/null | head -c 4096

package/mcp.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+  "mcpServers": {
+    "mental": {
+      "type": "stdio",
+      "command": "./bin/cli.mjs",
+      "args": ["serve"],
+      "cwd": "${PLUGIN_ROOT}"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@balacode/mental",
+  "version": "0.2.0",
+  "description": "Never reconstruct where you left off. Mental keeps the resume, the decisions, and what's still in the air.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "mental": "bin/cli.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "mental": "node bin/cli.mjs"
+  },
+  "files": [
+    "bin",
+    "skills",
+    "rules",
+    "hooks",
+    "plugin.json",
+    "mcp.json",
+    "assets",
+    ".cursor-plugin",
+    ".claude-plugin",
+    ".mcp.json",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/afaraha8403/mental.git"
+  },
+  "homepage": "https://github.com/afaraha8403/mental#readme",
+  "bugs": {
+    "url": "https://github.com/afaraha8403/mental/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/plugin.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "mental",
+  "version": "0.2.0",
+  "description": "Never reconstruct where you left off. Mental keeps the resume, the decisions, and what's still in the air — so you and your agents continue as if the last session never ended.",
+  "author": {
+    "name": "Ali Farahat",
+    "url": "https://github.com/afaraha8403"
+  },
+  "homepage": "https://github.com/afaraha8403/mental#readme",
+  "repository": "https://github.com/afaraha8403/mental",
+  "license": "MIT",
+  "keywords": [
+    "continuity",
+    "journal",
+    "decisions",
+    "okf",
+    "skills",
+    "mcp"
+  ]
+}

package/rules/mental.mdc

@@ -0,0 +1,18 @@
+---
+description: Project continuity is Mental. Orient and hand off via the CLI; never grep OKF.
+alwaysApply: true
+---
+
+Continuity is Mental. On start/finish of real work, or orientation questions, use the Mental skill.
+
+Run `mental where` then `mental heartbeat --json` (or `mental status --json` when notes are needed). Do not grep `.mental` or `~/.mental`. Do not parse YAML frontmatter yourself.
+
+Mid-chat, not just start/finish: before changing an approach, `mental search "…" --json` for prior decisions. When residue surfaces ("X said…", a concern, "park this"), record `mental attention … --json` immediately — do not wait for the handoff. If other agents may have written since you oriented, re-pulse `mental heartbeat --json`; it is cheap and derives git live.
+
+If `mental` is not on PATH, try `npx @balacode/mental …`. If that fails, continue the user's coding task and mention install. Missing Mental must not block work.
+
+Never commit Mental data. Never write secrets. Never edit gitignore; tell the user to run `mental doctor`.
+
+If you invoked `mental` this turn, end the user-visible reply with `<br>`, then the title `🧠 Mental`, then type lines under it (example in the Mental skill). Not a code fence.
+
+On a pasted transcript or a plan-progress question ("where in the plan / what's left?"), use the Mental skill. Cheap reload is `mental heartbeat --json`, not a notes dump.