Python
import {
chmod,
lstat,
mkdir,
readFile,
rename,
rm,
writeFile,
} from "node:fs/promises";
import path from "node:path";
import { installCliLink, planCliLink } from "@one-memory/runtime-control";
const CLI_PATH_BEGIN = "# >>> memhub PATH >>>";
const CLI_PATH_END = "# <<< memhub PATH <<<";
export function isInstalledApplicationsApp(
executablePath: string,
platform: NodeJS.Platform = process.platform,
): boolean {
if (platform !== "darwin") return true;
const resolved = path.resolve(executablePath);
return /^\/Applications\/[^/]+\.app\/Contents\/MacOS\/[^/]+$/.test(resolved);
}
export async function installBundledCliIfNeeded(options: {
home: string;
installRoot: string;
platform?: NodeJS.Platform;
}): Promise<void> {
const platform = options.platform ?? process.platform;
if (platform === "win32") return;
const plan = await planCliLink({
home: options.home,
installRoot: options.installRoot,
platform,
includeCompatibilityAlias: false,
});
await installCliLink(plan);
await ensureCliPath(options.home, plan.bin_directory, platform);
}
async function ensureCliPath(
home: string,
binDirectory: string,
platform: NodeJS.Platform,
): Promise<void> {
const profile = path.join(
home,
platform === "darwin" ? ".zprofile" : ".profile",
);
const existingInfo = await lstat(profile).catch(() => null);
if (
existingInfo?.isSymbolicLink() ||
(existingInfo && !existingInfo.isFile())
) {
throw new Error("shell_profile_unmanaged");
}
const existing = existingInfo ? await readFile(profile, "utf8") : "";
if (
existing.includes(CLI_PATH_BEGIN) ||
existing.split("\n").some((line) => line.includes(binDirectory))
) {
return;
}
await mkdir(home, { recursive: true, mode: 0o700 });
const separator = existing === "" || existing.endsWith("\n") ? "" : "\n";
const block = `${CLI_PATH_BEGIN}\nexport PATH="$HOME/.local/bin:$PATH"\n${CLI_PATH_END}\n`;
const temporary = `${profile}.memhub-${process.pid}`;
try {
await writeFile(temporary, `${existing}${separator}${block}`, {
encoding: "utf8",
mode: 0o600,
});
await chmod(temporary, existingInfo ? existingInfo.mode & 0o777 : 0o600);
await rename(temporary, profile);
} finally {
await rm(temporary, { force: true });
}
}
/** Install the bundle into the stable directory before rewriting host configs.
*
* Repair points every already-installed host at `current`. Doing that first
* leaves those hosts calling a program that is not on disk.
*/
export async function ensureStableRuntimeThenRepair(options: {
packaged: boolean;
preview: boolean;
install: () => Promise<unknown>;
repair: () => Promise<unknown>;
}): Promise<void> {
if (!options.packaged) return;
if (!options.preview) await options.install();
await options.repair();
}
export function startStableRuntimeRepair(options: {
packaged: boolean;
preview: boolean;
install: () => Promise<unknown>;
repair: () => Promise<unknown>;
onStage?: (
stage: "install" | "repair",
outcome: "started" | "succeeded",
) => void | Promise<void>;
onError?: (error: unknown) => void | Promise<void>;
}): Promise<void> {
return (async () => {
try {
if (!options.packaged) return;
if (!options.preview) {
await options.onStage?.("install", "started");
await options.install();
await options.onStage?.("install", "succeeded");
}
await options.onStage?.("repair", "started");
await options.repair();
await options.onStage?.("repair", "succeeded");
} catch (error) {
await options.onError?.(error);
}
})();
}
const SAFE_STABLE_RUNTIME_ERROR_CODES = new Set([
"installed_version_conflict",
"distribution_downgrade_refused",
"install_current_unmanaged",
// Migration runs before the app window exists, so these are the only names
// a first launch can be given. They stay codes here and become sentences in
// STABLE_RUNTIME_USER_MESSAGES: a person reading the dialog never sees them.
"packaged_runtime_not_current",
"sdk_migration_preflight_failed",
"sdk_migration_memory_unreadable",
"sdk_migration_model_profile_required",
"sdk_migration_vector_profile_missing",
"sdk_migration_model_secret_unavailable",
"sdk_migration_secure_storage_unavailable",
"sdk_migration_disk_space_insufficient",
"sdk_migration_cutover_failed",
"sdk_migration_bundle_copy_failed",
"sdk_migration_response_invalid",
"sdk_migration_status_unavailable",
"sdk_migration_incomplete",
"runtime_service_not_ready",
]);
/** Every migration code is a stable token Core or the orchestrator chose;
* keeping it (instead of collapsing to `desktop_start_failed`) is what lets a
* report be matched to the line in `sdk-migration.log`. */
const MIGRATION_CODE = /^sdk_(?:migration|data_plane)_[a-z0-9_]{1,80}$/;
export function stableRuntimeErrorCode(error: unknown): string {
if (
error instanceof Error &&
(SAFE_STABLE_RUNTIME_ERROR_CODES.has(error.message) ||
MIGRATION_CODE.test(error.message))
) {
return error.message;
}
return "desktop_start_failed";
}
/**
* `installUserService` reports a durable `launchctl disable` override with this
* exact code. It is a state to surface, not a failure to undo: the installer
* never re-enables a service the user or the system disabled, and the macOS
* platform checks assert that refusal
* (`install_refuses_to_re_enable_a_disabled_service`).
*
* The override outlives a re-install, so treating it as fatal leaves an
* affected machine with an app that exits on every launch. Desktop degrades
* instead, owning the Runtime as a child process, and reports the durable
* state rather than clearing it.
*
* Only this exact code degrades. Every other install failure keeps failing
* closed, so a real misconfiguration still surfaces instead of hiding behind a
* child process that may not serve hosts either.
*/
export function isDisabledServiceInstallError(error: unknown): boolean {
return (
error instanceof Error &&
error.message === "runtime_service_disabled_by_system"
);
}
export async function installServiceWithDisabledFallback(options: {
install(): Promise<void>;
restoreOwner(): Promise<void>;
reportDisabled(): Promise<void>;
startTransient(): Promise<void>;
}): Promise<"managed" | "transient"> {
try {
await options.install();
return "managed";
} catch (error) {
await options.restoreOwner();
if (!isDisabledServiceInstallError(error)) throw error;
await options.reportDisabled();
await options.startTransient();
return "transient";
}
}
/** What the user is told, instead of an internal error code.
*
* The codes are contractual and stay in the logs; this is the layer that turns
* them into something a person can act on. Every string says what happens to
* their memories, because that is the first thing anyone asks. */
export const STABLE_RUNTIME_USER_MESSAGES: Record<string, string> = {
installed_version_conflict:
"运行环境与这个安装包不一致,无法安全接管。请安装更新版本的 MemHub;你的记忆数据不会受到影响。",
distribution_downgrade_refused:
"已安装的运行环境比这个安装包更新,无法用旧安装包启动。请安装最新版本的 MemHub;你的记忆数据不会受到影响。",
install_current_unmanaged:
"运行环境的安装目录被改动过,无法安全接管。请重新安装 MemHub,你的记忆数据不会受到影响。",
packaged_runtime_not_current:
"新版本的运行环境没有装上,MemHub 不会用旧版本继续运行。请重新安装 MemHub;如果仍然失败,请把这个提示反馈给我们。你的记忆数据不会受到影响。",
sdk_migration_memory_unreadable:
"升级前核对发现,新版本还读不到你的全部记忆,所以没有切换数据源,旧数据保持原样可用。请把这个提示反馈给我们;原有记忆数据不会丢失。",
sdk_migration_model_profile_required:
"升级记忆数据格式需要先有可用的模型配置,用来核对新版本能否读回你的记忆。请在旧版本中完成模型配置后重启;你的记忆数据不会受到影响。",
sdk_migration_vector_profile_missing:
"你的记忆是用一个已删除的模型配置生成向量的,当前没有可用的模型配置能读回它们,所以没有升级。请在旧版本中重新添加那个模型配置并启用后重启;你的记忆数据不会受到影响。",
sdk_migration_model_secret_unavailable:
"模型密钥读不到(可能被系统钥匙串拒绝),无法核对新版本能否读回你的记忆。请允许 MemHub 访问钥匙串后重新启动;你的记忆数据不会受到影响。",
sdk_migration_secure_storage_unavailable:
"系统钥匙串暂时不可用,无法核对新版本能否读回你的记忆。请解锁钥匙串后重新启动;你的记忆数据不会受到影响。",
sdk_migration_disk_space_insufficient:
"磁盘空间不足,升级记忆数据格式时中断了。请至少腾出与记忆数据同等大小的可用空间(可在「关于本机 → 储存空间」查看),然后重新启动 MemHub;升级会自动继续,原有记忆数据不会丢失。",
sdk_migration_bundle_copy_failed:
"升级前备份没有写完,通常是磁盘空间不足。请清理磁盘空间后重新启动;原有记忆数据不会丢失。",
sdk_migration_cutover_failed:
"切换数据源时失败,原有记忆数据仍然完整可用。请重新启动重试;如果仍然失败,请把这个提示反馈给我们。",
sdk_migration_preflight_failed:
"升级前的检查没有通过,升级已停止。请重新启动重试;如果仍然失败,请把这个提示反馈给我们,原有记忆数据不会丢失。",
sdk_migration_status_unavailable:
"读不到升级状态,无法判断是否需要升级。请重新启动 MemHub;如果仍然失败,请重新安装,你的记忆数据不会受到影响。",
sdk_migration_response_invalid:
"升级过程返回了无法识别的内容,已停止。原有记忆数据不会丢失;请重新启动重试,如果仍然失败,请把这个提示反馈给我们。",
sdk_migration_incomplete:
"记忆数据格式升级没有完成,MemHub 暂时无法打开。请重新启动重试;如果仍然失败,请把这个提示反馈给我们,原有记忆数据不会丢失。",
runtime_service_not_ready:
"记忆服务仍在首次启动,请稍候后重试。你的记忆数据不会受到影响。",
desktop_start_failed:
"MemHub 启动失败。请重新启动;如果仍然打不开,请重新安装,你的记忆数据不会受到影响。",
};
export function stableRuntimeUserMessage(error: unknown): string {
const code = stableRuntimeErrorCode(error);
return (
STABLE_RUNTIME_USER_MESSAGES[code] ??
STABLE_RUNTIME_USER_MESSAGES.desktop_start_failed ??
""
);
}
/** What the startup dialog body says.
*
* A code we wrote copy for becomes a sentence. Every other code is shown as it
* is: this dialog is the last thing a person sees before the app closes, and an
* unexpected failure is more useful as the code support can look up than as a
* reassuring sentence that erases which failure actually fired. */
export function stableRuntimeFailureDetail(error: unknown): string {
if (!(error instanceof Error)) {
return STABLE_RUNTIME_USER_MESSAGES.desktop_start_failed ?? "";
}
return STABLE_RUNTIME_USER_MESSAGES[error.message] ?? error.message;
}
/** The installed Runtime must be at least the build this App carries. */
export async function requireCurrentRuntimeAtLeast(
installRoot: string,
buildNumber: number | undefined,
): Promise<void> {
if (buildNumber === undefined) return;
const manifest = await readFile(
path.join(installRoot, "current", "manifest.json"),
"utf8",
)
.then((text) => JSON.parse(text) as { build_number?: unknown })
.catch(() => null);
const installed = manifest?.build_number;
if (typeof installed !== "number" || installed < buildNumber) {
throw new Error("packaged_runtime_not_current");
}
}
export function startupFailureCause(error: unknown, home: string): string {
const text =
error instanceof Error ? `${error.name}: ${error.message}` : String(error);
return text
.split(home)
.join("~")
.replace(/[\r\n]+/g, " ")
.slice(0, 300);
}