@rohirik/openltm-core 2.8.0

package/src/cli/bin.ts

@@ -0,0 +1,97 @@
+#!/usr/bin/env bun
+/**
+ * cli/bin.ts — ltm CLI entrypoint.
+ *
+ * Usage:
+ *   bunx @rohirik/openltm-core                    # auto-detect agents
+ *   bunx @rohirik/openltm-core --claude           # Claude Code only
+ *   bunx @rohirik/openltm-core --opencode         # OpenCode only
+ *   bunx @rohirik/openltm-core --pi               # Pi only
+ *   bunx @rohirik/openltm-core --dry-run --claude # preview without writing
+ *
+ *   bunx @rohirik/openltm-core hook --name <hookName>  # lifecycle hook stub
+ *   bunx @rohirik/openltm-core mcp-serve               # MCP server (future)
+ */
+import { runInstallCli } from "./install.js";
+import { runHook } from "./hook.js";
+
+function printHelp(): void {
+  process.stdout.write(
+    [
+      "",
+      "  bunx @rohirik/openltm-core [options]",
+      "",
+      "  Options:",
+      "    --claude        Install into Claude Code",
+      "    --opencode      Install into OpenCode",
+      "    --pi            Install into Pi",
+      "    --dry-run       Preview without writing files",
+      "    --help, -h      Show this help",
+      "",
+      "  Sub-commands:",
+      "    hook --name <event>   Lifecycle hook stub (for Claude Code hook wiring)",
+      "    mcp-serve             Start the LTM MCP server",
+      "",
+      "  If no target flags are given, agents are auto-detected.",
+      "",
+    ].join("\n"),
+  );
+}
+
+async function main(): Promise<void> {
+  const argv = process.argv.slice(2);
+
+  if (argv[0] === "--help" || argv[0] === "-h") {
+    printHelp();
+    process.exit(0);
+  }
+
+  // Sub-command: hook
+  if (argv[0] === "hook") {
+    const nameIdx = argv.indexOf("--name");
+    const hookName = nameIdx !== -1 ? (argv[nameIdx + 1] ?? "") : "";
+    if (!hookName) {
+      process.stderr.write("  ltm hook: missing --name argument\n");
+      process.exit(1);
+    }
+    runHook(hookName);
+    return;
+  }
+
+  // Sub-command: mcp-serve (stub — full implementation deferred)
+  if (argv[0] === "mcp-serve") {
+    process.stderr.write(
+      "  ltm mcp-serve: not yet implemented — install the Claude Code plugin for MCP server support\n",
+    );
+    process.exit(0);
+  }
+
+  // Parse installer flags
+  let claude = false;
+  let opencode = false;
+  let pi = false;
+  let dryRun = false;
+
+  for (const arg of argv) {
+    if (arg === "--claude") claude = true;
+    else if (arg === "--opencode") opencode = true;
+    else if (arg === "--pi") pi = true;
+    else if (arg === "--dry-run") dryRun = true;
+    else if (arg === "--help" || arg === "-h") {
+      printHelp();
+      process.exit(0);
+    }
+  }
+
+  const result = await runInstallCli({
+    targets: { claude, opencode, pi },
+    dryRun,
+  });
+
+  process.exit(result.exitCode);
+}
+
+main().catch((err: unknown) => {
+  process.stderr.write(`\n  ltm fatal: ${String(err)}\n\n`);
+  process.exit(1);
+});

package/src/cli/claude.ts

@@ -0,0 +1,124 @@
+/**
+ * cli/claude.ts — Installer for Claude Code.
+ *
+ * Writes (or patches) ~/.claude/settings.json to add the LTM MCP server
+ * entry and three lifecycle hooks. Idempotent — safe to run multiple times.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { join, dirname } from "path";
+import os from "os";
+import { mergeMcpEntry, wireHooks } from "./_shared.js";
+import type { ClaudeSettings, McpServerEntry } from "./_shared.js";
+import type { InstallResult } from "./types.js";
+
+// ── Constants ─────────────────────────────────────────────────────────────────
+
+const MCP_NAME = "openltm";
+const MCP_ENTRY: McpServerEntry = {
+  command: "bunx",
+  args: ["@rohirik/openltm-core", "mcp-serve"],
+  env: { LTM_DB_PATH: "~/.claude/plugins/data/OpenLtm-openltm/openltm.db" },
+};
+
+const HOOKS: Array<{ event: string; args: string[] }> = [
+  {
+    event: "SessionStart",
+    args: ["@rohirik/openltm-core", "hook", "--name", "SessionStart"],
+  },
+  {
+    event: "PreCompact",
+    args: ["@rohirik/openltm-core", "hook", "--name", "PreCompact"],
+  },
+  {
+    event: "PostEditCheck",
+    args: ["@rohirik/openltm-core", "hook", "--name", "PostEditCheck"],
+  },
+];
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function settingsPath(homedir: string): string {
+  return join(homedir, ".claude", "settings.json");
+}
+
+function readSettings(path: string): ClaudeSettings {
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, "utf8")) as ClaudeSettings;
+  } catch {
+    // Malformed JSON → start fresh
+    return {};
+  }
+}
+
+/**
+ * Check if the settings already have the LTM MCP entry AND all 3 hooks wired.
+ * Used for early-exit idempotency.
+ */
+function isAlreadyInstalled(settings: ClaudeSettings): boolean {
+  // Check MCP entry
+  const entry = settings.mcpServers?.[MCP_NAME];
+  if (!entry || entry.command !== MCP_ENTRY.command) return false;
+
+  // Check each hook
+  for (const hook of HOOKS) {
+    const hookList = (settings.hooks as Record<string, unknown> | undefined)?.[hook.event];
+    if (!Array.isArray(hookList)) return false;
+    const present = hookList.some(
+      (h): boolean =>
+        typeof h === "object" &&
+        h !== null &&
+        (h as { command?: string }).command === "bunx" &&
+        Array.isArray((h as { args?: unknown[] }).args) &&
+        (h as { args: unknown[] }).args[0] === hook.args[0],
+    );
+    if (!present) return false;
+  }
+  return true;
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+/**
+ * installClaude — write or patch ~/.claude/settings.json.
+ *
+ * @param opts.homedir - Override home directory (useful for tests).
+ * @param opts.dryRun  - Compute result without writing any files.
+ * @returns InstallResult describing what happened.
+ */
+export async function installClaude(opts: {
+  homedir?: string;
+  dryRun?: boolean;
+}): Promise<InstallResult> {
+  const homedir = opts.homedir ?? os.homedir();
+  const dryRun = opts.dryRun ?? false;
+  const path = settingsPath(homedir);
+
+  const original = readSettings(path);
+
+  if (isAlreadyInstalled(original)) {
+    return { target: "claude", status: "skipped", detail: "already configured" };
+  }
+
+  // Apply MCP entry
+  let settings = mergeMcpEntry(original, MCP_NAME, MCP_ENTRY);
+
+  // Apply all 3 hooks
+  for (const hook of HOOKS) {
+    settings = wireHooks(settings, hook.event, "bunx", hook.args);
+  }
+
+  if (!dryRun) {
+    const dir = dirname(path);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(path, JSON.stringify(settings, null, 2) + "\n", "utf8");
+  }
+
+  return {
+    target: "claude",
+    status: "installed",
+    detail: dryRun ? "dry-run — no files written" : path,
+  };
+}

package/src/cli/detect.ts

@@ -0,0 +1,55 @@
+/**
+ * cli/detect.ts — Agent detection for the LTM installer.
+ *
+ * Probes the filesystem for known AI coding agent installations so the
+ * installer can auto-select targets without requiring explicit --claude /
+ * --opencode / --pi flags.
+ *
+ * Pure function — accepts a homedir argument so tests can supply a tmp dir.
+ */
+import { existsSync } from "fs";
+import { join } from "path";
+import os from "os";
+import type { DetectResult } from "./types.js";
+
+/**
+ * Probe for an OpenCode config directory using the standard path resolution
+ * order: $XDG_CONFIG_HOME/opencode → ~/.config/opencode → (darwin only)
+ * ~/Library/Application Support/opencode.
+ */
+function probeOpenCode(homedir: string): boolean {
+  const xdg = process.env["XDG_CONFIG_HOME"];
+  if (xdg && existsSync(join(xdg, "opencode"))) return true;
+  if (existsSync(join(homedir, ".config", "opencode"))) return true;
+  if (process.platform === "darwin") {
+    if (existsSync(join(homedir, "Library", "Application Support", "opencode"))) return true;
+  }
+  return false;
+}
+
+/**
+ * Probe for a Pi config using the three known locations:
+ * ~/.pi/ | ~/pi.toml | ~/.pi/config.toml
+ */
+function probePi(homedir: string): boolean {
+  return (
+    existsSync(join(homedir, ".pi")) ||
+    existsSync(join(homedir, "pi.toml")) ||
+    existsSync(join(homedir, ".pi", "config.toml"))
+  );
+}
+
+/**
+ * detectAgents — inspect the filesystem to determine which AI coding agents
+ * are installed in the given home directory.
+ *
+ * @param homedir - Defaults to `os.homedir()`. Override in tests.
+ * @returns DetectResult with boolean flags for each supported agent.
+ */
+export function detectAgents(homedir: string = os.homedir()): DetectResult {
+  return {
+    claude: existsSync(join(homedir, ".claude")),
+    opencode: probeOpenCode(homedir),
+    pi: probePi(homedir),
+  };
+}

package/src/cli/hook.ts

@@ -0,0 +1,25 @@
+/**
+ * cli/hook.ts — Hook dispatcher stub.
+ *
+ * Full hook logic lives in the Claude Code plugin (hooks/src/).
+ * When invoked via `bunx @rohirik/openltm-core hook --name <hookName>`, this
+ * stub exits cleanly (exit 0) so Claude Code does not treat the absent hook
+ * runner as an error.
+ *
+ * A future phase can wire actual hook logic here once openltm-core ships the
+ * compiled hook handlers.
+ */
+
+/**
+ * runHook — stub dispatcher for LTM lifecycle hooks.
+ *
+ * @param name - Hook event name (e.g. "SessionStart", "PreCompact").
+ */
+export function runHook(name: string): void {
+  // Stub: full hook logic requires the Claude Code plugin.
+  // Exit 0 so Claude Code does not break when the hook is registered.
+  process.stderr.write(
+    `LTM: hook '${name}' via bunx not yet supported — install the Claude Code plugin for full hook support\n`,
+  );
+  process.exit(0);
+}

package/src/cli/index.ts

@@ -0,0 +1,22 @@
+/**
+ * cli/index.ts — Public barrel for the @rohirik/openltm-core/cli sub-path export.
+ *
+ * Consumers that want to build on top of the LTM CLI primitives (e.g. a
+ * wrapper script or an e2e test harness) import from here instead of reaching
+ * into internal modules.
+ */
+export { runInstall, runInstallCli } from "./install.js";
+export type { CliRunOpts, CliRunResult } from "./install.js";
+export type {
+  CliInstallOptions,
+  CliInstallResult,
+  InstallStep,
+  InstallTargetId,
+  InstallResult,
+  DetectResult,
+} from "./types.js";
+export { InstallTarget } from "./types.js";
+export { detectAgents } from "./detect.js";
+export { installClaude } from "./claude.js";
+export { installOpenCode } from "./opencode.js";
+export { installPi } from "./pi.js";

package/src/cli/install.ts

@@ -0,0 +1,185 @@
+/**
+ * cli/install.ts — Install orchestrator.
+ *
+ * Coordinates detection → installation → UX rendering across all supported
+ * target agents (Claude Code, OpenCode, Pi). Uses @clack/prompts for output.
+ *
+ * The module exports two surfaces:
+ *   - `runInstall(opts)` — programmatic API (used by bin.ts and tests)
+ *   - Legacy `CliInstallResult` shape preserved for backward compatibility with
+ *     existing tests in src/__tests__/cli.test.ts
+ */
+import * as clack from "@clack/prompts";
+import { detectAgents } from "./detect.js";
+import { installClaude } from "./claude.js";
+import { installOpenCode } from "./opencode.js";
+import { installPi } from "./pi.js";
+import type { CliInstallOptions, CliInstallResult, InstallStep, InstallResult } from "./types.js";
+import { InstallTarget } from "./types.js";
+
+// ── Known targets set (legacy validation) ────────────────────────────────────
+
+const KNOWN_TARGETS = new Set<string>(Object.values(InstallTarget));
+
+// ── Legacy runInstall (backward compatible) ───────────────────────────────────
+
+/**
+ * runInstall — legacy programmatic API.
+ *
+ * Retained for backward compatibility with P6-0 tests in cli.test.ts.
+ * New code should use `runInstallCli` or call individual installers directly.
+ */
+export async function runInstall(opts: CliInstallOptions): Promise<CliInstallResult> {
+  const { target, dryRun = false, nonInteractive = false } = opts;
+  const steps: InstallStep[] = [];
+
+  if (!KNOWN_TARGETS.has(target)) {
+    return {
+      success: false,
+      message: `Unknown target: "${target}". Valid targets: ${[...KNOWN_TARGETS].join(", ")}`,
+      steps,
+    };
+  }
+
+  steps.push({ label: `Validate target: ${target}`, status: "done" });
+  steps.push({
+    label: "Detect plugin data directory",
+    status: dryRun ? "skipped" : "done",
+    detail: dryRun ? "dry-run mode — no filesystem writes" : opts.pluginDataDir ?? "(auto-detected)",
+  });
+  steps.push({
+    label: `Wire ${target} configuration`,
+    status: dryRun ? "skipped" : "done",
+    detail: dryRun ? "dry-run: would patch host config file" : undefined,
+  });
+
+  if (!nonInteractive && !dryRun) {
+    steps.push({
+      label: "Run onboarding wizard",
+      status: "skipped",
+      detail: "interactive mode — wizard deferred to ltm onboard",
+    });
+  }
+
+  const mode = dryRun ? " (dry-run)" : "";
+  return {
+    success: true,
+    message: `LTM install for "${target}" completed${mode}. Run "ltm onboard" to finish setup.`,
+    steps,
+  };
+}
+
+// ── CLI orchestration ─────────────────────────────────────────────────────────
+
+export interface CliRunOpts {
+  /** Explicit target flags from the command line. */
+  targets: {
+    claude: boolean;
+    opencode: boolean;
+    pi: boolean;
+  };
+  dryRun: boolean;
+  homedir?: string;
+  /** When true, suppress @clack output (used in tests). */
+  silent?: boolean;
+}
+
+export interface CliRunResult {
+  exitCode: number;
+  results: InstallResult[];
+}
+
+/**
+ * runInstallCli — main orchestrator for the `bunx @rohirik/openltm-core` flow.
+ *
+ * 1. If no target flags → call detectAgents()
+ * 2. If nothing found and no flags → exit 2
+ * 3. For each target call the installer and render @clack output
+ */
+export async function runInstallCli(opts: CliRunOpts): Promise<CliRunResult> {
+  const { dryRun, homedir, silent = false } = opts;
+
+  // Resolve targets
+  let targets = { ...opts.targets };
+  const hasExplicit = targets.claude || targets.opencode || targets.pi;
+
+  if (!hasExplicit) {
+    const detected = detectAgents(homedir);
+    targets = detected;
+  }
+
+  const anyTarget = targets.claude || targets.opencode || targets.pi;
+  if (!anyTarget) {
+    if (!silent) {
+      clack.log.warn(
+        "No supported agents found. Use --claude, --opencode, or --pi to install manually.",
+      );
+    }
+    return { exitCode: 2, results: [] };
+  }
+
+  if (!silent) {
+    clack.intro("LTM Installer");
+  }
+
+  const results: InstallResult[] = [];
+
+  // Claude
+  if (targets.claude) {
+    const s = silent ? null : clack.spinner();
+    if (s) s.start("Installing into Claude Code…");
+    const r = await installClaude({ homedir, dryRun });
+    results.push(r);
+    if (s) {
+      if (r.status === "installed") {
+        s.stop(`Claude Code: installed${dryRun ? " (dry-run)" : ""}`);
+      } else if (r.status === "skipped") {
+        s.stop("Claude Code: already configured (skipped)");
+      } else {
+        s.stop(`Claude Code: error — ${r.detail ?? "unknown error"}`);
+      }
+    }
+  }
+
+  // OpenCode
+  if (targets.opencode) {
+    const s = silent ? null : clack.spinner();
+    if (s) s.start("Installing into OpenCode…");
+    const r = await installOpenCode({ homedir, dryRun });
+    results.push(r);
+    if (s) {
+      if (r.status === "installed") {
+        s.stop(`OpenCode: installed${dryRun ? " (dry-run)" : ""}`);
+      } else if (r.status === "skipped") {
+        s.stop("OpenCode: already configured (skipped)");
+      } else {
+        s.stop(`OpenCode: error — ${r.detail ?? "unknown error"}`);
+      }
+    }
+  }
+
+  // Pi
+  if (targets.pi) {
+    const s = silent ? null : clack.spinner();
+    if (s) s.start("Installing into Pi…");
+    const r = await installPi({ dryRun });
+    results.push(r);
+    if (s) {
+      if (r.status === "installed") {
+        s.stop(`Pi: installed${dryRun ? " (dry-run)" : ""}`);
+      } else if (r.status === "skipped") {
+        s.stop("Pi: already configured (skipped)");
+      } else {
+        s.stop(`Pi: error — ${r.detail ?? "unknown error"}`);
+      }
+    }
+  }
+
+  const hasErrors = results.some((r) => r.status === "error");
+
+  if (!silent) {
+    clack.outro("Done. Shared DB: ~/.claude/plugins/data/OpenLtm-openltm/openltm.db");
+  }
+
+  return { exitCode: hasErrors ? 1 : 0, results };
+}