@balacode/mental 0.2.0

package/bin/commands/remap.mjs

@@ -0,0 +1,76 @@
+/**
+ * `mental remap` — list bindings, or point this clone at an existing UUID.
+ * Flags, not a standing TTY session: `--to <id>` or `--from <id>`.
+ */
+import { findGitRoot, getRemoteUrl } from "../lib/git.mjs";
+import { loadBindings, remapToBinding } from "../lib/bindings.mjs";
+import { printResult } from "../lib/output.mjs";
+
+export function formatBindings(home) {
+  const data = loadBindings(home);
+  if (!data.bindings.length) return "(no bindings)";
+  return data.bindings
+    .map((b) =>
+      [
+        `${b.id}  ${b.name || ""}`.trim(),
+        `  origins  ${(b.origins || []).join(", ") || "—"}`,
+        `  paths    ${(b.paths || []).join(", ") || "—"}`,
+        b.store ? `  store    ${b.store}` : null,
+      ]
+        .filter(Boolean)
+        .join("\n"),
+    )
+    .join("\n\n");
+}
+
+export function cmdRemap(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;
+  if (!home) {
+    printResult(stdout, args.json, false, undefined, {
+      code: "no-home",
+      message: "HOME is unset; Mental will not write.",
+    });
+    return 1;
+  }
+
+  const to =
+    (typeof args.flags?.to === "string" && args.flags.to) ||
+    (typeof args.flags?.from === "string" && args.flags.from) ||
+    null;
+
+  if (!to) {
+    const list = formatBindings(home);
+    printResult(stdout, args.json, true, { bindings: loadBindings(home).bindings }, undefined, () =>
+      `${list}\n\nPoint this clone: mental remap --to <id>`,
+    );
+    return 0;
+  }
+
+  const gitRoot = findGitRoot(cwd, { env });
+  if (!gitRoot) {
+    printResult(stdout, args.json, false, undefined, {
+      code: "not-git",
+      message: "mental remap needs a git repository.",
+    });
+    return 1;
+  }
+
+  const origin = getRemoteUrl(gitRoot, "origin", { env });
+  const result = remapToBinding({ home, gitRoot, toId: to, origin });
+  if (!result.ok) {
+    printResult(stdout, args.json, false, undefined, { code: result.code, message: result.message });
+    return 1;
+  }
+  printResult(
+    stdout,
+    args.json,
+    true,
+    { id: result.id, gitRoot, origin },
+    undefined,
+    () => `this clone → ${result.id}`,
+  );
+  return 0;
+}

package/bin/commands/search.mjs

@@ -0,0 +1,55 @@
+/**
+ * `mental search` — query the derived index (sqlite) or scan OKF files.
+ */
+import { resolveBundle } from "../lib/resolve.mjs";
+import { searchBundle } from "../lib/index.mjs";
+import { printResult } from "../lib/output.mjs";
+
+export function cmdSearch(args, io = {}) {
+  const stdout = io.stdout ?? process.stdout;
+  const q = args.rest.join(" ").trim();
+  if (!q) {
+    printResult(stdout, args.json, false, undefined, {
+      code: "usage",
+      message: "mental search requires a query",
+    });
+    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: 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 found = searchBundle({
+    root: resolved.data.root,
+    id: resolved.data.id,
+    home: args.home ?? process.env.HOME ?? process.env.USERPROFILE ?? null,
+    env: args.env ?? process.env,
+    q,
+    type,
+    status,
+    tag,
+    kind,
+  });
+  const data = { ...resolved.data, q, ...found };
+  printResult(stdout, args.json, true, data, undefined, (d) => {
+    if (d.hits.length === 0) return `no hits for ${d.q} (${d.backend})`;
+    return d.hits
+      .map((h) => {
+        const line = `[${h.type}] ${h.title} (${h.path})`;
+        return h.snippet ? `${line}\n  ${h.snippet}` : line;
+      })
+      .join("\n");
+  });
+  return 0;
+}

package/bin/commands/serve.mjs

@@ -0,0 +1,16 @@
+/**
+ * `mental serve` — optional MCP stdio wrapping the CLI commands
+ * (heartbeat/where/status/search/list/show/journal/attention/decide/note).
+ */
+import { serveMcp } from "../lib/mcp.mjs";
+
+export function cmdServe(args, io = {}) {
+  return serveMcp({
+    cwd: args.cwd,
+    home: args.home,
+    env: args.env,
+    dir: args.dir ?? null,
+    stdin: io.stdin,
+    stdout: io.stdout,
+  });
+}

package/bin/commands/show.mjs

@@ -0,0 +1,61 @@
+/**
+ * `mental show <path>` — one OKF file relative to the bundle root.
+ */
+import { resolveBundle } from "../lib/resolve.mjs";
+import { readBundleFile } from "../lib/okf.mjs";
+import { listBacklinks } from "../lib/index.mjs";
+import { printResult, kindLine } from "../lib/output.mjs";
+
+export function cmdShow(args, io = {}) {
+  const stdout = io.stdout ?? process.stdout;
+  const rel = (args.rest[0] || (typeof args.flags?.path === "string" ? args.flags.path : "")).trim();
+  if (!rel) {
+    printResult(stdout, args.json, false, undefined, {
+      code: "usage",
+      message: "mental show requires a path relative to the bundle root",
+    });
+    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: false,
+  });
+  if (!resolved.ok) {
+    printResult(stdout, args.json, false, undefined, resolved.error);
+    return 1;
+  }
+  const file = readBundleFile(resolved.data.root, rel);
+  if (!file.ok) {
+    printResult(stdout, args.json, false, undefined, file.error);
+    return 1;
+  }
+  const home = args.home ?? process.env.HOME ?? process.env.USERPROFILE ?? null;
+  const backlinks = listBacklinks({
+    root: resolved.data.root,
+    path: file.data.path,
+    id: resolved.data.id,
+    home,
+    env: args.env ?? process.env,
+  });
+  const payload = {
+    ...resolved.data,
+    path: file.data.path,
+    frontmatter: file.data.data,
+    body: file.data.body,
+    backlinks,
+  };
+  printResult(stdout, args.json, true, payload, undefined, (d) => {
+    const title = typeof d.frontmatter.title === "string" ? d.frontmatter.title : d.path;
+    const type = typeof d.frontmatter.type === "string" ? d.frontmatter.type : "";
+    const head = type ? `${title}  [${type}]` : title;
+    const linked =
+      d.backlinks.length === 0
+        ? ""
+        : `\n\nLinked from:\n${d.backlinks.map((b) => `  [${b.type}] ${b.title} (${b.path})`).join("\n")}`;
+    return `${kindLine("read", head)}\n${d.path}\n\n${d.body.trim() || "(empty)"}${linked}`;
+  });
+  return 0;
+}

package/bin/commands/split.mjs

@@ -0,0 +1,56 @@
+/**
+ * `mental split` — this clone gets a new UUID (empty or `--copy` of current OKF).
+ */
+import { findGitRoot, getRemoteUrl } from "../lib/git.mjs";
+import { projectSliceDir, splitBinding } from "../lib/bindings.mjs";
+import { bundleName, copyOkfTree, ensureSkeleton } from "../lib/okf.mjs";
+import { resolveBundle } from "../lib/resolve.mjs";
+import { printResult } from "../lib/output.mjs";
+
+export function cmdSplit(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;
+  if (!home) {
+    printResult(stdout, args.json, false, undefined, {
+      code: "no-home",
+      message: "HOME is unset; Mental will not write.",
+    });
+    return 1;
+  }
+
+  const gitRoot = findGitRoot(cwd, { env });
+  if (!gitRoot) {
+    printResult(stdout, args.json, false, undefined, {
+      code: "not-git",
+      message: "mental split needs a git repository.",
+    });
+    return 1;
+  }
+
+  const copy = Boolean(args.flags?.copy);
+  const prior = resolveBundle({ cwd, home, env, dir: args.dir ?? null, write: true });
+  if (!prior.ok) {
+    printResult(stdout, args.json, false, undefined, prior.error);
+    return 1;
+  }
+  const fromId = prior.data.id;
+  const fromRoot = prior.data.root;
+
+  const origin = getRemoteUrl(gitRoot, "origin", { env });
+  const split = splitBinding({ home, gitRoot, origin });
+  const dest = split.dest;
+  if (copy && fromRoot) copyOkfTree(fromRoot, dest);
+  ensureSkeleton(dest, { name: bundleName(dest, split.id) });
+
+  printResult(
+    stdout,
+    args.json,
+    true,
+    { id: split.id, fromId, gitRoot, copied: copy, root: dest, dest: projectSliceDir(home, split.id) },
+    undefined,
+    () => `split ${fromId || "—"} → ${split.id}${copy ? " (copied OKF)" : ""}`,
+  );
+  return 0;
+}

package/bin/commands/status.mjs

@@ -0,0 +1,136 @@
+/**
+ * `mental status` — derive git + latest Resume + open/deferred decisions + notes.
+ * Writes `status/current.md` as a disposable cache. OKF files remain SoT.
+ */
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { resolveBundle } from "../lib/resolve.mjs";
+import { gitSnapshot } from "../lib/git.mjs";
+import {
+  bundleName,
+  ensureSkeleton,
+  latestJournalHandoff,
+  listNotes,
+  listOpenAttention,
+  listOpenDecisions,
+  localDate,
+  renderStatus,
+} from "../lib/okf.mjs";
+import { printResult } from "../lib/output.mjs";
+
+function formatGit(git, gitRoot) {
+  if (!gitRoot) return "Not a git repository.";
+  const branch = git.branch || "(unknown branch)";
+  const dirty = git.dirty ? "uncommitted changes" : "clean";
+  const recent = git.recent.length ? git.recent.map((l) => `  ${l}`).join("\n") : "  (no commits)";
+  return `${branch}; ${dirty}\n${recent}`;
+}
+
+function formatHuman(data) {
+  const air =
+    data.attention.length === 0
+      ? "  none"
+      : data.attention.map((a) => {
+          const tag = a.status === "later" ? "later" : a.kind || a.status;
+          return `  - [${tag}] ${a.title} (${a.path})`;
+        }).join("\n");
+  const dec =
+    data.openDecisions.length === 0
+      ? "  none"
+      : data.openDecisions.map((d) => `  - [${d.status}] ${d.title} (${d.path})`).join("\n");
+  const notes =
+    data.notes.length === 0
+      ? "  none"
+      : data.notes.map((n) => `  - ${n.title} (${n.path})`).join("\n");
+  return [
+    `root:    ${data.root}`,
+    `mode:    ${data.mode}`,
+    `git:     ${data.git.branch || "—"} ${data.git.dirty ? "(dirty)" : "(clean)"}`,
+    `resume:  ${data.resume || "—"}`,
+    `against: ${data.against || "—"}`,
+    `now:     ${data.latestOutcome || "—"}`,
+    `in the air:`,
+    air,
+    `unsettled:`,
+    dec,
+    `notes:`,
+    notes,
+  ].join("\n");
+}
+
+/**
+ * @param {{ json: boolean, dir?: string, cwd?: string, home?: string, env?: NodeJS.ProcessEnv }} args
+ * @returns {number}
+ */
+export function cmdStatus(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;
+  }
+
+  const { data: where } = resolved;
+  const now = new Date();
+  ensureSkeleton(where.root, { name: bundleName(where.root, where.id || "project"), now });
+  const git = gitSnapshot(where.gitRoot, { env: args.env ?? process.env });
+  const handoff = latestJournalHandoff(where.root);
+  const openDecisions = listOpenDecisions(where.root);
+  const attention = listOpenAttention(where.root);
+  const notes = listNotes(where.root);
+  const name = bundleName(where.root, where.id || "project");
+  const inFlight = formatGit(git, where.gitRoot);
+  const resume = handoff.resume || "No journal yet — start work, then `mental journal` at the task boundary.";
+  const latestOutcome = handoff.outcome || "No journal sections yet.";
+  const against = handoff.against || null;
+
+  writeFileSync(
+    join(where.root, "status", "current.md"),
+    renderStatus({
+      name,
+      date: localDate(now),
+      ts: now.toISOString(),
+      now: latestOutcome,
+      inFlight,
+      decisions: openDecisions.map((d) => ({
+        title: d.title,
+        file: d.file,
+        status: d.status,
+      })),
+      attention: attention.map((a) => ({
+        title: a.title,
+        file: a.file,
+        status: a.status,
+        kind: a.kind,
+      })),
+      notes: notes.map((n) => ({
+        title: n.title,
+        file: n.file,
+        status: n.status,
+        description: n.description,
+      })),
+      resume,
+      against,
+    }),
+  );
+
+  const payload = {
+    ...where,
+    git: { branch: git.branch, dirty: git.dirty, recent: git.recent },
+    resume,
+    latestOutcome,
+    against,
+    attention,
+    openDecisions,
+    notes,
+    statusFile: "status/current.md",
+  };
+  printResult(stdout, args.json, true, payload, undefined, formatHuman);
+  return 0;
+}

package/bin/commands/uninstall.mjs

@@ -0,0 +1,58 @@
+/**
+ * `mental uninstall` — remove skill/rule/hooks Mental copied into user agent dirs.
+ * Does not delete ~/.mental unless `--delete-data DELETE`.
+ */
+import { existsSync, rmSync } from "node:fs";
+import { userMentalDir } from "../lib/bindings.mjs";
+import { uninstallSkills } from "../lib/uninstall.mjs";
+import { disableHooks } from "../lib/hooks.mjs";
+import { disableMcp } from "../lib/mcp.mjs";
+import { printResult } from "../lib/output.mjs";
+
+export function cmdUninstall(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; nothing to uninstall.",
+    });
+    return 1;
+  }
+
+  const deleteData = Boolean(args.flags?.["delete-data"]);
+  const confirm = typeof args.flags?.confirm === "string" ? args.flags.confirm : args.rest[0] || "";
+  if (deleteData && confirm !== "DELETE") {
+    printResult(stdout, args.json, false, undefined, {
+      code: "usage",
+      message: "Refusing to delete OKF. Pass --delete-data --confirm DELETE to wipe ~/.mental.",
+    });
+    return 1;
+  }
+
+  const skills = uninstallSkills({
+    home,
+    projectDir: args.flags?.project ? args.cwd ?? process.cwd() : null,
+  });
+  const hooks = disableHooks(home);
+  const mcp = disableMcp(home);
+  let wiped = null;
+  if (deleteData && confirm === "DELETE") {
+    const root = userMentalDir(home);
+    if (existsSync(root)) {
+      rmSync(root, { recursive: true, force: true });
+      wiped = root;
+    }
+  }
+
+  printResult(
+    stdout,
+    args.json,
+    true,
+    { removed: skills.removed, hooks: hooks.written, mcp: mcp.written, wiped },
+    undefined,
+    () =>
+      `removed ${skills.removed.length} skill/rule path(s)${wiped ? `\nwiped ${wiped}` : "\nOKF left in place (~/.mental)"}`,
+  );
+  return 0;
+}

package/bin/commands/where.mjs

@@ -0,0 +1,29 @@
+/**
+ * `mental where` — print the active OKF bundle. Agents call this first.
+ */
+import { resolveBundle } from "../lib/resolve.mjs";
+import { formatWhere, printResult } from "../lib/output.mjs";
+
+/**
+ * @param {{ json: boolean, dir?: string, cwd?: string, home?: string, env?: NodeJS.ProcessEnv }} args
+ * @param {{ stdout?: NodeJS.WritableStream, stderr?: NodeJS.WritableStream }} [io]
+ * @returns {number} exit code
+ */
+export function cmdWhere(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;
+  }
+
+  printResult(stdout, args.json, true, resolved.data, undefined, formatWhere);
+  return 0;
+}

package/bin/lib/args.mjs

@@ -0,0 +1,117 @@
+/**
+ * Shared CLI argument helpers and usage text.
+ */
+import { CMD, VERSION } from "./pkg.mjs";
+
+export function usage() {
+  return `${CMD} v${VERSION} — local-first OKF continuity
+
+Usage:
+  ${CMD}                       Heartbeat (TTY): resume, last outcome, git, residue, open decisions
+  ${CMD} heartbeat             Same pulse (agents: --json). Cheap reload — not a notes dump
+  ${CMD} where                 Active bundle (root, id, mode) — read-only
+  ${CMD} status                Git + latest Resume + residue + open decisions + notes
+  ${CMD} search <q>            Query notes/journal/decisions/attention (sqlite or scan)
+  ${CMD} list                  List concepts (--type --status --tag --kind)
+  ${CMD} show <path>           One file, relative to the bundle root (includes backlinks)
+  ${CMD} journal               Append today's journal section (--against PLAN.md)
+  ${CMD} attention             Create or update residue in the air (--kind --status resolved)
+  ${CMD} decide                Scaffold a decision file
+  ${CMD} note                  Scaffold a note
+  ${CMD} local                 Create ./.mental after ignore check (--import copies home, --move switches store)
+  ${CMD} remap                 List UUID bindings, or --to <id> / --from <id> for this clone
+  ${CMD} split                 New UUID for this clone (--copy keeps OKF files)
+  ${CMD} link                  Point this clone at --to <id>
+  ${CMD} install               Skill + rule + put ${CMD} on PATH (overrides previous)
+  ${CMD} uninstall             Remove installed skill/rule/hooks (OKF stays unless --delete-data DELETE)
+  ${CMD} hooks on|off          Optional session-start hooks (default off)
+  ${CMD} serve                 Optional MCP stdio (heartbeat/where/status/search/list/show/journal/attention/decide/note)
+  ${CMD} doctor                PATH, bindings, ignore, skill, index
+  ${CMD} reindex               Rebuild derived sqlite index from OKF files
+
+TTY: no args prints a one-shot heartbeat and exits. Named commands are one-shot.
+Non-TTY / agents: always pass --json. Do not grep OKF / YAML.
+
+Global flags:
+  --json             Machine-readable { ok, data } | { ok, error }
+  --dir <path>       Override resolve (same as MENTAL_DIR)
+  -h, --help         Show this help
+  -v, --version      Print version
+
+Privacy: default store is ~/.mental (never commit). Project ./.mental
+only after \`${CMD} local\`. Leftover ./.mental is normalized into
+~/.mental/projects/<uuid> and indexed (source is not deleted).
+Never store secrets.
+`;
+}
+
+/**
+ * Parse argv into a structured args object.
+ * Global flags may appear before or after the command.
+ *
+ * @param {string[]} argv
+ */
+export function parseArgv(argv) {
+  const args = {
+    command: null,
+    json: false,
+    dir: undefined,
+    help: false,
+    version: false,
+    /** @type {string[]} */
+    rest: [],
+    /** @type {Record<string, string | boolean>} */
+    flags: {},
+  };
+
+  const takesValue = new Set([
+    "--dir",
+    "--title",
+    "--body",
+    "--resume",
+    "--status",
+    "--slug",
+    "--description",
+    "--from",
+    "--to",
+    "--against",
+    "--kind",
+    "--path",
+    "--type",
+    "--tag",
+    "--confirm",
+  ]);
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "-h" || a === "--help") {
+      args.help = true;
+    } else if (a === "-v" || a === "--version") {
+      args.version = true;
+    } else if (a === "--json") {
+      args.json = true;
+    } else if (a === "--dir") {
+      const v = argv[++i];
+      if (v == null) throw new Error("--dir requires a path");
+      args.dir = v;
+    } else if (takesValue.has(a)) {
+      const v = argv[++i];
+      if (v == null) throw new Error(`${a} requires a value`);
+      args.flags[a.slice(2)] = v;
+    } else if (a.startsWith("--") && a.includes("=")) {
+      const eq = a.indexOf("=");
+      const key = a.slice(2, eq);
+      args.flags[key] = a.slice(eq + 1);
+      if (key === "dir") args.dir = a.slice(eq + 1);
+      if (key === "json") args.json = true;
+    } else if (a.startsWith("--")) {
+      args.flags[a.slice(2)] = true;
+    } else if (!args.command) {
+      args.command = a;
+    } else {
+      args.rest.push(a);
+    }
+  }
+
+  return args;
+}