@agfpd/iapeer-memory 0.1.1

package/src/commands/render.ts

@@ -0,0 +1,199 @@
+/**
+ * `iapeer-memory render` — explicit one-shot rendering of the package's
+ * artifacts. memoryd renders these continuously at runtime; `render` is the
+ * manual/scripted path (init, repair, debugging, tests).
+ *
+ *   render index    --agent NAME [--out FILE] [--projects-root DIR]
+ *   render fragment --agent NAME --peer-cwd DIR [--index FILE]
+ *   render doctrine --role NAME --peer-cwd DIR --template FILE
+ *   render guide    --source FILE --target IAPEER_DIR
+ *
+ * `guide` writes the HOST-WIDE fragment — it reaches EVERY peer of the
+ * fleet on their next wakes, so the target directory is always EXPLICIT
+ * (no default to the production ~/.iapeer; the fleet rollout is a
+ * separately sanctioned release step).
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  configFromEnv,
+  regenerateVaultIndex,
+  renderDoctrine,
+  renderPeerFragment,
+  resolveAgentName,
+  writeHostWideGuideFragment,
+  type FragmentEnv,
+} from "@agfpd/iapeer-memory-core";
+import { authorIndexPath, memoryPaths } from "../paths.js";
+import { packageVersion } from "../version.js";
+
+class UsageError extends Error {}
+
+function parseFlags(argv: string[], spec: Record<string, "value" | "bool">): {
+  flags: Record<string, string | boolean>;
+  rest: string[];
+} {
+  const flags: Record<string, string | boolean> = {};
+  const rest: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith("--")) {
+      rest.push(a);
+      continue;
+    }
+    const kind = spec[a];
+    if (!kind) throw new UsageError(`unknown flag: ${a}`);
+    if (kind === "bool") {
+      flags[a] = true;
+    } else {
+      const v = argv[++i];
+      if (v === undefined) throw new UsageError(`${a} requires a value`);
+      flags[a] = v;
+    }
+  }
+  return { flags, rest };
+}
+
+function renderIndex(argv: string[]): number {
+  const { flags } = parseFlags(argv, {
+    "--agent": "value",
+    "--out": "value",
+    "--projects-root": "value",
+  });
+  const agent = resolveAgentName((flags["--agent"] as string) ?? null);
+  if (!agent) throw new UsageError("no agent (pass --agent or set PEER_PERSONALITY)");
+
+  const config = configFromEnv();
+  const paths = memoryPaths();
+  const outFile = (flags["--out"] as string) || authorIndexPath(paths, agent);
+  const projectsRoot =
+    (flags["--projects-root"] as string) ||
+    process.env.IAPEER_MEMORY_PROJECTS_ROOT ||
+    path.join(process.env.HOME || os.homedir(), "Projects");
+
+  fs.mkdirSync(path.dirname(outFile), { recursive: true });
+  const result = regenerateVaultIndex({
+    vault: config.vaultPath,
+    agent,
+    outFile,
+    ctx: { taxonomy: config.taxonomy, ranking: config.ranking },
+    projectsRoot,
+  });
+  console.log(
+    `render index: ${outFile} (${result.total} notes` +
+      `${result.truncated ? ", truncated" : ""}` +
+      `${result.skipped.length ? `, ${result.skipped.length} skipped` : ""})`,
+  );
+  return 0;
+}
+
+function renderFragment(argv: string[]): number {
+  const { flags } = parseFlags(argv, {
+    "--agent": "value",
+    "--peer-cwd": "value",
+    "--index": "value",
+  });
+  const agent = resolveAgentName((flags["--agent"] as string) ?? null);
+  if (!agent) throw new UsageError("no agent (pass --agent or set PEER_PERSONALITY)");
+  const peerCwd = flags["--peer-cwd"] as string | undefined;
+  if (!peerCwd) throw new UsageError("--peer-cwd is required");
+
+  const config = configFromEnv();
+  const paths = memoryPaths();
+  const indexAgent = process.env.IAPEER_MEMORY_INDEX_AGENT || "index";
+  const indexFile = (flags["--index"] as string) || authorIndexPath(paths, agent);
+  if (!fs.existsSync(indexFile)) {
+    console.error(
+      `render fragment: author index not found at ${indexFile} — ` +
+        `run \`iapeer-memory render index --agent ${agent}\` first ` +
+        `(the fragment would silently miss its index layer)`,
+    );
+    return 1;
+  }
+
+  const env: FragmentEnv = {
+    agent,
+    indexAgent,
+    paths: {
+      vault: config.vaultPath,
+      db: config.index.dbPath,
+      config: paths.configFile,
+      state: paths.stateDir,
+      cache: paths.cacheDir,
+      logs: paths.logsDir,
+    },
+    authorIndexPath: indexFile,
+    tagsDictionaryPath: agent === indexAgent ? paths.tagsMirrorPath : undefined,
+  };
+  const written = renderPeerFragment({ peerCwd, env });
+  console.log(`render fragment: ${written}`);
+  return 0;
+}
+
+function renderDoctrineCmd(argv: string[]): number {
+  const { flags } = parseFlags(argv, {
+    "--role": "value",
+    "--peer-cwd": "value",
+    "--template": "value",
+  });
+  const role = flags["--role"] as string | undefined;
+  const peerCwd = flags["--peer-cwd"] as string | undefined;
+  const template = flags["--template"] as string | undefined;
+  if (!role || !peerCwd || !template) {
+    throw new UsageError("--role, --peer-cwd and --template are all required");
+  }
+  const outcome = renderDoctrine({
+    templatePath: template,
+    peerCwd,
+    version: packageVersion(),
+  });
+  console.log(`render doctrine [${role}]: ${outcome.action} ${outcome.target}`);
+  return outcome.action === "missing-template" ? 1 : 0;
+}
+
+function renderGuide(argv: string[]): number {
+  const { flags } = parseFlags(argv, {
+    "--source": "value",
+    "--target": "value",
+  });
+  const source = flags["--source"] as string | undefined;
+  const target = flags["--target"] as string | undefined;
+  if (!source || !target) {
+    throw new UsageError(
+      "--source and --target are both required (the host-wide guide reaches " +
+        "the whole fleet — the target is never implicit)",
+    );
+  }
+  const text = fs.readFileSync(source, "utf-8");
+  const written = writeHostWideGuideFragment(target, text);
+  console.log(`render guide: ${written}`);
+  return 0;
+}
+
+export function cmdRender(argv: string[]): number {
+  const [sub, ...rest] = argv;
+  try {
+    switch (sub) {
+      case "index":
+        return renderIndex(rest);
+      case "fragment":
+        return renderFragment(rest);
+      case "doctrine":
+        return renderDoctrineCmd(rest);
+      case "guide":
+        return renderGuide(rest);
+      default:
+        throw new UsageError(
+          `unknown render target: ${sub ?? "(none)"} (expected index | fragment | doctrine | guide)`,
+        );
+    }
+  } catch (err) {
+    if (err instanceof UsageError) {
+      console.error(`iapeer-memory render: ${err.message}`);
+      return 2;
+    }
+    throw err;
+  }
+}

package/src/commands/status.ts

@@ -0,0 +1,155 @@
+/**
+ * `iapeer-memory status` — read-only diagnostics of the whole chain
+ * (ADR-009: the status surface must diagnose a socket without a system).
+ * Aggregates: verify checks (NO repair) + slot declaration + a live TCP
+ * probe of the MCP endpoint + the inbox load. Never mutates anything;
+ * exit 1 when something needs attention.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import {
+  getTaxonomy,
+  isLocaleId,
+  prepareSqliteRuntime,
+} from "@agfpd/iapeer-memory-core";
+import { memoryPaths } from "../paths.js";
+import { readSlot } from "../slot.js";
+import { packageVersion } from "../version.js";
+import { runVerify } from "./verify.js";
+
+/**
+ * The search-pipeline line — VISIBLE degradation is an acceptance condition
+ * (boris, P3a): a host configured for vector search that silently falls
+ * back must say so here and why.
+ *
+ * Source of truth ladder: (1) the LIVE pipeline as reported by the running
+ * memoryd (a real vault_search call over MCP — per-component statuses, the
+ * same object every search returns); (2) when memoryd is down — the static
+ * configuration view + the sqlite runtime probe. P3c live-smoke fact: in
+ * the compiled binary the sqlite-vec dylib does not resolve from /$bunfs —
+ * memoryd logs it once and vector search continues BRUTE-FORCE (semantics
+ * intact, slower on large vaults); the live pipeline still says
+ * embedding: ok, which is the truthful state.
+ */
+export function searchPipelineLine(env: Record<string, string | undefined>): string {
+  const embeddingConfigured = Boolean(env.IAPEER_MEMORY_EMBEDDING_ENDPOINT);
+  const rerankerConfigured = Boolean(env.IAPEER_MEMORY_RERANKER_ENDPOINT);
+  if (!embeddingConfigured) {
+    return "BM25-only (no embedding endpoint configured — a valid zero-config state)";
+  }
+  const vec = prepareSqliteRuntime();
+  return (
+    `hybrid configured: BM25 + embeddings${rerankerConfigured ? " + reranker" : ""}; ` +
+    (vec.available
+      ? `vec index runtime ok (${vec.dylibPath})`
+      : `vec index unavailable (${vec.reason}) — vector search runs brute-force`)
+  );
+}
+
+/** Live pipeline from the running memoryd — the same per-component statuses
+ * every vault_search returns. Null when memoryd is unreachable. */
+export async function probeSearchPipeline(port: number): Promise<string | null> {
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/mcp`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        accept: "application/json, text/event-stream",
+        "X-IAPeer-Identity": "claude-status-probe",
+      },
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: { name: "vault_search", arguments: { query: "status probe" } },
+      }),
+      signal: AbortSignal.timeout(8000),
+    });
+    const text = await res.text();
+    // streamable-http frames the JSON as an SSE `data:` line
+    const dataLine = text.split("\n").find((l) => l.startsWith("data:"));
+    const payload = JSON.parse(dataLine ? dataLine.slice(5) : text) as {
+      result?: { structuredContent?: { pipeline?: Record<string, unknown> } };
+    };
+    const pipeline = payload.result?.structuredContent?.pipeline;
+    if (!pipeline) return null;
+    const parts = ["bm25", "embedding", "reranker", "graph"]
+      .filter((k) => k in pipeline)
+      .map((k) => `${k}: ${String(pipeline[k])}`);
+    return `live pipeline — ${parts.join(", ")}`;
+  } catch {
+    return null;
+  }
+}
+
+async function probeMcp(port: number): Promise<{ line: string; alive: boolean }> {
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/mcp`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: "{}",
+      signal: AbortSignal.timeout(1500),
+    });
+    // ANY http response means memoryd is listening (a real MCP handshake
+    // needs a session — this is a liveness probe, not a protocol check).
+    return { line: `listening on ${port} (http ${res.status})`, alive: true };
+  } catch {
+    return { line: `nothing listening on ${port}`, alive: false };
+  }
+}
+
+export async function cmdStatus(argv: string[]): Promise<number> {
+  if (argv.length) {
+    console.error(`iapeer-memory status: unknown flag: ${argv[0]}`);
+    return 2;
+  }
+  const paths = memoryPaths();
+  const version = packageVersion();
+  console.log(`iapeer-memory v${version}`);
+
+  const results = runVerify({ repair: false });
+  const width = Math.max(...results.map((r) => r.name.length), 12);
+  for (const r of results) {
+    const mark =
+      r.status === "ok" ? "ok  " : r.status === "skip" ? "skip" : "FAIL";
+    console.log(`${mark}  ${r.name.padEnd(width)}  ${r.detail}`);
+  }
+
+  const slot = readSlot(paths.slotPath);
+  console.log(
+    `      ${"slot-file".padEnd(width)}  ` +
+      (slot
+        ? `${slot.provider} v${slot.version} (registered ${slot.registeredAt})`
+        : "empty"),
+  );
+
+  const port = Number(process.env.IAPEER_MEMORY_MCP_PORT || "") || 8766;
+  const mcp = await probeMcp(port);
+  console.log(`      ${"mcp-endpoint".padEnd(width)}  ${mcp.line}`);
+  // The live pipeline is only probed when the endpoint is alive — a dead
+  // port already told us everything (and the static view says the rest).
+  const livePipeline = mcp.alive ? await probeSearchPipeline(port) : null;
+  console.log(
+    `      ${"search".padEnd(width)}  ` +
+      (livePipeline ?? `${searchPipelineLine(process.env)} (memoryd down — static view)`),
+  );
+
+  const vault = process.env.IAPEER_MEMORY_VAULT_PATH ?? "";
+  const localeRaw = process.env.IAPEER_MEMORY_LOCALE || "en";
+  if (vault && isLocaleId(localeRaw)) {
+    const inboxDir = path.join(vault, getTaxonomy(localeRaw).folders.inbox);
+    let count = 0;
+    try {
+      count = fs.readdirSync(inboxDir).filter((f) => f.endsWith(".md")).length;
+    } catch {
+      count = -1;
+    }
+    console.log(
+      `      ${"inbox".padEnd(width)}  ` +
+        (count < 0 ? `folder missing (${inboxDir})` : `${count} draft(s) awaiting the Index`),
+    );
+  }
+
+  return results.some((r) => r.status === "fail") ? 1 : 0;
+}

package/src/commands/uninstall.ts

@@ -0,0 +1,126 @@
+/**
+ * `iapeer-memory uninstall [--keep-binary]` — remove the system from the
+ * host. SYMMETRY OBLIGATION of the memory-slot contract: the provider that
+ * writes the slot declaration removes it.
+ *
+ * What it removes: slot declaration (own only — a foreign slot is refused),
+ * the compiled binary. What it deliberately KEEPS: the vault (user data),
+ * the package config (operator-owned), state/cache (cheap to rebuild, may
+ * hold migrate backups!). What lands in P3c: notifier deregistration +
+ * memoryd stop (the watcher owns the process lifecycle).
+ *
+ * Native auto-memory of the fleet is NOT restored (contract decision,
+ * c968219): silent re-enabling would quietly resurrect split memory across
+ * the fleet — worse than an honest visible degradation. The restore lever
+ * is the core's: `iapeer native-memory on --all` (manual decision).
+ */
+
+import fs from "node:fs";
+import { memoryPaths } from "../paths.js";
+import { removeBinary } from "../binary.js";
+import { removeSlot } from "../slot.js";
+import { unregisterWatcher, WATCHER_TRIGGER_ID } from "../watcher.js";
+
+/**
+ * Owner verification before signalling: the process command line must look
+ * like OUR daemon (`… memoryd`, launched via the CLI/launcher). A pid can
+ * be recycled by the OS between memoryd's crash and uninstall — verifying
+ * the command closes the "signal a stranger" class. Probe failure → false
+ * (never signal on uncertainty).
+ */
+export function pidLooksLikeOurs(pid: number): boolean {
+  try {
+    const proc = Bun.spawnSync(["ps", "-o", "command=", "-p", String(pid)], {
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    if (proc.exitCode !== 0) return false;
+    const command = proc.stdout.toString().trim();
+    return command.includes("memoryd");
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Stop memoryd by its pid file. DEFENSIVE KILL CONTRACT (incident 10.06,
+ * boris): a signal is sent ONLY to a positive, live pid whose command line
+ * is VERIFIED to be ours — a recycled/foreign pid in a stale file must
+ * never be signalled; never a group/negative pid by construction. Shared
+ * by uninstall (stop) and update (managed restart: SIGTERM → the notifier
+ * watcher relaunches via the launcher with the fresh binary, ADR-010).
+ */
+export function stopMemorydByPidFile(pidPath: string): string {
+  let line = "not running (no pid file)";
+  try {
+    const pid = Number(fs.readFileSync(pidPath, "utf-8").trim());
+    if (Number.isInteger(pid) && pid > 1) {
+      if (!pidLooksLikeOurs(pid)) {
+        line = `pid file points at a non-memoryd process (${pid}) — NOT signalling; stale file removed`;
+      } else {
+        try {
+          process.kill(pid, "SIGTERM");
+          line = `SIGTERM sent to pid ${pid} (command verified)`;
+        } catch {
+          line = `stale pid file (process ${pid} gone) — removed`;
+        }
+      }
+    }
+    fs.unlinkSync(pidPath);
+  } catch {
+    // no pid file — nothing to stop
+  }
+  return line;
+}
+
+export function cmdUninstall(argv: string[]): number {
+  let keepBinary = false;
+  let iapeerBin = "iapeer";
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--keep-binary") keepBinary = true;
+    else if (a === "--iapeer-bin") iapeerBin = argv[++i] ?? "iapeer";
+    else {
+      console.error(`iapeer-memory uninstall: unknown flag: ${a}`);
+      return 2;
+    }
+  }
+
+  const paths = memoryPaths();
+  let failed = false;
+
+  const slot = removeSlot(paths.slotPath);
+  if (slot === "refused-foreign") {
+    console.log("slot      : held by a FOREIGN provider — left intact");
+    failed = true;
+  } else {
+    console.log(`slot      : ${slot === "removed" ? "declaration removed" : "already absent"}`);
+  }
+
+  // watcher: best-effort unregister (not-found is soft on the notifier side;
+  // the teaching reply goes to the index session, not here).
+  const unreg = unregisterWatcher({ iapeerBin });
+  console.log(
+    `watcher   : ${
+      unreg.ok
+        ? `unregister sent for ${WATCHER_TRIGGER_ID}`
+        : `unregister not sent (${unreg.detail}) — remove the trigger manually via the watcher peer`
+    }`,
+  );
+
+  console.log(`memoryd   : ${stopMemorydByPidFile(paths.pidPath)}`);
+
+  if (keepBinary) {
+    console.log(`binary    : kept (${paths.binaryPath})`);
+  } else {
+    console.log(`binary    : ${removeBinary(paths.binaryPath) === "removed" ? `removed ${paths.binaryPath}` : "already absent"}`);
+  }
+
+  console.log(`vault     : NOT touched (user data)`);
+  console.log(`config    : NOT touched (${paths.configFile} — operator-owned)`);
+  console.log(
+    "native    : fleet auto-memory stays OFF — restoring it is a manual decision; core lever: iapeer native-memory on --all",
+  );
+
+  return failed ? 1 : 0;
+}

package/src/commands/update.ts

@@ -0,0 +1,138 @@
+/**
+ * `iapeer-memory update` — one command, every surface, deterministic
+ * (ADR-010; closes the «daemon running a deleted snapshot» defect class).
+ *
+ * Run from SOURCE (`npx @agfpd/iapeer-memory@latest update`): the fresh
+ * npx snapshot recompiles the stable binary; everything downstream follows
+ * the new code. Surfaces, in order:
+ *
+ *   1. binary     — recompile `~/.local/bin/iapeer-memory` (from the
+ *                   installed binary itself: honest skip + npx hint);
+ *   2. templates  — re-materialise (package-owned, bytes-compare);
+ *   3. doctrines  — re-render every role from the roles manifest with the
+ *                   fresh version marker; roles pick it up on their next
+ *                   cold wake (ADR-007), no restarts;
+ *   4. slot       — re-declare with the new version (contract obligation);
+ *   5. launcher   — regenerate (in case the binary path moved);
+ *   6. memoryd    — MANAGED restart: verified SIGTERM via the pid file →
+ *                   the notifier watcher relaunches through the launcher
+ *                   with the NEW binary (exit-detect is unconditional —
+ *                   notifier fact). Not running → nothing to do;
+ *   7. plugin     — the harness's native plugin update flow (printed hint;
+ *                   the package never reaches into harness internals).
+ *
+ * Idempotent: same version re-run → identical/no-op on every surface.
+ */
+
+import {
+  isLocaleId,
+  renderDoctrine,
+  type LocaleId,
+} from "@agfpd/iapeer-memory-core";
+import { installBinary } from "../binary.js";
+import { memoryPaths } from "../paths.js";
+import { readRolesManifest } from "../roles.js";
+import { writeSlot } from "../slot.js";
+import { materialiseTemplates } from "../templates/index.js";
+import { packageVersion } from "../version.js";
+import { writeLauncherScript } from "../watcher.js";
+import { stopMemorydByPidFile } from "./uninstall.js";
+
+export function cmdUpdate(argv: string[]): number {
+  let skipBinary = false;
+  for (const a of argv) {
+    if (a === "--skip-binary") skipBinary = true;
+    else {
+      console.error(`iapeer-memory update: unknown flag: ${a}`);
+      return 2;
+    }
+  }
+
+  const paths = memoryPaths();
+  const version = packageVersion();
+  const localeRaw = process.env.IAPEER_MEMORY_LOCALE || "en";
+  if (!isLocaleId(localeRaw)) {
+    console.error(`iapeer-memory update: unknown locale "${localeRaw}"`);
+    return 2;
+  }
+  const locale: LocaleId = localeRaw;
+  let failures = 0;
+  const step = (name: string, detail: string, ok = true): void => {
+    if (!ok) failures++;
+    console.log(`${ok ? "ok  " : "FAIL"}  ${name.padEnd(10)}  ${detail}`);
+  };
+
+  console.log(`iapeer-memory update → v${version}`);
+
+  // 1. binary
+  if (skipBinary) {
+    step("binary", "skipped (--skip-binary)");
+  } else {
+    const bin = installBinary({ outPath: paths.binaryPath });
+    step(
+      "binary",
+      bin.action === "compiled"
+        ? `recompiled ${bin.outPath} (${Math.round(bin.bytes / 1024 / 1024)}MB)`
+        : bin.action === "skipped-compiled"
+          ? "running FROM the installed binary — recompile via: npx @agfpd/iapeer-memory@latest update"
+          : `compile failed — ${bin.detail}`,
+      bin.action !== "failed",
+    );
+  }
+
+  // 2. templates (package-owned)
+  const tmpl = materialiseTemplates({ templatesDir: paths.templatesDir, locale });
+  step("templates", `${tmpl.written.length} written, ${tmpl.identical.length} identical`);
+
+  // 3. role doctrines (version marker follows the package — ADR-010)
+  const manifest = readRolesManifest(paths.rolesManifestPath);
+  if (!manifest || manifest.roles.length === 0) {
+    step("doctrines", "no roles manifest — init has not run (nothing to re-render)");
+  } else {
+    const outcomes = manifest.roles.map((r) => ({
+      role: r.role,
+      ...renderDoctrine({ templatePath: r.template, peerCwd: r.peerCwd, version }),
+    }));
+    const missing = outcomes.filter((o) => o.action === "missing-template");
+    step(
+      "doctrines",
+      outcomes
+        .map((o) => `${o.role}: ${o.action}`)
+        .join(", ") + ` (v${version}; roles pick it up on next cold wake)`,
+      missing.length === 0,
+    );
+  }
+
+  // 4. slot version (contract obligation)
+  const slot = writeSlot({
+    slotPath: paths.slotPath,
+    version,
+    heartbeat: paths.heartbeatPath,
+  });
+  step(
+    "slot",
+    slot.action === "refused-foreign"
+      ? `slot held by foreign provider "${slot.existing?.provider}" — not ours to update`
+      : `${slot.action} (v${version})`,
+    slot.action !== "refused-foreign",
+  );
+
+  // 5. launcher
+  step("launcher", writeLauncherScript({ launcherPath: paths.launcherPath, binaryPath: paths.binaryPath }));
+
+  // 6. memoryd managed restart (the watcher relaunches with the new binary)
+  step("memoryd", `${stopMemorydByPidFile(paths.pidPath)} — the notifier watcher relaunches it with the new binary`);
+
+  // 7. plugin — harness-owned surface
+  console.log(
+    "      plugin      update via the harness's native plugin flow " +
+      "(claude/codex plugin manager); the package never reaches into harness internals",
+  );
+
+  console.log(
+    failures
+      ? `\nupdate finished with ${failures} problem(s) — iapeer-memory verify --repair`
+      : "\nupdate complete — confirm: iapeer-memory verify",
+  );
+  return failures ? 1 : 0;
+}