@xyrlan/mnemo 0.13.0

package/README.md

@@ -0,0 +1,15 @@
+# @xyrlan/mnemo (npm wrapper)
+
+One-command installer for [mnemo](https://github.com/xyrlan/mnemo).
+
+```
+npx @xyrlan/mnemo install              # global, default
+npx @xyrlan/mnemo install --project    # only in <cwd>
+npx @xyrlan/mnemo uninstall
+```
+
+This package is a thin Node bootstrap. The actual mnemo runtime is a Python
+package installed automatically via `uv`, `pipx`, or `pip --user` (whichever
+is available). Python 3.8+ is required.
+
+See the main project README for usage details.

package/bin/mnemo.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+"use strict";
+
+const { runInstall } = require("../lib/runInstall");
+const { runUninstall } = require("../lib/runUninstall");
+
+function printHelp() {
+  process.stdout.write([
+    "Usage: npx @xyrlan/mnemo <command> [flags]",
+    "",
+    "Commands:",
+    "  install      Install mnemo (Python) + register hooks/slash commands",
+    "  uninstall    Remove mnemo from this scope (vault preserved)",
+    "  help         Show this message",
+    "",
+    "Install flags:",
+    "  --global             Install globally (default)",
+    "  --project, --local   Install only in the current directory",
+    "  --vault-root <path>  Override vault location",
+    "  --upgrade            Force upgrade if already installed",
+    "  --yes, -y            Non-interactive (default: global)",
+    "  --quiet              Suppress informational output",
+    "",
+    "Uninstall flags:",
+    "  --scope global|project|both",
+    "  --yes, -y",
+    "  --quiet",
+    "",
+  ].join("\n"));
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const cmd = argv[0];
+  const rest = argv.slice(1);
+  switch (cmd) {
+    case "install":
+      process.exit(await runInstall(rest));
+    case "uninstall":
+      process.exit(await runUninstall(rest));
+    case undefined:
+    case "help":
+    case "--help":
+    case "-h":
+      printHelp();
+      process.exit(0);
+    default:
+      process.stderr.write(`unknown command: ${cmd}\n`);
+      printHelp();
+      process.exit(2);
+  }
+}
+
+main().catch((err) => {
+  process.stderr.write(`fatal: ${err && err.message ? err.message : err}\n`);
+  process.exit(1);
+});

package/lib/bootstrap.js

@@ -0,0 +1,70 @@
+"use strict";
+
+const { execSync, spawnSync } = require("node:child_process");
+const { probe } = require("./detect");
+
+
+const PIN_SPEC = "mnemo-claude>=0.12,<0.13";
+
+
+function buildInstallCmd(installer, spec = PIN_SPEC) {
+  switch (installer) {
+    case "uv":       return `uv tool install '${spec}'`;
+    case "pipx":     return `pipx install '${spec}'`;
+    case "pip-user": return `python3 -m pip install --user '${spec}'`;
+    default: throw new Error(`unknown installer: ${installer}`);
+  }
+}
+
+
+function buildUpgradeCmd(installer) {
+  switch (installer) {
+    case "uv":       return "uv tool upgrade mnemo-claude";
+    case "pipx":     return "pipx upgrade mnemo-claude";
+    case "pip-user": return "python3 -m pip install --user --upgrade mnemo-claude";
+    default: throw new Error(`unknown installer: ${installer}`);
+  }
+}
+
+
+function isAlreadyInstalled(probeFn = probe) {
+  return probeFn("mnemo --version");
+}
+
+
+function runShell(cmd, { quiet = false } = {}) {
+  const result = spawnSync("sh", ["-c", cmd], { stdio: quiet ? "ignore" : "inherit" });
+  return result.status === null ? 1 : result.status;
+}
+
+
+function verifyOnPath() {
+  try {
+    execSync("mnemo --version", { stdio: "ignore" });
+    return true;
+  } catch (_e) {
+    return false;
+  }
+}
+
+
+function pathFixHint(installer) {
+  if (installer === "pipx") return "Run `pipx ensurepath` and reopen your shell.";
+  if (installer === "uv")   return "Run `uv tool update-shell` and reopen your shell.";
+  if (installer === "pip-user") {
+    if (process.platform === "win32") return "Add %APPDATA%\\Python\\Scripts to PATH.";
+    return "Add ~/.local/bin to PATH (e.g. via your shell profile).";
+  }
+  return "Re-open your shell to refresh PATH.";
+}
+
+
+module.exports = {
+  PIN_SPEC,
+  buildInstallCmd,
+  buildUpgradeCmd,
+  isAlreadyInstalled,
+  runShell,
+  verifyOnPath,
+  pathFixHint,
+};

package/lib/detect.js

@@ -0,0 +1,67 @@
+"use strict";
+
+const { execSync } = require("node:child_process");
+
+
+function parsePythonVersion(stdout) {
+  const m = /Python\s+(\d+)\.(\d+)(?:\.(\d+))?/.exec(stdout || "");
+  if (!m) return null;
+  return {
+    major: parseInt(m[1], 10),
+    minor: parseInt(m[2], 10),
+    patch: m[3] ? parseInt(m[3], 10) : 0,
+  };
+}
+
+
+function probe(cmd) {
+  try {
+    execSync(`${cmd} --version`, { stdio: "ignore" });
+    return true;
+  } catch (_e) {
+    return false;
+  }
+}
+
+
+function pickInstaller(probeFn = probe) {
+  if (probeFn("uv")) return "uv";
+  if (probeFn("pipx")) return "pipx";
+  if (probeFn("pip") || probeFn("pip3") || probeFn("python3 -m pip")) return "pip-user";
+  return null;
+}
+
+
+function detectPython() {
+  for (const cmd of ["python3", "python"]) {
+    try {
+      const out = execSync(`${cmd} --version`, { encoding: "utf8" });
+      const v = parsePythonVersion(out);
+      if (v && (v.major > 3 || (v.major === 3 && v.minor >= 8))) {
+        return { version: v, command: cmd };
+      }
+    } catch (_e) {
+      continue;
+    }
+  }
+  return null;
+}
+
+
+function isPep668(stderr) {
+  return /externally-managed-environment/i.test(stderr || "");
+}
+
+
+function pep668InstallHint() {
+  if (process.platform === "darwin") return "brew install pipx";
+  try {
+    const osr = require("node:fs").readFileSync("/etc/os-release", "utf8");
+    if (/ID=(?:debian|ubuntu)/i.test(osr)) return "sudo apt install pipx";
+    if (/ID=(?:fedora|rhel|centos)/i.test(osr)) return "sudo dnf install pipx";
+  } catch (_e) { /* ignore */ }
+  return "install pipx via your system package manager";
+}
+
+
+module.exports = { parsePythonVersion, probe, pickInstaller, detectPython, isPep668, pep668InstallHint };

package/lib/messages.js

@@ -0,0 +1,17 @@
+"use strict";
+
+const C = {
+  green:  "\x1b[32m",
+  yellow: "\x1b[33m",
+  red:    "\x1b[31m",
+  dim:    "\x1b[2m",
+  reset:  "\x1b[0m",
+};
+
+function ok(msg)    { process.stdout.write(`${C.green}✓${C.reset} ${msg}\n`); }
+function warn(msg)  { process.stdout.write(`${C.yellow}⚠${C.reset} ${msg}\n`); }
+function err(msg)   { process.stderr.write(`${C.red}✗${C.reset} ${msg}\n`); }
+function info(msg)  { process.stdout.write(`${C.dim}↻${C.reset} ${msg}\n`); }
+function plain(msg) { process.stdout.write(`${msg}\n`); }
+
+module.exports = { ok, warn, err, info, plain };

package/lib/prompt.js

@@ -0,0 +1,26 @@
+"use strict";
+
+const readline = require("node:readline");
+
+
+function promptScope({ stdin = process.stdin, stdout = process.stdout } = {}) {
+  const rl = readline.createInterface({ input: stdin, output: stdout, terminal: false });
+  const question = [
+    "",
+    "Where should mnemo install hooks?",
+    "  [1] Global  — every Claude Code session (recommended)",
+    "  [2] Project — only in this directory",
+    "choice [1]: ",
+  ].join("\n");
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      const trimmed = (answer || "").trim();
+      if (trimmed === "2") return resolve("project");
+      return resolve("global");
+    });
+  });
+}
+
+
+module.exports = { promptScope };

package/lib/runInstall.js

@@ -0,0 +1,92 @@
+"use strict";
+
+const { detectPython, pickInstaller, pep668InstallHint } = require("./detect");
+const {
+  PIN_SPEC,
+  buildInstallCmd,
+  buildUpgradeCmd,
+  isAlreadyInstalled,
+  runShell,
+  verifyOnPath,
+  pathFixHint,
+} = require("./bootstrap");
+const { promptScope } = require("./prompt");
+const { buildInitArgs, runMnemo } = require("./runMnemo");
+const m = require("./messages");
+
+
+function parseFlags(argv) {
+  const flags = { scope: null, vaultRoot: null, upgrade: false, yes: false, quiet: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--global")              flags.scope = "global";
+    else if (a === "--project" || a === "--local") flags.scope = "project";
+    else if (a === "--upgrade")        flags.upgrade = true;
+    else if (a === "--yes" || a === "-y") flags.yes = true;
+    else if (a === "--quiet")          flags.quiet = true;
+    else if (a === "--vault-root")     { flags.vaultRoot = argv[++i]; }
+  }
+  return flags;
+}
+
+
+async function runInstall(argv) {
+  const flags = parseFlags(argv);
+
+  const py = detectPython();
+  if (!py) {
+    m.err("Python 3.8+ not found.");
+    m.plain("  → Install Python 3.8 or newer (https://www.python.org/downloads/) and retry.");
+    return 1;
+  }
+  if (!flags.quiet) m.ok(`Python ${py.version.major}.${py.version.minor} detected`);
+
+  const installer = pickInstaller();
+  if (!installer) {
+    m.err("No Python installer (uv, pipx, or pip) found on PATH.");
+    m.plain(`  → ${pep668InstallHint()}`);
+    return 1;
+  }
+  if (!flags.quiet) m.ok(`installer: ${installer}`);
+
+  const installed = isAlreadyInstalled();
+  if (installed && !flags.upgrade) {
+    if (!flags.quiet) m.ok("mnemo already installed. Skipping installer step. (use --upgrade to force)");
+  } else {
+    const cmd = installed ? buildUpgradeCmd(installer) : buildInstallCmd(installer, PIN_SPEC);
+    if (!flags.quiet) m.info(`Running: ${cmd}`);
+    const status = runShell(cmd, { quiet: flags.quiet });
+    if (status !== 0) {
+      m.err(`Installer command failed (exit ${status}).`);
+      return status;
+    }
+    if (!verifyOnPath()) {
+      m.err("`mnemo --version` not reachable on PATH after install.");
+      m.plain(`  → ${pathFixHint(installer)}`);
+      return 2;
+    }
+    if (!flags.quiet) m.ok("mnemo on PATH");
+  }
+
+  let scope = flags.scope;
+  if (!scope) {
+    if (flags.yes) scope = "global";
+    else scope = await promptScope();
+  }
+
+  const args = buildInitArgs({ scope, vaultRoot: flags.vaultRoot, quiet: flags.quiet, yes: true });
+  const status = runMnemo(args, { quiet: flags.quiet });
+  if (status !== 0) return status;
+
+  if (!flags.quiet) {
+    if (scope === "project") {
+      m.plain(`\nDone. Launch \`claude\` in ${process.cwd()} to activate the local hooks.`);
+    } else {
+      m.plain("\nDone. Open Claude Code anywhere; mnemo is active.");
+    }
+  }
+  return 0;
+}
+
+
+module.exports = { runInstall, parseFlags };

package/lib/runMnemo.js

@@ -0,0 +1,31 @@
+"use strict";
+
+const { spawnSync } = require("node:child_process");
+
+
+function buildInitArgs({ scope, vaultRoot, quiet, yes = true }) {
+  const args = ["init"];
+  if (scope === "project") args.push("--project");
+  if (yes) args.push("--yes");
+  if (quiet) args.push("--quiet");
+  if (vaultRoot) { args.push("--vault-root", vaultRoot); }
+  return args;
+}
+
+
+function buildUninstallArgs({ scope, quiet, yes = true }) {
+  const args = ["uninstall"];
+  if (scope === "project") args.push("--project");
+  if (yes) args.push("--yes");
+  if (quiet) args.push("--quiet");
+  return args;
+}
+
+
+function runMnemo(args, { quiet = false } = {}) {
+  const result = spawnSync("mnemo", args, { stdio: quiet ? "ignore" : "inherit" });
+  return result.status === null ? 1 : result.status;
+}
+
+
+module.exports = { buildInitArgs, buildUninstallArgs, runMnemo };

package/lib/runUninstall.js

@@ -0,0 +1,127 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const os = require("node:os");
+
+const { pickInstaller } = require("./detect");
+const { runShell } = require("./bootstrap");
+const { buildUninstallArgs, runMnemo } = require("./runMnemo");
+const m = require("./messages");
+
+
+function parseUninstallFlags(argv) {
+  const f = { scope: null, yes: false, quiet: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--scope") f.scope = argv[++i];
+    else if (a === "--yes" || a === "-y") f.yes = true;
+    else if (a === "--quiet") f.quiet = true;
+  }
+  return f;
+}
+
+
+function _hasMnemoInSettings(settingsPath) {
+  if (!fs.existsSync(settingsPath)) return false;
+  try {
+    const data = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+    const hooks = (data && data.hooks) || {};
+    for (const ev of Object.keys(hooks)) {
+      const entries = hooks[ev] || [];
+      for (const e of entries) {
+        for (const h of (e.hooks || [])) {
+          if (typeof h.command === "string" && h.command.includes("mnemo.hooks.")) return true;
+        }
+      }
+    }
+    return false;
+  } catch (_e) {
+    return false;
+  }
+}
+
+
+function detectScopes() {
+  return {
+    project: _hasMnemoInSettings(path.join(process.cwd(), ".claude", "settings.json")),
+    global:  _hasMnemoInSettings(path.join(os.homedir(), ".claude", "settings.json")),
+  };
+}
+
+
+function resolveUninstallScope(flag, present, nonInteractive) {
+  if (flag) {
+    if (!["project", "global", "both"].includes(flag)) {
+      throw new Error(`invalid --scope: ${flag}`);
+    }
+    return flag;
+  }
+  const both = present.project && present.global;
+  if (both && nonInteractive) {
+    throw new Error("both project and global installs detected; pass --scope explicitly");
+  }
+  if (present.project && !present.global) return "project";
+  if (present.global && !present.project) return "global";
+  return null;
+}
+
+
+async function _promptUninstallScope() {
+  const readline = require("node:readline");
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const question = [
+    "",
+    "Both project and global mnemo installs detected.",
+    "  [1] project (this directory)",
+    "  [2] global",
+    "  [3] both",
+    "choice [1]: ",
+  ].join("\n");
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      const t = (answer || "").trim();
+      if (t === "2") return resolve("global");
+      if (t === "3") return resolve("both");
+      return resolve("project");
+    });
+  });
+}
+
+
+async function runUninstall(argv) {
+  const flags = parseUninstallFlags(argv);
+  const present = detectScopes();
+  if (!present.project && !present.global) {
+    m.warn("No mnemo install detected (no hooks in project or global settings).");
+    return 0;
+  }
+  let scope;
+  try {
+    scope = resolveUninstallScope(flags.scope, present, flags.yes) || await _promptUninstallScope();
+  } catch (e) {
+    m.err(e.message);
+    return 2;
+  }
+
+  const scopes = scope === "both" ? ["project", "global"] : [scope];
+  for (const s of scopes) {
+    const status = runMnemo(buildUninstallArgs({ scope: s, quiet: flags.quiet, yes: true }), { quiet: flags.quiet });
+    if (status !== 0) return status;
+  }
+
+  const installer = pickInstaller();
+  if (installer) {
+    const cmd = installer === "uv" ? "uv tool uninstall mnemo-claude"
+              : installer === "pipx" ? "pipx uninstall mnemo-claude"
+              : "python3 -m pip uninstall -y --user mnemo-claude";
+    if (!flags.quiet) m.info(`Running: ${cmd}`);
+    runShell(cmd, { quiet: flags.quiet });
+  }
+  if (!flags.quiet) m.plain("\nDone. Vault preserved.");
+  return 0;
+}
+
+
+module.exports = { runUninstall, parseUninstallFlags, resolveUninstallScope, detectScopes };

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@xyrlan/mnemo",
+  "version": "0.13.0",
+  "description": "One-command installer for mnemo (the Obsidian that populates itself).",
+  "bin": {
+    "mnemo": "bin/mnemo.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xyrlan/mnemo.git"
+  },
+  "homepage": "https://github.com/xyrlan/mnemo",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test test/"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "README.md"
+  ]
+}