@agfpd/iapeer-memory 0.1.1

package/src/commands/init.ts

@@ -0,0 +1,358 @@
+/**
+ * `iapeer-memory init` — provision the system on this host (docs/10
+ * §Install-flow). IDEMPOTENT: every step is safe to re-run; re-running
+ * init is the official repair path for a half-provisioned host.
+ *
+ * Interactivity contract (fixed with the iapeer core, memory-slot doc):
+ * the PROVIDER owns the install questions. tty + missing answers →
+ * interactive prompts (storage path, locale, optional search endpoint,
+ * human name); all answers via flags → fully silent; NON-tty (or
+ * --non-interactive) without an explicit --vault → refusal (silent
+ * provisioning of a default storage path is forbidden). `iapeer onboard`
+ * runs this init with inherited stdio and may pass `--human <personality>`
+ * (sent only when exactly one natural peer exists in the registry).
+ *
+ * Step order: deps → vault → config → binary → templates → role peers +
+ * doctrines + roles manifest → watcher registration → slot declaration →
+ * native-memory sweep (core verb, soft-skip on old cores) → host-wide
+ * guide fragment. Ecosystem steps are skippable (--skip-ecosystem) for
+ * sandboxed runs; the binary compile is skippable (--skip-binary) for
+ * fast tests.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import {
+  getTaxonomy,
+  isLocaleId,
+  renderDoctrine,
+  writeHostWideGuideFragment,
+  type LocaleId,
+} from "@agfpd/iapeer-memory-core";
+import { installBinary } from "../binary.js";
+import { memoryPaths } from "../paths.js";
+import { provisionVault, writeDefaultConfig } from "../provision.js";
+import { writeRolesManifest, type RoleEntry } from "../roles.js";
+import { writeSlot } from "../slot.js";
+import {
+  guideText,
+  materialiseTemplates,
+  roleTemplatePath,
+  ROLE_NAMES,
+} from "../templates/index.js";
+import { packageVersion } from "../version.js";
+import { registerWatcher, writeLauncherScript } from "../watcher.js";
+
+type InitFlags = {
+  vault?: string;
+  locale?: string;
+  human?: string;
+  embeddingEndpoint?: string;
+  rerankerEndpoint?: string;
+  nonInteractive: boolean;
+  skipDeps: boolean;
+  skipEcosystem: boolean;
+  skipBinary: boolean;
+  iapeerBin: string;
+};
+
+function parseFlags(argv: string[]): InitFlags | null {
+  const f: InitFlags = {
+    nonInteractive: false,
+    skipDeps: false,
+    skipEcosystem: false,
+    skipBinary: false,
+    iapeerBin: "iapeer",
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const take = (): string | undefined => argv[++i];
+    switch (a) {
+      case "--vault": f.vault = take(); break;
+      case "--locale": f.locale = take(); break;
+      case "--human": f.human = take(); break;
+      case "--embedding-endpoint": f.embeddingEndpoint = take(); break;
+      case "--reranker-endpoint": f.rerankerEndpoint = take(); break;
+      case "--non-interactive": f.nonInteractive = true; break;
+      case "--skip-deps": f.skipDeps = true; break;
+      case "--skip-ecosystem": f.skipEcosystem = true; break;
+      case "--skip-binary": f.skipBinary = true; break;
+      case "--iapeer-bin": f.iapeerBin = take() ?? "iapeer"; break;
+      default:
+        console.error(`iapeer-memory init: unknown flag: ${a}`);
+        return null;
+    }
+  }
+  return f;
+}
+
+// ── iapeer registry helpers ──────────────────────────────────────────────────
+
+type PeerInfo = { personality: string; intelligence?: string; cwd?: string };
+
+type RunResult = { exitCode: number; stdout: string; stderr: string };
+
+/** spawnSync that never throws — a missing binary is a result, not a crash. */
+function run(cmd: string[]): RunResult {
+  try {
+    const proc = Bun.spawnSync(cmd, { stdout: "pipe", stderr: "pipe" });
+    return {
+      exitCode: proc.exitCode,
+      stdout: proc.stdout.toString(),
+      stderr: proc.stderr.toString(),
+    };
+  } catch (err) {
+    return { exitCode: 127, stdout: "", stderr: String(err) };
+  }
+}
+
+function listPeers(iapeerBin: string): PeerInfo[] | null {
+  const proc = run([iapeerBin, "list", "--json"]);
+  if (proc.exitCode !== 0) return null;
+  try {
+    return JSON.parse(proc.stdout) as PeerInfo[];
+  } catch {
+    return null;
+  }
+}
+
+/** «Don't ask what the stack already knows»: exactly one natural peer → its name. */
+function naturalPeerDefault(peers: PeerInfo[] | null): string | null {
+  const naturals = (peers ?? []).filter((p) => p.intelligence === "natural");
+  return naturals.length === 1 ? naturals[0].personality : null;
+}
+
+// ── interactive prompts (tty only) ───────────────────────────────────────────
+
+function ask(question: string, fallback: string): string {
+  // Bun's global prompt(); returns null on EOF.
+  const answer = prompt(`${question}${fallback ? ` [${fallback}]` : ""}:`);
+  const trimmed = (answer ?? "").trim();
+  return trimmed || fallback;
+}
+
+// ── the command ──────────────────────────────────────────────────────────────
+
+export async function cmdInit(argv: string[]): Promise<number> {
+  const flags = parseFlags(argv);
+  if (!flags) return 2;
+
+  const interactive =
+    !flags.nonInteractive && Boolean(process.stdin.isTTY && process.stdout.isTTY);
+
+  // ── resolve answers (provider owns the questions) ──
+  let vault = flags.vault ?? "";
+  let localeRaw = flags.locale ?? "";
+  let human = flags.human ?? "";
+  let embeddingEndpoint = flags.embeddingEndpoint ?? "";
+  const rerankerEndpoint = flags.rerankerEndpoint ?? "";
+
+  const peers = flags.skipEcosystem ? null : listPeers(flags.iapeerBin);
+  const humanDefault = flags.human ?? naturalPeerDefault(peers) ?? "";
+
+  if (!vault) {
+    if (!interactive) {
+      console.error(
+        "iapeer-memory init: no tty and no --vault — refusing to silently " +
+          "provision a default storage path. Pass --vault PATH (and --locale).",
+      );
+      return 2;
+    }
+    vault = ask("Vault (storage) path", path.join(process.env.HOME ?? "~", "iapeer-memory-vault"));
+  }
+  if (!localeRaw) {
+    localeRaw = interactive ? ask("Vault locale (en|ru)", "en") : "en";
+  }
+  if (!isLocaleId(localeRaw)) {
+    console.error(`iapeer-memory init: unknown locale "${localeRaw}" (expected en|ru)`);
+    return 2;
+  }
+  const locale: LocaleId = localeRaw;
+  if (!human) {
+    human = interactive
+      ? ask("Human owner personality (empty = no human role)", humanDefault)
+      : humanDefault; // the stack knew it — use it, don't ask
+  }
+  if (!embeddingEndpoint && interactive) {
+    embeddingEndpoint = ask(
+      "Embedding endpoint (OpenAI-compatible; empty = BM25-only)",
+      "",
+    );
+  }
+
+  const paths = memoryPaths();
+  const iapeerDir = path.dirname(paths.slotPath);
+  const version = packageVersion();
+  let failures = 0;
+  const step = (name: string, detail: string, ok = true): void => {
+    if (!ok) failures++;
+    console.log(`${ok ? "ok  " : "FAIL"}  ${name.padEnd(10)}  ${detail}`);
+  };
+
+  // 1. dependencies
+  if (flags.skipDeps) {
+    step("deps", "skipped (--skip-deps)");
+  } else {
+    const ver = run([flags.iapeerBin, "version"]);
+    if (ver.exitCode !== 0) {
+      step("deps", "iapeer foundation not found on PATH — install it first (npx @agfpd/iapeer)", false);
+    } else {
+      const coreVersion = ver.stdout.trim();
+      const hasNotifier = (peers ?? []).some((p) => p.personality === "watcher");
+      step(
+        "deps",
+        `iapeer ${coreVersion}` +
+          (hasNotifier ? ", notifier watcher peer present" : ""),
+        hasNotifier,
+      );
+      if (!hasNotifier) {
+        console.log(
+          "      deps        notifier-runtime watcher peer missing — install the notifier " +
+            "runtime (iapeer install-runtime notifier), then re-run init",
+        );
+      }
+    }
+  }
+
+  // 2. vault
+  fs.mkdirSync(vault, { recursive: true });
+  const prov = provisionVault({ vaultPath: vault, taxonomy: getTaxonomy(locale) });
+  step(
+    "vault",
+    `${vault} (${prov.createdDirs.length} dirs + ${prov.createdFiles.length} seeds created, ${prov.kept.length} kept)`,
+  );
+
+  // 3. config (operator-owned; written once)
+  const cfg = writeDefaultConfig({
+    configFile: paths.configFile,
+    vaultPath: vault,
+    locale,
+    human: human || null,
+    embeddingEndpoint: embeddingEndpoint || null,
+    rerankerEndpoint: rerankerEndpoint || null,
+  });
+  step("config", `${paths.configFile} (${cfg})`);
+
+  // 4. stable binary
+  if (flags.skipBinary) {
+    step("binary", "skipped (--skip-binary)");
+  } else {
+    const bin = installBinary({ outPath: paths.binaryPath });
+    step(
+      "binary",
+      bin.action === "compiled"
+        ? `${bin.outPath} (${Math.round(bin.bytes / 1024 / 1024)}MB)`
+        : bin.action === "skipped-compiled"
+          ? `kept existing ${bin.outPath} (running from the installed binary)`
+          : `compile failed — ${bin.detail}`,
+      bin.action !== "failed",
+    );
+  }
+
+  // 5. templates (package-owned)
+  const tmpl = materialiseTemplates({ templatesDir: paths.templatesDir, locale });
+  step("templates", `${paths.templatesDir} (${tmpl.written.length} written, ${tmpl.identical.length} identical)`);
+
+  // 6. role peers + doctrines + manifest
+  if (flags.skipEcosystem) {
+    step("roles", "skipped (--skip-ecosystem)");
+  } else {
+    const roleEntries: RoleEntry[] = [];
+    let rolesOk = true;
+    let createdAny = false;
+    for (const role of ROLE_NAMES) {
+      const exists = (peers ?? []).some((p) => p.personality === role);
+      if (!exists) {
+        const created = run([flags.iapeerBin, "create", role]);
+        if (created.exitCode !== 0) {
+          rolesOk = false;
+          console.log(`      roles       create ${role} failed: ${created.stderr.trim()}`);
+          continue;
+        }
+        createdAny = true;
+      }
+    }
+    // peerCwd: the registry FACT when the core exposes it (`cwd` in
+    // `iapeer list --json` — iapeer 39de94b, next core release), otherwise
+    // the core's DOCUMENTED create default (no --path — требование Артура;
+    // IAPEER_ROOT-aware). Forward-compatible: switches to the fact
+    // automatically once the deployed core ships the field.
+    const freshPeers = createdAny ? listPeers(flags.iapeerBin) : peers;
+    for (const role of ROLE_NAMES) {
+      const registryCwd = (freshPeers ?? []).find((p) => p.personality === role)?.cwd;
+      const peerCwd = registryCwd || path.join(iapeerDir, "peers", role);
+      const template = roleTemplatePath(paths.templatesDir, locale, role);
+      const rendered = renderDoctrine({ templatePath: template, peerCwd, version });
+      if (rendered.action === "missing-template") {
+        rolesOk = false;
+        console.log(`      roles       ${role}: template missing at ${template}`);
+        continue;
+      }
+      roleEntries.push({ role, peerCwd, template });
+    }
+    writeRolesManifest({ rolesManifestPath: paths.rolesManifestPath, roles: roleEntries });
+    step(
+      "roles",
+      `${roleEntries.map((r) => r.role).join(", ")} (doctrines v${version}, manifest ${paths.rolesManifestPath})`,
+      rolesOk && roleEntries.length === ROLE_NAMES.length,
+    );
+  }
+
+  // 7. watcher registration (registrant = index; reply goes to the index
+  // session — confirmation is the durable profile, checked by verify)
+  if (flags.skipEcosystem) {
+    step("watcher", "skipped (--skip-ecosystem)");
+  } else {
+    writeLauncherScript({ launcherPath: paths.launcherPath, binaryPath: paths.binaryPath });
+    const sent = registerWatcher({
+      launcherPath: paths.launcherPath,
+      iapeerBin: flags.iapeerBin,
+    });
+    step(
+      "watcher",
+      sent.ok
+        ? `registration sent (${paths.launcherPath} → target index); confirm: iapeer-memory verify`
+        : `registration failed — ${sent.detail}`,
+      sent.ok,
+    );
+  }
+
+  // 8. slot declaration (the contract: written by the provider, atomic)
+  const slot = writeSlot({
+    slotPath: paths.slotPath,
+    version,
+    heartbeat: paths.heartbeatPath,
+  });
+  step(
+    "slot",
+    slot.action === "refused-foreign"
+      ? `slot held by foreign provider "${slot.existing?.provider}" — uninstall it first`
+      : `${paths.slotPath} (${slot.action}, v${version})`,
+    slot.action !== "refused-foreign",
+  );
+
+  // 9. native-memory sweep — the core's lever (one home of runtime forms);
+  // soft-skip when the verb is unavailable (older core), verify re-runs later.
+  if (flags.skipEcosystem) {
+    step("sweep", "skipped (--skip-ecosystem)");
+  } else {
+    const sweep = run([flags.iapeerBin, "native-memory", "off", "--all"]);
+    step(
+      "sweep",
+      sweep.exitCode === 0
+        ? `native auto-memory off across the fleet (${sweep.stdout.trim().split("\n").pop() ?? "ok"})`
+        : `soft-skip: core verb unavailable (${sweep.stderr.trim().slice(0, 120) || `exit ${sweep.exitCode}`}) — upgrade the iapeer core and re-run`,
+    );
+  }
+
+  // 10. host-wide guide fragment (layer 5 — reaches every peer on next wakes)
+  const guidePath = writeHostWideGuideFragment(iapeerDir, guideText(locale));
+  step("guide", guidePath);
+
+  console.log(
+    failures
+      ? `\ninit finished with ${failures} problem(s) — re-run init (idempotent) or iapeer-memory verify --repair`
+      : "\ninit complete — check the chain: iapeer-memory status",
+  );
+  return failures ? 1 : 0;
+}

package/src/commands/install-binary.ts

@@ -0,0 +1,44 @@
+/**
+ * `iapeer-memory install-binary` — compile the stable CLI binary into
+ * `~/.local/bin/iapeer-memory` (init step / repair path). Must run from the
+ * package SOURCE (npx / checkout); the installed binary cannot rebuild
+ * itself (see binary.ts header).
+ */
+
+import { installBinary } from "../binary.js";
+import { memoryPaths } from "../paths.js";
+
+export function cmdInstallBinary(argv: string[]): number {
+  let outPath = memoryPaths().binaryPath;
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === "--out") {
+      const v = argv[++i];
+      if (!v) {
+        console.error("iapeer-memory install-binary: --out requires a value");
+        return 2;
+      }
+      outPath = v;
+    } else {
+      console.error(`iapeer-memory install-binary: unknown flag: ${argv[i]}`);
+      return 2;
+    }
+  }
+
+  const outcome = installBinary({ outPath });
+  switch (outcome.action) {
+    case "compiled":
+      console.log(
+        `install-binary: compiled ${outcome.outPath} (${Math.round(outcome.bytes / 1024 / 1024)}MB)`,
+      );
+      return 0;
+    case "skipped-compiled":
+      console.error(
+        "install-binary: running FROM the installed binary — sources unavailable; " +
+          "re-install via: npx @agfpd/iapeer-memory install-binary",
+      );
+      return 1;
+    case "failed":
+      console.error(`install-binary: compile failed — ${outcome.detail}`);
+      return 1;
+  }
+}

package/src/commands/memoryd.ts

@@ -0,0 +1,101 @@
+/**
+ * `iapeer-memory memoryd` — run the daemon in the foreground (ADR-004).
+ *
+ *   iapeer-memory memoryd [--mcp-port N | --no-mcp] [--human NAME]
+ *
+ * This IS the watcher script the notifier supervises: stdout carries the
+ * event signal lines (INBOX_NEW / PERMANENT_* — core emits them), stderr
+ * carries logs, SIGTERM/SIGINT shut down cleanly (flush + close). All state
+ * paths come from the shared `paths.ts` namespace — the heartbeat lands
+ * exactly where `verify` reads it, by construction.
+ *
+ * - MCP port: `--mcp-port` > IAPEER_MEMORY_MCP_PORT/config file > 8766
+ *   (config default, ADR-012); `--no-mcp` disables the endpoint;
+ * - human-edit detection: `--human` > IAPEER_MEMORY_HUMAN_NAME; absent →
+ *   detection off (⚖7 — the human role is optional);
+ * - fresh-edit window: IAPEER_MEMORY_FRESH_EDIT_WINDOW_S (default in core).
+ */
+
+import fs from "node:fs";
+import { configFromEnv, startMemoryd } from "@agfpd/iapeer-memory-core";
+import { memoryPaths } from "../paths.js";
+
+export async function cmdMemoryd(argv: string[]): Promise<number> {
+  let mcpPort: number | undefined;
+  let noMcp = false;
+  let human: string | null = null;
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    switch (a) {
+      case "--mcp-port": {
+        const v = Number(argv[++i]);
+        if (!Number.isInteger(v) || v < 0 || v > 65535) {
+          console.error(`iapeer-memory memoryd: invalid --mcp-port: ${argv[i]}`);
+          return 2;
+        }
+        mcpPort = v;
+        break;
+      }
+      case "--no-mcp":
+        noMcp = true;
+        break;
+      case "--human":
+        human = argv[++i] ?? null;
+        break;
+      default:
+        console.error(`iapeer-memory memoryd: unknown flag: ${a}`);
+        return 2;
+    }
+  }
+
+  const config = configFromEnv();
+  const paths = memoryPaths();
+  for (const dir of [paths.stateDir, paths.cacheDir, paths.logsDir]) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  // pid file — uninstall's stop handle (best-effort; stale files are
+  // harmless: the reader checks liveness before signalling).
+  fs.writeFileSync(paths.pidPath, `${process.pid}\n`);
+
+  const freshEditWindowRaw = process.env.IAPEER_MEMORY_FRESH_EDIT_WINDOW_S;
+  const freshEditWindowS =
+    freshEditWindowRaw && Number.isFinite(Number(freshEditWindowRaw))
+      ? Number(freshEditWindowRaw)
+      : undefined;
+
+  const handle = await startMemoryd({
+    config,
+    heartbeatPath: paths.heartbeatPath,
+    hashStatePath: paths.hashStatePath,
+    tagsMirrorPath: paths.tagsMirrorPath,
+    humanName: human ?? process.env.IAPEER_MEMORY_HUMAN_NAME ?? null,
+    freshEditWindowS,
+    mcpPort: noMcp ? null : mcpPort,
+  });
+
+  return await new Promise<number>((resolve) => {
+    let closing = false;
+    const shutdown = (signal: string) => {
+      if (closing) return;
+      closing = true;
+      console.error(`memoryd: ${signal} — shutting down`);
+      handle
+        .close()
+        .then(() => {
+          try {
+            fs.unlinkSync(paths.pidPath);
+          } catch {
+            // best effort
+          }
+          resolve(0);
+        })
+        .catch((err) => {
+          console.error(`memoryd: close failed: ${String(err)}`);
+          resolve(1);
+        });
+    };
+    process.on("SIGINT", () => shutdown("SIGINT"));
+    process.on("SIGTERM", () => shutdown("SIGTERM"));
+  });
+}

package/src/commands/migrate.ts

@@ -0,0 +1,112 @@
+/**
+ * `iapeer-memory migrate` — move a harness's built-in auto-memory into the
+ * vault's agent-memory zone (core engine; the SOURCE directory is
+ * adapter-scoped and always explicit — the engine never guesses where a
+ * harness keeps its memories, ADR/нюанс: codex format is gated on live
+ * verification, P5).
+ *
+ *   iapeer-memory migrate --source DIR --agent NAME [--apply]
+ *                         [--backup-root DIR]
+ *
+ * Dry-run by default: prints the plan (per-file mapping + subtype counts)
+ * and exits 0. `--apply` runs the real migration: per-file backup → convert
+ * + atomic write → unlink source; exit 1 if any file errored.
+ */
+
+import fs from "node:fs";
+import {
+  applyMigration,
+  configFromEnv,
+  planMigration,
+  resolveAgentName,
+} from "@agfpd/iapeer-memory-core";
+import { memoryPaths } from "../paths.js";
+import path from "node:path";
+
+export function cmdMigrate(argv: string[]): number {
+  let source = "";
+  let agent: string | null = null;
+  let apply = false;
+  let backupRoot = "";
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    switch (a) {
+      case "--source":
+        source = argv[++i] ?? "";
+        break;
+      case "--agent":
+        agent = argv[++i] ?? null;
+        break;
+      case "--apply":
+        apply = true;
+        break;
+      case "--backup-root":
+        backupRoot = argv[++i] ?? "";
+        break;
+      default:
+        console.error(`iapeer-memory migrate: unknown flag: ${a}`);
+        return 2;
+    }
+  }
+
+  const resolvedAgent = resolveAgentName(agent);
+  if (!source || !resolvedAgent) {
+    console.error(
+      "iapeer-memory migrate: --source DIR is required, and an agent " +
+        "(--agent or PEER_PERSONALITY) must resolve",
+    );
+    return 2;
+  }
+  if (!fs.existsSync(source) || !fs.statSync(source).isDirectory()) {
+    console.error(`iapeer-memory migrate: source is not a directory: ${source}`);
+    return 1;
+  }
+
+  const config = configFromEnv();
+  const paths = memoryPaths();
+
+  if (!apply) {
+    const plan = planMigration({
+      sourceDir: source,
+      agent: resolvedAgent,
+      vault: config.vaultPath,
+      taxonomy: config.taxonomy,
+    });
+    console.log(`migrate (dry-run): ${plan.source} → ${plan.target}`);
+    for (const f of plan.files) {
+      console.log(
+        f.error
+          ? `  !! ${f.name}: ${f.error}`
+          : `  ${f.name}: ${f.oldType} → ${f.subtype}`,
+      );
+    }
+    if (plan.skippedSystem.length) {
+      console.log(`  system (backup-only): ${plan.skippedSystem.join(", ")}`);
+    }
+    if (plan.skippedAlreadyInTarget.length) {
+      console.log(`  already in target: ${plan.skippedAlreadyInTarget.join(", ")}`);
+    }
+    console.log(
+      `  total to migrate: ${plan.totalToMigrate} ` +
+        `(${Object.entries(plan.subtypeCounts).map(([k, v]) => `${k}: ${v}`).join(", ") || "none"})`,
+    );
+    console.log("run again with --apply to migrate");
+    return 0;
+  }
+
+  const result = applyMigration({
+    sourceDir: source,
+    agent: resolvedAgent,
+    vault: config.vaultPath,
+    backupRoot: backupRoot || path.join(paths.stateDir, "migrate-backups"),
+    taxonomy: config.taxonomy,
+  });
+  console.log(
+    `migrate: ${result.migrated.length} migrated, ${result.skipped.length} skipped, ` +
+      `${result.errors.length} errors; backup: ${result.backupDir}` +
+      `${result.sourceRemoved ? "; source dir removed" : ""}`,
+  );
+  for (const e of result.errors) console.error(`  !! ${e}`);
+  return result.errors.length ? 1 : 0;
+}