@memorax/memorax-code 0.1.0

package/lib/memorax-code-backend/dist/backend-service-record.js

@@ -0,0 +1,206 @@
+import { randomUUID } from "node:crypto";
+import { linkSync, readFileSync, rmSync, statSync, unlinkSync } from "node:fs";
+import { readJsonRuntimeRecord, RuntimeRecordError, writePrivateJsonRecord, } from "../../memorax-code-adapter-common/src/runtime-record.mjs";
+export const BACKEND_SERVICE_RECORD_VERSION = 1;
+const BACKEND_SERVICE_RECORD_KEYS = new Set([
+    "version",
+    "pid",
+    "instanceId",
+    "host",
+    "port",
+    "url",
+    "logPath",
+    "startedAt",
+]);
+const BACKEND_INSTANCE_ID_PATTERN = /^[A-Za-z0-9_-]+$/;
+export class BackendServiceStateError extends RuntimeRecordError {
+    constructor(state, path) {
+        super({
+            name: "Backend service state",
+            path,
+            state,
+            codePrefix: "BACKEND_SERVICE_STATE",
+            recovery: state.status === "unsupported"
+                ? "upgrade MemoraX Code or restore a supported service state record"
+                : "confirm that no managed Backend owns the recorded process before removing the state file",
+        });
+        this.name = "BackendServiceStateError";
+    }
+}
+export function readBackendServiceRecordAtPath(path) {
+    const state = readJsonRuntimeRecord(path);
+    if (state.status !== "present")
+        return state;
+    const value = state.value;
+    if (value.version !== BACKEND_SERVICE_RECORD_VERSION) {
+        if (Number.isSafeInteger(value.version) && value.version > 0) {
+            return { status: "unsupported", version: value.version };
+        }
+        return { status: "invalid", reason: "invalid_version" };
+    }
+    if (Object.keys(value).some((key) => !BACKEND_SERVICE_RECORD_KEYS.has(key))) {
+        return { status: "invalid", reason: "unknown_fields" };
+    }
+    if (!Number.isSafeInteger(value.pid) || value.pid <= 0) {
+        return { status: "invalid", reason: "invalid_pid" };
+    }
+    if (!Object.prototype.hasOwnProperty.call(value, "instanceId")) {
+        return { status: "invalid", reason: "missing_instance_id" };
+    }
+    if (typeof value.instanceId !== "string"
+        || !BACKEND_INSTANCE_ID_PATTERN.test(value.instanceId)) {
+        return { status: "invalid", reason: "invalid_instance_id" };
+    }
+    const host = nonEmptyString(value.host);
+    if (!host)
+        return { status: "invalid", reason: "invalid_host" };
+    if (!Number.isSafeInteger(value.port)
+        || value.port <= 0
+        || value.port > 65535) {
+        return { status: "invalid", reason: "invalid_port" };
+    }
+    const url = backendServiceRecordUrl(value.url, value.port);
+    if (!url)
+        return { status: "invalid", reason: "invalid_url" };
+    const logPath = nonEmptyString(value.logPath);
+    if (!logPath)
+        return { status: "invalid", reason: "invalid_log_path" };
+    const startedAt = timestampValue(value.startedAt);
+    if (!startedAt)
+        return { status: "invalid", reason: "invalid_started_at" };
+    return {
+        status: "valid",
+        record: {
+            version: BACKEND_SERVICE_RECORD_VERSION,
+            pid: value.pid,
+            instanceId: value.instanceId,
+            host,
+            port: value.port,
+            url,
+            logPath,
+            startedAt,
+        },
+    };
+}
+export function readBackendServiceStateAtPath(path) {
+    const state = readBackendServiceRecordAtPath(path);
+    if (state.status === "absent")
+        return undefined;
+    if (state.status !== "valid")
+        throw new BackendServiceStateError(state, path);
+    const { version: _version, ...serviceState } = state.record;
+    return serviceState;
+}
+export function writeBackendServiceStateAtPath(path, state, durableBoundary, runtime) {
+    return writePrivateJsonRecord(path, {
+        version: BACKEND_SERVICE_RECORD_VERSION,
+        ...state,
+    }, {
+        ...runtime,
+        durableBoundary,
+    });
+}
+export function removeBackendServiceStateIfOwnedAtPath(path, expected) {
+    const current = readBackendServiceRecordAtPath(path);
+    if (current.status === "absent") {
+        return { disposition: "not_owned", reason: "absent" };
+    }
+    if (current.status === "invalid" && current.reason === "unreadable") {
+        return removalIoFailure("failed to read Backend service state");
+    }
+    if (current.status !== "valid" || !sameServiceInstance(current.record, expected)) {
+        return { disposition: "not_owned", reason: "replacement" };
+    }
+    const claimPath = `${path}.delete-${randomUUID()}`;
+    try {
+        linkSync(path, claimPath);
+    }
+    catch (error) {
+        return isMissingPathError(error)
+            ? { disposition: "not_owned", reason: "absent" }
+            : removalIoFailure("failed to claim Backend service state", error);
+    }
+    let result;
+    try {
+        const pathStat = statSync(path);
+        const claimStat = statSync(claimPath);
+        if (pathStat.dev !== claimStat.dev || pathStat.ino !== claimStat.ino) {
+            result = { disposition: "not_owned", reason: "replacement" };
+        }
+        else {
+            const claimed = readBackendServiceRecordAtPath(claimPath);
+            if (claimed.status !== "valid" || !sameServiceInstance(claimed.record, expected)) {
+                result = { disposition: "not_owned", reason: "replacement" };
+            }
+            else if (readFileSync(path, "utf8") !== readFileSync(claimPath, "utf8")) {
+                result = { disposition: "not_owned", reason: "replacement" };
+            }
+            else {
+                unlinkSync(path);
+                result = { disposition: "removed" };
+            }
+        }
+    }
+    catch (error) {
+        result = isMissingPathError(error)
+            ? { disposition: "not_owned", reason: "absent" }
+            : removalIoFailure("failed to remove Backend service state", error);
+    }
+    try {
+        rmSync(claimPath, { force: true });
+    }
+    catch (error) {
+        return removalIoFailure("failed to remove Backend service state claim", error);
+    }
+    return result;
+}
+function sameServiceInstance(record, expected) {
+    return record.pid === expected.pid && record.instanceId === expected.instanceId;
+}
+function removalIoFailure(message, error) {
+    const detail = error instanceof Error ? error.message : undefined;
+    const errorCode = errorCodeOf(error);
+    return {
+        disposition: "io_failed",
+        error: detail ? `${message}: ${detail}` : message,
+        ...(errorCode ? { errorCode } : {}),
+    };
+}
+function isMissingPathError(error) {
+    return errorCodeOf(error) === "ENOENT";
+}
+function errorCodeOf(error) {
+    return typeof error === "object"
+        && error !== null
+        && "code" in error
+        && typeof error.code === "string"
+        ? error.code
+        : undefined;
+}
+function backendServiceRecordUrl(value, port) {
+    const candidate = nonEmptyString(value);
+    if (!candidate)
+        return undefined;
+    try {
+        const parsed = new URL(candidate);
+        if (parsed.protocol !== "http:"
+            || parsed.username
+            || parsed.password
+            || (parsed.pathname !== "" && parsed.pathname !== "/")
+            || parsed.search
+            || parsed.hash
+            || Number(parsed.port || "80") !== port)
+            return undefined;
+        return parsed.toString().replace(/\/+$/, "");
+    }
+    catch {
+        return undefined;
+    }
+}
+function nonEmptyString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function timestampValue(value) {
+    const candidate = nonEmptyString(value);
+    return candidate && Number.isFinite(Date.parse(candidate)) ? candidate : undefined;
+}

package/lib/memorax-code-backend/dist/backend-service-result.js

@@ -0,0 +1,37 @@
+import { BackendConnectionAuthorityError } from "../../memorax-code-adapter-common/src/backend-connection.mjs";
+import { RuntimeRecordError, } from "../../memorax-code-adapter-common/src/runtime-record.mjs";
+export function runtimeRecordServiceFailure(action, error) {
+    return {
+        ok: false,
+        action,
+        error: error instanceof Error ? error.message : String(error),
+        ...runtimeRecordErrorFields(error),
+    };
+}
+export function runtimeRecordErrorFields(error) {
+    return error instanceof BackendConnectionAuthorityError || error instanceof RuntimeRecordError
+        ? { errorCode: error.code }
+        : {};
+}
+export function runtimeRecordDurabilityWarning(record, result) {
+    if (result?.durability !== "uncertain")
+        return undefined;
+    return {
+        code: "BACKEND_RUNTIME_RECORD_DURABILITY_UNCERTAIN",
+        record,
+        ...(result.durabilityErrorCode ? { errorCode: result.durabilityErrorCode } : {}),
+        message: `${runtimeRecordLabel(record)} was installed, but crash durability could not be confirmed`,
+    };
+}
+export function withRuntimeRecordWarnings(result, warnings) {
+    return warnings.length > 0
+        ? { ...result, degraded: true, warnings }
+        : result;
+}
+function runtimeRecordLabel(record) {
+    if (record === "pid")
+        return "Backend PID record";
+    if (record === "token")
+        return "Backend token record";
+    return "Backend connection authority";
+}

package/lib/memorax-code-backend/dist/backend-service-token.js

@@ -0,0 +1,11 @@
+import { backendServiceHome } from "./backend-lifecycle-lock.js";
+import { persistBackendTokenForHome, readBackendTokenForHome, writeBackendTokenForHome, } from "./backend-token-record.js";
+export function readBackendToken(options = {}) {
+    return readBackendTokenForHome(backendServiceHome(options));
+}
+export function writeBackendToken(options = {}, rotate = false, runtime) {
+    return writeBackendTokenForHome(backendServiceHome(options), rotate, runtime);
+}
+export function persistBackendToken(options, token, runtime) {
+    return persistBackendTokenForHome(backendServiceHome(options), token, runtime);
+}

package/lib/memorax-code-backend/dist/backend-shutdown-request.js

@@ -0,0 +1,133 @@
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, rmSync, unwatchFile, watchFile, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+const BACKEND_INSTANCE_ID_PATTERN = /^[A-Za-z0-9_-]+$/;
+const BACKEND_SHUTDOWN_REQUEST_POLL_INTERVAL_MS = 50;
+export function backendShutdownRequestPath(memoraxCodeHome) {
+    return join(memoraxCodeHome, "runtime", "backend", "backend.shutdown.json");
+}
+export function writeBackendShutdownRequest(memoraxCodeHome, target) {
+    assertShutdownTarget(target);
+    const path = backendShutdownRequestPath(memoraxCodeHome);
+    const directory = join(memoraxCodeHome, "runtime", "backend");
+    const temporaryPath = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    const request = {
+        version: 1,
+        pid: target.pid,
+        instanceId: target.instanceId,
+        requestedAt: new Date().toISOString(),
+    };
+    mkdirSync(directory, { recursive: true });
+    rmSync(path, { force: true });
+    try {
+        writeFileSync(temporaryPath, `${JSON.stringify(request, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+        renameSync(temporaryPath, path);
+    }
+    catch (error) {
+        rmSync(temporaryPath, { force: true });
+        throw error;
+    }
+    return path;
+}
+export function clearBackendShutdownRequest(memoraxCodeHome) {
+    rmSync(backendShutdownRequestPath(memoraxCodeHome), { force: true });
+}
+export function startBackendShutdownRequestWatcher(options) {
+    assertShutdownTarget(options);
+    const path = backendShutdownRequestPath(options.memoraxCodeHome);
+    const directory = dirname(path);
+    let closed = false;
+    let accepted = false;
+    let watching = false;
+    function invokeShutdown() {
+        if (closed)
+            return;
+        void Promise.resolve(options.onShutdown()).catch((error) => {
+            options.onError?.(error);
+        });
+    }
+    function stopWatching() {
+        if (!watching)
+            return;
+        watching = false;
+        unwatchFile(path, inspect);
+    }
+    function inspect() {
+        if (closed || accepted)
+            return;
+        try {
+            if (!takeMatchingShutdownRequest(path, options))
+                return;
+            accepted = true;
+            stopWatching();
+            queueMicrotask(invokeShutdown);
+        }
+        catch (error) {
+            options.onError?.(error);
+        }
+    }
+    mkdirSync(directory, { recursive: true });
+    inspect();
+    if (!accepted) {
+        watching = true;
+        // Directory fs.watch events may be coalesced or dropped. Poll the exact
+        // request path so a graceful Windows shutdown cannot depend on one event.
+        watchFile(path, {
+            persistent: false,
+            interval: BACKEND_SHUTDOWN_REQUEST_POLL_INTERVAL_MS,
+        }, inspect);
+        // Close the gap between the initial inspection and polling registration.
+        inspect();
+    }
+    return {
+        close() {
+            if (closed)
+                return;
+            closed = true;
+            stopWatching();
+            clearBackendShutdownRequest(options.memoraxCodeHome);
+        },
+    };
+}
+function takeMatchingShutdownRequest(path, target) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+    rmSync(path, { force: true });
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return false;
+    }
+    if (!isShutdownRequest(parsed))
+        return false;
+    return parsed.pid === target.pid && parsed.instanceId === target.instanceId;
+}
+function isShutdownRequest(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const request = value;
+    return request.version === 1
+        && Number.isSafeInteger(request.pid)
+        && request.pid > 0
+        && typeof request.instanceId === "string"
+        && BACKEND_INSTANCE_ID_PATTERN.test(request.instanceId)
+        && typeof request.requestedAt === "string"
+        && Number.isFinite(Date.parse(request.requestedAt));
+}
+function assertShutdownTarget(target) {
+    if (!Number.isSafeInteger(target.pid) || target.pid <= 0) {
+        throw new TypeError("Backend shutdown target PID must be a positive safe integer");
+    }
+    if (!BACKEND_INSTANCE_ID_PATTERN.test(target.instanceId)) {
+        throw new TypeError("Backend shutdown target instanceId is invalid");
+    }
+}

package/lib/memorax-code-backend/dist/backend-state.js

@@ -0,0 +1,58 @@
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { backendEnv } from "./backend-env.js";
+export function createBackendState(host = "127.0.0.1", options = {}) {
+    const authToken = options.authToken ?? backendEnv("TOKEN");
+    const sessionHome = options.sessionHome ?? process.env.MEMORAX_CODE_HOME ?? join(homedir(), ".memorax-code");
+    const claudeProjectsRoot = options.claudeProjectsRoot
+        ?? memoryViewerClaudeProjectsRootFromEnv(process.env);
+    const security = {
+        ...envBackendSecurity(),
+        ...options.security,
+    };
+    validateBackendSecurity(host, authToken, security);
+    return {
+        sessionHome,
+        claudeProjectsRoot,
+        authToken,
+        security,
+    };
+}
+export function memoryViewerClaudeProjectsRootFromEnv(env) {
+    const configured = env.MEMORAX_CODE_MEMORY_VIEWER_CLAUDE_PROJECTS_ROOT?.trim();
+    if (!configured)
+        return undefined;
+    if (configured === "disabled")
+        return false;
+    return resolve(configured);
+}
+function envBackendSecurity() {
+    const mode = backendEnv("MODE") === "server" ? "server" : "local";
+    return {
+        mode,
+        allowExternalAccess: parseBooleanEnv(backendEnv("ALLOW_EXTERNAL")) ?? mode === "server",
+    };
+}
+function validateBackendSecurity(host, authToken, security) {
+    if (!isLoopbackHost(host) && !security.allowExternalAccess) {
+        const hint = "set MEMORAX_CODE_BACKEND_ALLOW_EXTERNAL=1 and configure MEMORAX_CODE_BACKEND_TOKEN to opt in";
+        throw new Error(`external Backend host "${host}" is disabled; ${hint}`);
+    }
+    if ((!isLoopbackHost(host) || security.mode === "server") && !authToken) {
+        throw new Error("MEMORAX_CODE_BACKEND_TOKEN is required for server mode or external Backend access");
+    }
+}
+export function isLoopbackHost(host) {
+    const normalized = host.trim().toLowerCase().replace(/^\[|\]$/g, "");
+    return normalized === "localhost" || normalized === "127.0.0.1" || normalized === "::1";
+}
+function parseBooleanEnv(value) {
+    if (value === undefined)
+        return undefined;
+    const normalized = value.trim().toLowerCase();
+    if (["1", "true", "yes", "on", "enabled"].includes(normalized))
+        return true;
+    if (["0", "false", "no", "off", "disabled"].includes(normalized))
+        return false;
+    return undefined;
+}

package/lib/memorax-code-backend/dist/backend-status.js

@@ -0,0 +1,53 @@
+//! Local backend health probe used by lifecycle status.
+import { resolve } from "node:path";
+export async function runBackendStatus(backendUrl, backendToken, timeoutMs = 5000, expectedIdentity) {
+    try {
+        const response = await fetch(new URL("/health", backendUrl), {
+            headers: backendHeaders(backendToken),
+            signal: AbortSignal.timeout(Math.max(1, Math.trunc(timeoutMs))),
+        });
+        const body = await response.json().catch(() => ({}));
+        const service = typeof body.service === "string" ? body.service : undefined;
+        const instanceId = typeof body.instanceId === "string" ? body.instanceId : undefined;
+        const identity = expectedIdentity
+            ? {
+                urlMatches: normalizeUrl(backendUrl) === normalizeUrl(expectedIdentity.url),
+                instanceIdMatches: !expectedIdentity.instanceId || instanceId === expectedIdentity.instanceId,
+                sessionHomeMatches: !expectedIdentity.sessionHome
+                    || (typeof body.state?.sessionHome === "string"
+                        && resolve(body.state.sessionHome) === resolve(expectedIdentity.sessionHome)),
+            }
+            : undefined;
+        return {
+            ok: response.ok
+                && body.ok === true
+                && service === "memorax-code-backend"
+                && (!identity || (identity.urlMatches && identity.instanceIdMatches && identity.sessionHomeMatches)),
+            url: backendUrl,
+            status: response.status,
+            service,
+            instanceId,
+            authRequired: typeof body.authRequired === "boolean" ? body.authRequired : undefined,
+            state: body.state,
+            identity,
+        };
+    }
+    catch (error) {
+        return { ok: false, url: backendUrl, error: error instanceof Error ? error.message : String(error) };
+    }
+}
+function normalizeUrl(value) {
+    try {
+        return new URL(value).toString().replace(/\/+$/, "");
+    }
+    catch {
+        return value.replace(/\/+$/, "");
+    }
+}
+function backendHeaders(backendToken, extra = {}) {
+    return {
+        ...extra,
+        connection: "close",
+        ...(backendToken ? { authorization: `Bearer ${backendToken}` } : {}),
+    };
+}

package/lib/memorax-code-backend/dist/backend-token-record.js

@@ -0,0 +1,79 @@
+import { randomBytes } from "node:crypto";
+import { backendTokenPath, BackendTokenRecordError, readBackendTokenRecordState, writeBackendTokenRecord, } from "../../memorax-code-adapter-common/src/backend-connection.mjs";
+export function readBackendTokenForHome(memoraxCodeHome) {
+    const state = readBackendTokenRecordState(memoraxCodeHome);
+    if (state.status === "absent")
+        return undefined;
+    if (state.status !== "valid") {
+        throw new BackendTokenRecordError(state, backendTokenPath(memoraxCodeHome));
+    }
+    return serviceTokenRecord(state.record, backendTokenPath(memoraxCodeHome));
+}
+export function writeBackendTokenForHome(memoraxCodeHome, rotate = false, runtime) {
+    const state = readBackendTokenRecordState(memoraxCodeHome);
+    if (state.status === "unsupported") {
+        throw new BackendTokenRecordError(state, backendTokenPath(memoraxCodeHome));
+    }
+    if (state.status === "invalid" && !rotate) {
+        throw new BackendTokenRecordError(state, backendTokenPath(memoraxCodeHome));
+    }
+    const existing = state.status === "valid"
+        ? serviceTokenRecord(state.record, backendTokenPath(memoraxCodeHome))
+        : undefined;
+    if (existing && !rotate)
+        return existing;
+    const now = new Date().toISOString();
+    return persistTokenRecord(memoraxCodeHome, {
+        token: randomBytes(32).toString("base64url"),
+        tokenPath: backendTokenPath(memoraxCodeHome),
+        createdAt: existing?.createdAt ?? now,
+        ...(existing ? { rotatedAt: now } : {}),
+    }, runtime);
+}
+export function persistBackendTokenForHome(memoraxCodeHome, token, runtime) {
+    const state = readBackendTokenRecordState(memoraxCodeHome);
+    if (state.status !== "absent" && state.status !== "valid") {
+        throw new BackendTokenRecordError(state, backendTokenPath(memoraxCodeHome));
+    }
+    const existing = state.status === "valid"
+        ? serviceTokenRecord(state.record, backendTokenPath(memoraxCodeHome))
+        : undefined;
+    if (existing?.token === token)
+        return existing;
+    const now = new Date().toISOString();
+    return persistTokenRecord(memoraxCodeHome, {
+        token,
+        tokenPath: backendTokenPath(memoraxCodeHome),
+        createdAt: existing?.createdAt ?? now,
+        ...(existing ? { rotatedAt: now } : {}),
+    }, runtime);
+}
+export function assertBackendTokenPersistenceEligible(memoraxCodeHome) {
+    const state = readBackendTokenRecordState(memoraxCodeHome);
+    if (state.status === "invalid" || state.status === "unsupported") {
+        throw new BackendTokenRecordError(state, backendTokenPath(memoraxCodeHome));
+    }
+}
+function serviceTokenRecord(record, path, persistence) {
+    return {
+        token: record.token,
+        tokenPath: path,
+        createdAt: record.createdAt,
+        ...(record.rotatedAt ? { rotatedAt: record.rotatedAt } : {}),
+        ...(persistence ? { persistence } : {}),
+    };
+}
+function persistTokenRecord(memoraxCodeHome, record, runtime) {
+    const written = writeBackendTokenRecord({
+        memoraxCodeHome,
+        token: record.token,
+        createdAt: record.createdAt,
+        ...(record.rotatedAt ? { rotatedAt: record.rotatedAt } : {}),
+    }, runtime);
+    return serviceTokenRecord(written.record, written.path, {
+        durability: written.durability,
+        ...(written.durabilityErrorCode
+            ? { durabilityErrorCode: written.durabilityErrorCode }
+            : {}),
+    });
+}