@balacode/mental 0.2.0

package/bin/commands/doctor.mjs

@@ -0,0 +1,150 @@
+/**
+ * `mental doctor` — PATH, where, bindings, ignore, skill presence.
+ * Exit 3 when problems exist (still prints JSON).
+ */
+import { existsSync } from "node:fs";
+import { resolve as resolvePath } from "node:path";
+import { resolveBundle, findLocalMental } from "../lib/resolve.mjs";
+import { loadBindings } from "../lib/bindings.mjs";
+import { checkMentalIgnored, ensureMentalExcluded, gitAvailable } from "../lib/ignore.mjs";
+import { skillsPresent } from "../lib/install-skills.mjs";
+import { printResult, brandMark } from "../lib/output.mjs";
+import { CMD } from "../lib/pkg.mjs";
+import { isOptedInLocal } from "../lib/import-legacy.mjs";
+import { findGitRoot } from "../lib/git.mjs";
+import { indexPath } from "../lib/index.mjs";
+
+function check(id, ok, message, level = "error") {
+  return { id, ok, level, message };
+}
+
+export function cmdDoctor(args, io = {}) {
+  const stdout = io.stdout ?? process.stdout;
+  const home = args.home ?? process.env.HOME ?? process.env.USERPROFILE ?? null;
+  const cwd = args.cwd ?? process.cwd();
+  const env = args.env ?? process.env;
+  const fixIgnore = Boolean(args.flags?.["fix-ignore"]);
+
+  /** @type {ReturnType<typeof check>[]} */
+  const checks = [];
+
+  if (!home) {
+    checks.push(check("home", false, "HOME unset; no writes"));
+  } else {
+    checks.push(check("home", true, home));
+  }
+
+  checks.push(
+    check("git", gitAvailable({ env }), gitAvailable({ env }) ? "git on PATH" : "git missing"),
+  );
+
+  if (fixIgnore && home) {
+    const r = ensureMentalExcluded({ home, env });
+    checks.push(
+      check(
+        "fix-ignore",
+        Boolean(r.ok),
+        r.ok ? `excludes: ${r.file}` : r.reason || "fix-ignore failed",
+      ),
+    );
+  }
+
+  const resolved = resolveBundle({
+    cwd,
+    home,
+    env,
+    dir: args.dir ?? null,
+    write: false,
+  });
+  if (resolved.ok) {
+    checks.push(check("where", true, `${resolved.data.mode} ${resolved.data.root}`));
+    if (resolved.data.mode === "local") {
+      const ign = checkMentalIgnored({ cwd, env });
+      checks.push(
+        check(
+          "local-ignore",
+          ign.liveIgnored === true,
+          ign.liveIgnored
+            ? ".mental/ is ignored"
+            : "local .mental/ is NOT ignored — run mental doctor --fix-ignore",
+        ),
+      );
+    }
+    if (resolved.data.id) {
+      const file = indexPath(home, resolved.data.id, env);
+      const has = existsSync(file);
+      checks.push(
+        check(
+          "index",
+          true,
+          has ? `sqlite ${file}` : "no sqlite index yet — run mental where or mental reindex",
+          has ? "info" : "warn",
+        ),
+      );
+    }
+  } else {
+    checks.push(check("where", false, resolved.error.message));
+  }
+
+  if (home) {
+    /** @type {ReturnType<typeof loadBindings> | null} */
+    let bindings = null;
+    try {
+      bindings = loadBindings(home);
+      checks.push(check("bindings", true, `${bindings.bindings.length} binding(s)`));
+    } catch (err) {
+      checks.push(check("bindings", false, err instanceof Error ? err.message : String(err)));
+    }
+
+    checks.push(
+      check(
+        "skills",
+        skillsPresent(home),
+        skillsPresent(home)
+          ? "skill present in a user agent dir"
+          : `run \`${CMD} install\``,
+      ),
+    );
+
+    const gitRoot = resolved.ok ? resolved.data.gitRoot : findGitRoot(cwd, { env });
+    const leftover = findLocalMental(cwd, { home, gitRoot });
+    if (leftover && !isOptedInLocal(leftover)) {
+      const leftoverAbs = resolvePath(leftover);
+      const imported = Boolean(
+        bindings?.bindings.some(
+          (x) => x.legacyImportedFrom && resolvePath(x.legacyImportedFrom) === leftoverAbs,
+        ),
+      );
+      checks.push(
+        check(
+          "legacy-import",
+          true,
+          imported
+            ? `leftover ${leftover} still on disk; already imported into ~/.mental/projects (not deleted)`
+            : `leftover ${leftover} will import into ~/.mental/projects on next write (status/journal/install)`,
+          "warn",
+        ),
+      );
+    }
+  }
+
+  const problems = checks.filter((c) => !c.ok && c.level === "error");
+  const data = {
+    checks,
+    where: resolved.ok ? resolved.data : null,
+    problems: problems.length,
+  };
+  printResult(
+    stdout,
+    args.json,
+    true,
+    data,
+    undefined,
+    (d) =>
+      d.checks
+        .map((c) => `${c.ok ? "✓" : "✖"} ${c.id}: ${c.message}`)
+        .join("\n") +
+      (problems.length ? `\n${problems.length} problem(s)` : `\n${brandMark()} doctor clean`),
+  );
+  return problems.length ? 3 : 0;
+}

package/bin/commands/heartbeat.mjs

@@ -0,0 +1,21 @@
+/**
+ * `mental` with no args on a TTY, or `mental heartbeat` — print the pulse and exit.
+ * Agents: `mental heartbeat --json`.
+ */
+import { collectHeartbeat, formatHeartbeat } from "../lib/heartbeat.mjs";
+import { printResult } from "../lib/output.mjs";
+
+/**
+ * @param {{ json: boolean, dir?: string, cwd?: string, home?: string, env?: NodeJS.ProcessEnv }} args
+ * @returns {number}
+ */
+export function cmdHeartbeat(args, io = {}) {
+  const stdout = io.stdout ?? process.stdout;
+  const collected = collectHeartbeat(args);
+  if (!collected.ok) {
+    printResult(stdout, args.json, false, undefined, collected.error);
+    return 1;
+  }
+  printResult(stdout, args.json, true, collected.data, undefined, formatHeartbeat);
+  return 0;
+}

package/bin/commands/hooks.mjs

@@ -0,0 +1,41 @@
+/**
+ * `mental hooks on|off` — optional session-start snippets. Default off.
+ */
+import { disableHooks, enableHooks } from "../lib/hooks.mjs";
+import { printResult } from "../lib/output.mjs";
+
+export function cmdHooks(args, io = {}) {
+  const stdout = io.stdout ?? process.stdout;
+  const home = args.home ?? process.env.HOME ?? process.env.USERPROFILE ?? null;
+  if (!home) {
+    printResult(stdout, args.json, false, undefined, {
+      code: "no-home",
+      message: "HOME is unset; Mental will not write hooks.",
+    });
+    return 1;
+  }
+
+  const action = (args.rest[0] || "").toLowerCase();
+  if (action !== "on" && action !== "off") {
+    printResult(stdout, args.json, false, undefined, {
+      code: "usage",
+      message: "mental hooks on|off  (default off; install does not enable hooks)",
+    });
+    return 1;
+  }
+
+  const result = action === "on" ? enableHooks(home) : disableHooks(home);
+  if (!result.ok) {
+    printResult(stdout, args.json, false, undefined, result.error);
+    return 1;
+  }
+  printResult(
+    stdout,
+    args.json,
+    true,
+    { action, ...result },
+    undefined,
+    () => `hooks ${action}: ${result.written.join(", ") || "nothing to change"}`,
+  );
+  return 0;
+}

package/bin/commands/install.mjs

@@ -0,0 +1,86 @@
+/**
+ * `mental install` — copy skill + tiny rule to user agent dirs; ~/.mental skeleton.
+ * `--hooks` and `--mcp` are optional and default off.
+ */
+import { resolveBundle } from "../lib/resolve.mjs";
+import { userMentalDir } from "../lib/bindings.mjs";
+import { ensureSkeleton } from "../lib/okf.mjs";
+import { installSkills } from "../lib/install-skills.mjs";
+import { installGlobalCli } from "../lib/install-cli.mjs";
+import { enableHooks } from "../lib/hooks.mjs";
+import { enableMcp } from "../lib/mcp.mjs";
+import { CMD } from "../lib/pkg.mjs";
+import { printResult, brandLine } from "../lib/output.mjs";
+
+export function cmdInstall(args, io = {}) {
+  const stdout = io.stdout ?? process.stdout;
+  const home = args.home ?? process.env.HOME ?? process.env.USERPROFILE ?? null;
+  if (!home) {
+    printResult(stdout, args.json, false, undefined, {
+      code: "no-home",
+      message: "HOME is unset; refusing to install. Mental fails open — continue coding.",
+    });
+    return 1;
+  }
+
+  const project = Boolean(args.flags?.project);
+  const hooks = Boolean(args.flags?.hooks);
+  const mcp = Boolean(args.flags?.mcp);
+  const cwd = args.cwd ?? process.cwd();
+
+  const installed = installSkills({
+    home,
+    projectDir: project ? cwd : null,
+  });
+  const cli = installGlobalCli({ home, env: args.env ?? process.env });
+  const personal = userMentalDir(home);
+  ensureSkeleton(personal, { name: "personal" });
+
+  let hookResult = null;
+  if (hooks) hookResult = enableHooks(home);
+
+  let mcpResult = null;
+  if (mcp) mcpResult = enableMcp(home);
+
+  const resolved = resolveBundle({
+    cwd,
+    home,
+    env: args.env ?? process.env,
+    dir: args.dir ?? null,
+    write: true,
+  });
+
+  const imported = resolved.ok ? resolved.data.imported : null;
+  const data = {
+    home,
+    personalRoot: personal,
+    skills: installed.written,
+    cli,
+    project: project ? `${cwd}/.github/skills/mental` : null,
+    hooks: hookResult,
+    mcp: mcpResult,
+    where: resolved.ok ? resolved.data : null,
+    imported: imported || null,
+  };
+  const importLine =
+    imported?.copied?.length
+      ? `\nimported ${imported.copied.length} leftover file(s) from ${imported.from}`
+      : "";
+  const cliLine = cli.bin ? `\nCLI: ${cli.bin}` : "";
+  const hookLine = hooks ? "\nhooks: enabled (session-start → mental status --json)" : "";
+  const mcpLine = mcp
+    ? mcpResult?.ok
+      ? `\nMCP: ${CMD} serve registered in ${mcpResult.written.join(", ")}`
+      : `\nMCP: config write failed (${mcpResult?.error?.message ?? "unknown"}) — add \`${CMD} serve\` manually`
+    : "";
+  printResult(
+    stdout,
+    args.json,
+    true,
+    data,
+    undefined,
+    () =>
+      `${brandLine(`installed skill + rule (${installed.written.length} paths)`)}\n~/.mental skeleton: ${personal}${cliLine}${hookLine}${mcpLine}${importLine}`,
+  );
+  return 0;
+}

package/bin/commands/journal.mjs

@@ -0,0 +1,54 @@
+/**
+ * `mental journal` — append one section to today's journal (task boundary).
+ */
+import { resolveBundle } from "../lib/resolve.mjs";
+import { appendJournal, bundleName, ensureSkeleton, repoRelativePath } from "../lib/okf.mjs";
+import { refreshIndex } from "../lib/index.mjs";
+import { printResult, kindLine } from "../lib/output.mjs";
+
+/**
+ * @param {{ json: boolean, dir?: string, flags?: Record<string, string | boolean>, cwd?: string, home?: string, env?: NodeJS.ProcessEnv }} args
+ * @returns {number}
+ */
+export function cmdJournal(args, io = {}) {
+  const stdout = io.stdout ?? process.stdout;
+  const title = typeof args.flags?.title === "string" ? args.flags.title : null;
+  if (!title) {
+    printResult(stdout, args.json, false, undefined, {
+      code: "usage",
+      message: "mental journal requires --title (agents also pass --body --resume --json)",
+    });
+    return 1;
+  }
+  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: true,
+  });
+  if (!resolved.ok) {
+    printResult(stdout, args.json, false, undefined, resolved.error);
+    return 1;
+  }
+  const body = typeof args.flags?.body === "string" ? args.flags.body : "";
+  const resume = typeof args.flags?.resume === "string" ? args.flags.resume : "Continue. — open loops: none";
+  const againstRaw = typeof args.flags?.against === "string" ? args.flags.against : undefined;
+  const against = againstRaw != null ? repoRelativePath(againstRaw) : undefined;
+  if (againstRaw != null && against === null) {
+    printResult(stdout, args.json, false, undefined, {
+      code: "usage",
+      message: "--against must be a repo-relative path (no ..)",
+    });
+    return 1;
+  }
+  ensureSkeleton(resolved.data.root, {
+    name: bundleName(resolved.data.root, resolved.data.id || "project"),
+  });
+  const written = appendJournal(resolved.data.root, { title, body, resume, against });
+  const home = args.home ?? process.env.HOME ?? process.env.USERPROFILE ?? null;
+  const indexed = refreshIndex(resolved.data, home, args.env ?? process.env);
+  const data = { ...resolved.data, ...written, indexed };
+  printResult(stdout, args.json, true, data, undefined, () => kindLine("journal", `appended ${written.path}`));
+  return 0;
+}

package/bin/commands/link.mjs

@@ -0,0 +1,18 @@
+/**
+ * `mental link` — point this cwd at an existing UUID (second clone of same project).
+ */
+import { printResult } from "../lib/output.mjs";
+import { cmdRemap } from "./remap.mjs";
+
+export function cmdLink(args, io = {}) {
+  const stdout = io.stdout ?? process.stdout;
+  const to = typeof args.flags?.to === "string" ? args.flags.to : null;
+  if (!to) {
+    printResult(stdout, args.json, false, undefined, {
+      code: "usage",
+      message: "mental link requires --to <uuid> (or run mental remap --to <uuid>)",
+    });
+    return 1;
+  }
+  return cmdRemap({ ...args, flags: { ...args.flags, to } }, io);
+}

package/bin/commands/list.mjs

@@ -0,0 +1,51 @@
+/**
+ * `mental list` — concepts in the active bundle (filters: --type --status --tag --kind).
+ */
+import { resolveBundle } from "../lib/resolve.mjs";
+import { filterConcepts, listConcepts } from "../lib/index.mjs";
+import { printResult } from "../lib/output.mjs";
+
+function summarize(c) {
+  return {
+    path: c.path,
+    type: c.type,
+    title: c.title,
+    description: c.description || "",
+    status: c.status,
+    kind: c.kind || "",
+    tags: c.tags,
+  };
+}
+
+export function cmdList(args, io = {}) {
+  const stdout = io.stdout ?? process.stdout;
+  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) {
+    printResult(stdout, args.json, false, undefined, resolved.error);
+    return 1;
+  }
+  const type = typeof args.flags?.type === "string" ? args.flags.type : undefined;
+  const status = typeof args.flags?.status === "string" ? args.flags.status : undefined;
+  const tag = typeof args.flags?.tag === "string" ? args.flags.tag : undefined;
+  const kind = typeof args.flags?.kind === "string" ? args.flags.kind : undefined;
+  const items = filterConcepts(listConcepts(resolved.data.root), { type, status, tag, kind }).map(summarize);
+  const data = {
+    ...resolved.data,
+    items,
+    type: type ?? null,
+    status: status ?? null,
+    tag: tag ?? null,
+    kind: kind ?? null,
+  };
+  printResult(stdout, args.json, true, data, undefined, (d) => {
+    if (d.items.length === 0) return "(none)";
+    return d.items.map((i) => `[${i.type}] ${i.title} (${i.path})`).join("\n");
+  });
+  return 0;
+}

package/bin/commands/local.mjs

@@ -0,0 +1,118 @@
+/**
+ * `mental local` — opt in to a project-local bundle.
+ * Refuse unless git will ignore `./.mental/` (v1 always private).
+ *
+ * Leftover Balakit `./.mental` is snapshotted into the home UUID store first,
+ * then this folder becomes the write root.
+ *
+ * `--import` copies the home UUID slice into `./.mental`.
+ * `--move` does the same and marks the binding store=local (home files stay
+ * unless `--delete-home`).
+ */
+import { existsSync, rmSync } from "node:fs";
+import { basename, join } from "node:path";
+import { findGitRoot } from "../lib/git.mjs";
+import { assertLocalIgnorable } from "../lib/ignore.mjs";
+import { bundleName, copyOkfTree, ensureSkeleton } from "../lib/okf.mjs";
+import { printResult } from "../lib/output.mjs";
+import { resolveBundle } from "../lib/resolve.mjs";
+import { projectSliceDir, setBindingStore } from "../lib/bindings.mjs";
+import { isOptedInLocal, markOptedInLocal } from "../lib/import-legacy.mjs";
+
+export function cmdLocal(args, io = {}) {
+  const stdout = io.stdout ?? process.stdout;
+  const cwd = args.cwd ?? process.cwd();
+  const env = args.env ?? process.env;
+  const home = args.home ?? env.HOME ?? env.USERPROFILE ?? null;
+  const doImport = Boolean(args.flags?.import);
+  const doMove = Boolean(args.flags?.move);
+  const deleteHome = Boolean(args.flags?.["delete-home"]);
+
+  const gitRoot = findGitRoot(cwd, { env });
+  const destRoot = gitRoot || cwd;
+  const dest = join(destRoot, ".mental");
+
+  const gate = assertLocalIgnorable(destRoot, { env });
+  if (!gate.ok) {
+    printResult(stdout, args.json, false, undefined, gate.error);
+    return 1;
+  }
+
+  const leftoverExists = existsSync(dest);
+  const alreadyOpted = leftoverExists && isOptedInLocal(dest);
+
+  if (leftoverExists && !alreadyOpted) {
+    resolveBundle({
+      cwd,
+      home,
+      env,
+      dir: args.dir ?? null,
+      write: true,
+    });
+  }
+
+  const homeWhere = resolveBundle({
+    cwd,
+    home,
+    env,
+    dir: args.dir ?? null,
+    write: true,
+  });
+  if (!homeWhere.ok) {
+    printResult(stdout, args.json, false, undefined, homeWhere.error);
+    return 1;
+  }
+
+  const created = !leftoverExists;
+  ensureSkeleton(dest, { name: bundleName(dest, basename(destRoot)) });
+
+  let copied = [];
+  if ((doImport || doMove) && homeWhere.data.id && homeWhere.data.mode !== "local") {
+    const slice = projectSliceDir(home, homeWhere.data.id);
+    copied = copyOkfTree(slice, dest);
+  } else if ((doImport || doMove) && homeWhere.data.mode === "home" && homeWhere.data.root) {
+    copied = copyOkfTree(homeWhere.data.root, dest);
+  }
+
+  markOptedInLocal(dest);
+
+  const where = resolveBundle({
+    cwd,
+    home,
+    env,
+    dir: args.dir ?? null,
+    write: true,
+  });
+  if (where.ok && where.data.id && home) {
+    setBindingStore(home, where.data.id, "local");
+  }
+
+  let purged = null;
+  if (doMove && deleteHome && homeWhere.data.id && home) {
+    const slice = projectSliceDir(home, homeWhere.data.id);
+    if (existsSync(slice) && slice !== dest) {
+      rmSync(slice, { recursive: true, force: true });
+      purged = slice;
+    }
+  }
+
+  const data = {
+    root: dest,
+    created,
+    imported: doImport || doMove,
+    copied,
+    purged,
+    gitRoot: gitRoot || null,
+    where: where.ok ? where.data : null,
+  };
+  printResult(
+    stdout,
+    args.json,
+    true,
+    data,
+    undefined,
+    () =>
+      `${created ? "created" : "already present"} ${dest}${copied.length ? `\ncopied ${copied.join(", ")}` : ""}`,
+  );
+  return 0;
+}

package/bin/commands/note.mjs

@@ -0,0 +1,61 @@
+/**
+ * `mental note` — scaffold a durable note (only if it will save future time).
+ */
+import { resolveBundle } from "../lib/resolve.mjs";
+import { bundleName, ensureSkeleton, writeNote } from "../lib/okf.mjs";
+import { refreshIndex } from "../lib/index.mjs";
+import { printResult, kindLine } from "../lib/output.mjs";
+
+const STATUSES = new Set(["draft", "active", "superseded"]);
+
+export function cmdNote(args, io = {}) {
+  const stdout = io.stdout ?? process.stdout;
+  const title = typeof args.flags?.title === "string" ? args.flags.title : null;
+  if (!title) {
+    printResult(stdout, args.json, false, undefined, {
+      code: "usage",
+      message: "mental note requires --title",
+    });
+    return 1;
+  }
+  const status = typeof args.flags?.status === "string" ? args.flags.status : "active";
+  if (!STATUSES.has(status)) {
+    printResult(stdout, args.json, false, undefined, {
+      code: "usage",
+      message: `status must be ${[...STATUSES].join("|")}`,
+    });
+    return 1;
+  }
+  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: true,
+  });
+  if (!resolved.ok) {
+    printResult(stdout, args.json, false, undefined, resolved.error);
+    return 1;
+  }
+  ensureSkeleton(resolved.data.root, {
+    name: bundleName(resolved.data.root, resolved.data.id || "project"),
+  });
+  try {
+    const written = writeNote(resolved.data.root, {
+      title,
+      status,
+      description: typeof args.flags?.description === "string" ? args.flags.description : "",
+      body: typeof args.flags?.body === "string" ? args.flags.body : "",
+      slug: typeof args.flags?.slug === "string" ? args.flags.slug : undefined,
+    });
+    const home = args.home ?? process.env.HOME ?? process.env.USERPROFILE ?? null;
+    const indexed = refreshIndex(resolved.data, home, args.env ?? process.env);
+    printResult(stdout, args.json, true, { ...resolved.data, ...written, indexed }, undefined, () => kindLine("note", `wrote ${written.path}`));
+    return 0;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const code = /** @type {{ code?: string }} */ (err).code || "write";
+    printResult(stdout, args.json, false, undefined, { code, message });
+    return 1;
+  }
+}

package/bin/commands/reindex.mjs

@@ -0,0 +1,48 @@
+/**
+ * `mental reindex` — rebuild the derived sqlite index from OKF files.
+ */
+import { resolveBundle } from "../lib/resolve.mjs";
+import { reindexBundle } from "../lib/index.mjs";
+import { printResult, brandLine } from "../lib/output.mjs";
+
+export function cmdReindex(args, io = {}) {
+  const stdout = io.stdout ?? process.stdout;
+  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: true,
+  });
+  if (!resolved.ok) {
+    printResult(stdout, args.json, false, undefined, resolved.error);
+    return 1;
+  }
+  if (!resolved.data.id) {
+    printResult(stdout, args.json, false, undefined, {
+      code: "no-id",
+      message: "No project UUID yet; reindex needs a git binding. Run `mental where` in a repo.",
+    });
+    return 1;
+  }
+  const indexed =
+    resolved.data.indexed ??
+    reindexBundle({
+      root: resolved.data.root,
+      id: resolved.data.id,
+      home: args.home ?? process.env.HOME ?? process.env.USERPROFILE,
+      env: args.env ?? process.env,
+    });
+  printResult(
+    stdout,
+    args.json,
+    indexed.ok,
+    { ...resolved.data, indexed },
+    indexed.ok ? undefined : { code: "index", message: indexed.error || "reindex failed" },
+    (d) =>
+      d.indexed.ok
+        ? brandLine(`indexed ${d.indexed.concepts} concept(s) → ${d.indexed.path}`)
+        : d.indexed.error || "reindex failed",
+  );
+  return indexed.ok ? 0 : 1;
+}