memkin 0.4.0

package/dist/lifecycle/legacy-migration.js

@@ -0,0 +1,212 @@
+/**
+ * Legacy data auto-migration (R2): memoark → memkin.
+ *
+ * R1 renamed every default with NO fallback (config file, ~/.memkin data dir,
+ * project-local .memkin/ state dir). Existing users — whose real memories live
+ * under the old memoark paths — would silently start from scratch. This module
+ * performs a one-shot, seamless migration at CLI startup so nothing is lost.
+ *
+ * It is invoked ONCE, early in CLI boot (a commander `preAction` hook), BEFORE
+ * loadConfig reads memkin.yaml or any store is opened. It covers three moves:
+ *
+ *   1. user data dir   ~/.memoark      → ~/.memkin
+ *   2. config file      memoark.yaml   → memkin.yaml   (nearest-ancestor search,
+ *      mirroring resolveConfigPath's upward walk from cwd)
+ *   3. project state    .memoark/      → .memkin/      (at the config anchor dir
+ *      AND at cwd — see migrateLegacyData for why both)
+ *
+ * Design rules (see R2 spec):
+ *   - rename-only (fs.renameSync). NEVER copy-recursive — a half-copied SQLite/PG
+ *     dir is worse than none. On EXDEV / any rename failure we leave the old dir
+ *     in place and print an actionable manual-move instruction.
+ *   - both old + new exist → NEVER merge, NEVER delete. Use new, warn once.
+ *   - neither exists → silent no-op (fresh install stays zero-noise).
+ *   - idempotent: after a successful move the old path is gone, so a second run
+ *     hits the "neither / new-only" branch and stays silent.
+ *   - lock safety: refuse to move ~/.memoark while a legacy daemon lock is live
+ *     (lifecycle.lock / managed-pg.lock with an alive pid).
+ *   - backups (~/.memoark.bak.*) are intentionally left untouched.
+ *   - legacy MEMOARK_* env vars are NOT honored (clean cut) but never silently
+ *     ignored — we warn listing which are set and their MEMKIN_* replacement.
+ *
+ * All output goes through caller-supplied `notice` / `warn` sinks. In production
+ * both default to STDERR (console.error). This is deliberate: the choke point
+ * runs for every command including `serve --mcp`, where STDOUT is the JSON-RPC
+ * channel and any stray byte corrupts the transport. stderr is safe there.
+ */
+import { existsSync, readFileSync, renameSync } from "node:fs";
+import { dirname, join } from "node:path";
+/**
+ * Check if a process is alive using signal 0 (no actual signal delivered).
+ * Mirrors the logic in lifecycle-lock.ts / managed-lock.ts.
+ */
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true; // delivered → alive
+    }
+    catch (err) {
+        if (err.code === "EPERM")
+            return true; // exists, owned by another user
+        return false; // ESRCH → no such process
+    }
+}
+/**
+ * Returns true if the legacy data dir contains a lock file whose owning pid is
+ * still alive — i.e. a legacy daemon (serve / managed PG) may be running against
+ * it. We refuse to move the dir out from under a live process.
+ *
+ * We check the same lock filenames the current code uses inside the data dir:
+ *   - lifecycle.lock  (SP4 mutation lock; JSON { pid, ... })
+ *   - managed-pg.lock (managed Postgres lock; JSON { pid, ts })
+ * A corrupted / unparseable lock is treated as NOT live (stale) — consistent
+ * with how acquireLifecycleLock / withManagedLock reclaim corrupted locks.
+ */
+function legacyDataDirHasLiveLock(dir) {
+    for (const name of ["lifecycle.lock", "managed-pg.lock"]) {
+        const p = join(dir, name);
+        if (!existsSync(p))
+            continue;
+        try {
+            const parsed = JSON.parse(readFileSync(p, "utf8"));
+            const pid = parsed.pid;
+            if (typeof pid === "number" && isProcessAlive(pid))
+                return true;
+        }
+        catch {
+            // unparseable → treat as stale, keep checking other lock files
+        }
+    }
+    return false;
+}
+/** Migrate one target with the shared old/new rules (see module doc). */
+function migrateTarget(target, notice, warn, renameFn) {
+    const { oldPath, newPath, oldLabel, newLabel } = target;
+    const oldExists = existsSync(oldPath);
+    const newExists = existsSync(newPath);
+    // neither → silent no-op (also the idempotent second-run path once old is gone)
+    if (!oldExists)
+        return;
+    // both exist → NEVER merge, NEVER delete. Use new, warn once about the stale old one.
+    if (newExists) {
+        warn(`Legacy ${oldLabel} still exists but ${newLabel} is already in use — ` +
+            `ignoring the old one. Remove ${oldLabel} manually once you've confirmed nothing is needed.`);
+        return;
+    }
+    // old exists, new absent → rename (same-volume move; atomic, no copy).
+    try {
+        renameFn(oldPath, newPath);
+        notice(`Migrated legacy ${oldLabel} → ${newLabel}`);
+    }
+    catch (err) {
+        const code = err.code;
+        const hint = code === "EXDEV" ? " (old and new are on different volumes)" : code ? ` (${code})` : "";
+        warn(`Could not migrate legacy ${oldLabel} → ${newLabel}${hint}. ` +
+            `Move it manually: mv "${oldPath}" "${newPath}"`);
+    }
+}
+/**
+ * Find the directory where config discovery will anchor, mirroring
+ * resolveConfigPath (src/core/config.ts): walk up from cwd and stop at the
+ * FIRST directory containing memkin.yaml OR memoark.yaml.
+ *
+ * Including the legacy name in the stop condition is the whole point: a user
+ * with memoark.yaml at the project root who runs memkin from a subdir must get
+ * that file renamed IN PLACE at the ancestor, or post-R1 discovery walks past
+ * it and silently boots on defaults. A nearer memkin.yaml shadows any older
+ * memoark.yaml higher up (exactly as discovery would), so we stop there and
+ * leave the shadowed file alone.
+ *
+ * Falls back to cwd when nothing is found — same as resolveConfigPath's
+ * `resolve(process.cwd(), "memkin.yaml")` fallback.
+ */
+function findConfigAnchorDir(cwd) {
+    let dir = cwd;
+    while (true) {
+        if (existsSync(join(dir, "memkin.yaml")) || existsSync(join(dir, "memoark.yaml"))) {
+            return dir;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return cwd;
+        dir = parent;
+    }
+}
+/**
+ * Detect legacy MEMOARK_* env vars and warn (once) that they are no longer
+ * honored and must be renamed to MEMKIN_*. Values are never printed.
+ */
+function warnLegacyEnvVars(env, warn) {
+    const legacy = Object.keys(env)
+        .filter((k) => k.startsWith("MEMOARK_"))
+        .sort();
+    if (legacy.length === 0)
+        return;
+    const renamed = legacy.map((k) => `${k}→${k.replace(/^MEMOARK_/, "MEMKIN_")}`).join(", ");
+    warn(`Ignoring legacy environment variable(s): ${renamed}. ` +
+        `MEMOARK_* vars are no longer read — rename them to MEMKIN_* to take effect.`);
+}
+/**
+ * Run all legacy → memkin migrations. Idempotent and safe to call on every boot.
+ *
+ * Order: env warning first (cheap, always relevant), then data dir (guarded by
+ * lock check), then config file, then project state dir.
+ */
+export function migrateLegacyData(opts) {
+    const notice = opts.notice ?? ((m) => console.error(m));
+    const warn = opts.warn ?? ((m) => console.error(m));
+    const renameFn = opts.renameFn ?? renameSync;
+    const { home, cwd, env } = opts;
+    // 0. Legacy env vars — warn but do not honor.
+    warnLegacyEnvVars(env, warn);
+    // 1. User data dir: ~/.memoark → ~/.memkin (lock-guarded).
+    const oldDataDir = join(home, ".memoark");
+    const newDataDir = join(home, ".memkin");
+    if (existsSync(oldDataDir) && !existsSync(newDataDir)) {
+        if (legacyDataDirHasLiveLock(oldDataDir)) {
+            warn(`Legacy data dir ${join(home, ".memoark")} appears to have a running instance ` +
+                `(live lock detected). Stop it first (e.g. \`memkin down\`), then re-run to migrate.`);
+        }
+        else {
+            migrateTarget({
+                oldPath: oldDataDir,
+                newPath: newDataDir,
+                oldLabel: "~/.memoark",
+                newLabel: "~/.memkin",
+            }, notice, warn, renameFn);
+        }
+    }
+    else if (existsSync(oldDataDir) && existsSync(newDataDir)) {
+        // both exist → warn once, keep both.
+        migrateTarget({ oldPath: oldDataDir, newPath: newDataDir, oldLabel: "~/.memoark", newLabel: "~/.memkin" }, notice, warn, renameFn);
+    }
+    // 2. Config file: memoark.yaml → memkin.yaml at the discovery anchor (nearest
+    //    ancestor from cwd, mirroring resolveConfigPath's upward walk — NOT just
+    //    cwd, or a config at the project root is missed when running from a
+    //    subdir). Default name only; a user-supplied --config / MEMKIN_CONFIG
+    //    path is their own and untouched.
+    const anchorDir = findConfigAnchorDir(cwd);
+    const inAnchor = anchorDir === cwd ? "" : ` (in ${anchorDir})`;
+    migrateTarget({
+        oldPath: join(anchorDir, "memoark.yaml"),
+        newPath: join(anchorDir, "memkin.yaml"),
+        oldLabel: `memoark.yaml${inAnchor}`,
+        newLabel: "memkin.yaml",
+    }, notice, warn, renameFn);
+    // 3. Project-local state dir: .memoark/ → .memkin/. State resolution is NOT
+    //    cwd-only (src/core/state.ts defaults to cwd, but most call sites anchor
+    //    to the config's projectRoot = dirname(configPath) — e.g. extract/serve in
+    //    cli.ts), so migrate at BOTH locations: the config anchor dir (projectRoot
+    //    callers) and cwd (no-base callers like `docs sync`). Same rules each.
+    const stateDirs = anchorDir === cwd ? [cwd] : [anchorDir, cwd];
+    for (const base of stateDirs) {
+        const inBase = base === cwd ? "" : ` (in ${base})`;
+        migrateTarget({
+            oldPath: join(base, ".memoark"),
+            newPath: join(base, ".memkin"),
+            oldLabel: `.memoark/${inBase}`,
+            newLabel: ".memkin/",
+        }, notice, warn, renameFn);
+    }
+}
+//# sourceMappingURL=legacy-migration.js.map

package/dist/lifecycle/legacy-migration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacy-migration.js","sourceRoot":"","sources":["../../src/lifecycle/legacy-migration.ts"],"names":[],"mappings":"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"}

package/dist/lifecycle/lifecycle-lock.d.ts

@@ -0,0 +1,20 @@
+export interface LockInfo {
+    pid: number;
+    command: string;
+    hostname: string;
+    startedAt: string;
+}
+export interface LockHandle {
+    release(): void;
+}
+export declare class LifecycleLockError extends Error {
+    readonly holder: LockInfo;
+    constructor(holder: LockInfo);
+}
+/**
+ * Acquire the lifecycle advisory lock at `<home>/.memkin/lifecycle.lock`.
+ * Throws `LifecycleLockError` if another live process on this hostname holds the lock.
+ * Reclaims stale locks (dead pid).
+ */
+export declare function acquireLifecycleLock(home: string, command: string): LockHandle;
+//# sourceMappingURL=lifecycle-lock.d.ts.map

package/dist/lifecycle/lifecycle-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-lock.d.ts","sourceRoot":"","sources":["../../src/lifecycle/lifecycle-lock.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,IAAI,IAAI,CAAC;CACjB;AAKD,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;gBACd,MAAM,EAAE,QAAQ;CAY7B;AA8BD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,CA0C9E"}

package/dist/lifecycle/lifecycle-lock.js

@@ -0,0 +1,98 @@
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { hostname } from "node:os";
+import { join } from "node:path";
+const LOCK_FILENAME = "lifecycle.lock";
+const MAX_PREEMPT_RETRIES = 5;
+export class LifecycleLockError extends Error {
+    holder;
+    constructor(holder) {
+        super([
+            "✗ Memkin lifecycle lock is held by another process",
+            `  Holder: PID ${holder.pid}, command '${holder.command}', started at ${holder.startedAt} (host: ${holder.hostname})`,
+            "  Only one SP4 mutation command can run at a time.",
+            "  → Wait for the other command to finish, then retry.",
+        ].join("\n"));
+        this.name = "LifecycleLockError";
+        this.holder = holder;
+    }
+}
+/** Check if a process is alive using signal 0 (no actual signal sent). */
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true; // delivered → alive
+    }
+    catch (err) {
+        if (err.code === "EPERM")
+            return true; // exists but owned by another user
+        return false; // ESRCH → no such process
+    }
+}
+function makeHandle(lockPath, self) {
+    let released = false;
+    const release = () => {
+        if (released)
+            return;
+        released = true;
+        try {
+            const cur = JSON.parse(readFileSync(lockPath, "utf8"));
+            if (cur.pid === self.pid)
+                unlinkSync(lockPath); // only delete if we still own it
+        }
+        catch {
+            // already deleted or corrupted → nothing to do
+        }
+        process.removeListener("exit", release);
+    };
+    process.once("exit", release);
+    return { release };
+}
+/**
+ * Acquire the lifecycle advisory lock at `<home>/.memkin/lifecycle.lock`.
+ * Throws `LifecycleLockError` if another live process on this hostname holds the lock.
+ * Reclaims stale locks (dead pid).
+ */
+export function acquireLifecycleLock(home, command) {
+    const lockDir = join(home, ".memkin");
+    if (!existsSync(lockDir))
+        mkdirSync(lockDir, { recursive: true });
+    const lockPath = join(lockDir, LOCK_FILENAME);
+    const self = {
+        pid: process.pid,
+        command,
+        hostname: hostname(),
+        startedAt: new Date().toISOString(),
+    };
+    for (let attempt = 0; attempt < MAX_PREEMPT_RETRIES; attempt++) {
+        try {
+            writeFileSync(lockPath, JSON.stringify(self), { flag: "wx" }); // O_EXCL — atomic create
+            return makeHandle(lockPath, self);
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+        }
+        // EEXIST — inspect current holder
+        let holder = null;
+        try {
+            holder = JSON.parse(readFileSync(lockPath, "utf8"));
+        }
+        catch {
+            holder = null; // corrupted → treat as stale
+        }
+        if (holder && holder.hostname !== self.hostname)
+            throw new LifecycleLockError(holder); // cross-host: conservative reject
+        if (holder && isProcessAlive(holder.pid))
+            throw new LifecycleLockError(holder); // live process → reject
+        // stale (dead pid or corrupted) — unlink and retry
+        try {
+            unlinkSync(lockPath);
+        }
+        catch (err) {
+            if (err.code !== "ENOENT")
+                throw err; // another process already cleaned up
+        }
+    }
+    throw new Error(`Failed to acquire lifecycle lock after ${MAX_PREEMPT_RETRIES} attempts (livelock?)`);
+}
+//# sourceMappingURL=lifecycle-lock.js.map

package/dist/lifecycle/lifecycle-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-lock.js","sourceRoot":"","sources":["../../src/lifecycle/lifecycle-lock.ts"],"names":[],"mappings":"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"}

package/dist/lifecycle/run-up.d.ts

@@ -0,0 +1,38 @@
+import type { LoadedConfig } from "../core/config.js";
+import type { DaemonRuntime } from "../daemon/autostart/argv.js";
+import type { CommandRunner } from "../daemon/autostart/runner.js";
+export interface RunUpOptions {
+    port?: number;
+    config?: string;
+    linger?: boolean;
+}
+export interface RunUpInjected {
+    runner?: CommandRunner;
+    fetchHealthImpl?: (url: string) => Promise<{
+        status: number;
+        body: Record<string, unknown>;
+    }>;
+    home?: string;
+    platform?: NodeJS.Platform;
+    /** Override daemon runtime detection — useful in tests where no binary/dist exists. */
+    daemonRuntime?: DaemonRuntime;
+    /**
+     * Override the managed-Postgres foreground provision step. Injected in tests to
+     * avoid spinning up a real Postgres cluster. In production this is omitted and the
+     * real provisionManagedForeground is called with live provider/supervisor deps.
+     */
+    provisionManagedForeground?: (config: LoadedConfig) => Promise<void>;
+}
+export interface RunUpResult {
+    url: string;
+    port: number;
+    engine: string;
+    wiredAgents: string[];
+    skippedAgents: Array<{
+        id: string;
+        reason: string;
+    }>;
+    warnings: string[];
+}
+export declare function runUp(opts?: RunUpOptions, injected?: RunUpInjected): Promise<RunUpResult>;
+//# sourceMappingURL=run-up.d.ts.map

package/dist/lifecycle/run-up.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-up.d.ts","sourceRoot":"","sources":["../../src/lifecycle/run-up.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAUjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAanE,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IAC9F,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC3B,uFAAuF;IACvF,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;;OAIG;IACH,0BAA0B,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACtE;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,aAAa,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrD,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,wBAAsB,KAAK,CACzB,IAAI,GAAE,YAAiB,EACvB,QAAQ,GAAE,aAAkB,GAC3B,OAAO,CAAC,WAAW,CAAC,CAiOtB"}