Python
/** Keep the managed bin directory on the user's PATH.
*
* The product requirement is "装完即短指令可用": after `memhub install` the
* user must be able to type `memhub ...` without exporting anything. The
* installer already creates the `memhub`/`one-memory` links in `binDir`; this
* module makes `binDir` reachable from a NEW shell.
*
* Design rules, deliberately conservative:
* - Only a marked, single block is ever written. We never rewrite or reorder
* the user's existing profile content.
* - Idempotent: re-running installs the same block once.
* - Removable: uninstall removes exactly the block we wrote, and only if it
* still matches byte-for-byte.
* - A profile that already puts binDir on PATH is left completely alone.
* - Reject path escapes: binDir must be absolute and newline-free, and the
* profile must live in the user's home.
*/
import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
import path from "node:path";
const BEGIN = "# >>> memhub PATH >>>";
const END = "# <<< memhub PATH <<<";
export interface ShellPathPlan {
schema_version: 1;
status: "present" | "create" | "blocked";
blocked_reason: string | null;
bin_directory: string;
profile_path: string;
/** The exact block this tool owns, or null when there is nothing to write. */
block: string | null;
/** True when the caller explicitly opted out of profile edits. Recorded so
* apply can re-verify the same plan instead of re-planning into a write. */
disabled?: boolean;
}
export interface ShellPathReceipt extends ShellPathPlan {
created: boolean;
}
/** The profile a login shell on this platform will read for `PATH`.
*
* macOS defaults to zsh, so `~/.zprofile` is the login-shell file; Linux (and
* unknown POSIX) use `~/.profile`, which is the portable choice. Windows has no
* POSIX profile and stays blocked until a real PATH story is verified.
*/
function defaultProfilePath(
platform: NodeJS.Platform,
home: string,
): string | null {
if (platform === "darwin") return path.join(home, ".zprofile");
if (platform === "linux") return path.join(home, ".profile");
return null;
}
function blockFor(binDirectory: string): string {
return [
BEGIN,
`# Added by memhub install. Remove with: memhub uninstall --yes`,
`case ":$PATH:" in`,
` *":${binDirectory}:"*) ;;`,
` *) PATH="${binDirectory}:$PATH" ;;`,
`esac`,
`export PATH`,
END,
"",
].join("\n");
}
/** The block plus the separator that positions it, so removing it restores the
* original file byte-for-byte regardless of the original's trailing newline. */
function ownedBlock(existing: string | null, binDirectory: string): string {
const separator =
existing === null || existing === "" || existing.endsWith("\n") ? "" : "\n";
return `${separator}${blockFor(binDirectory)}`;
}
export async function planShellPath(options: {
binDirectory: string;
home: string;
platform?: NodeJS.Platform;
profilePath?: string;
/** Opt out of profile edits entirely (isolated installs, CI, scripted
* installs that manage PATH themselves). Reported as `present` with no block
* so no caller is tempted to write one later. */
disabled?: boolean;
}): Promise<ShellPathPlan> {
const platform = options.platform ?? process.platform;
const paths = platform === "win32" ? path.win32 : path.posix;
const binDirectory = options.binDirectory;
const profilePath =
options.profilePath ?? defaultProfilePath(platform, options.home);
if (options.disabled === true) {
return {
schema_version: 1,
status: "present",
blocked_reason: null,
bin_directory: binDirectory,
profile_path: profilePath ?? "",
block: null,
disabled: true,
};
}
const blocked = (reason: string, target: string): ShellPathPlan => ({
schema_version: 1,
status: "blocked",
blocked_reason: reason,
bin_directory: target,
profile_path: profilePath ?? "",
block: null,
});
if (
!paths.isAbsolute(binDirectory) ||
binDirectory.includes("\0") ||
/[\r\n]/.test(binDirectory)
) {
return blocked("bin_directory_unusable", binDirectory);
}
if (profilePath === null) {
return blocked("shell_path_not_verified", binDirectory);
}
const home = paths.resolve(options.home);
const resolvedProfile = paths.resolve(profilePath);
// Never write outside the user's own profile directory.
if (paths.dirname(resolvedProfile) !== home) {
return blocked("profile_outside_home", binDirectory);
}
const existing = await readProfile(resolvedProfile);
const block = ownedBlock(existing, binDirectory);
if (existing === null) {
return {
schema_version: 1,
status: "create",
blocked_reason: null,
bin_directory: binDirectory,
profile_path: resolvedProfile,
block,
};
}
if (existing.includes(block)) {
return {
schema_version: 1,
status: "present",
blocked_reason: null,
bin_directory: binDirectory,
profile_path: resolvedProfile,
block,
};
}
// A different-but-equivalent membership already exists (user manages PATH).
if (profileExportsDirectory(existing, binDirectory)) {
return {
schema_version: 1,
status: "present",
blocked_reason: null,
bin_directory: binDirectory,
profile_path: resolvedProfile,
block: null,
};
}
return {
schema_version: 1,
status: "create",
blocked_reason: null,
bin_directory: binDirectory,
profile_path: resolvedProfile,
block,
};
}
export async function applyShellPath(
plan: ShellPathPlan,
): Promise<ShellPathReceipt> {
if (plan.status === "blocked") {
throw new Error(plan.blocked_reason ?? "shell_path_blocked");
}
const refreshed = await planShellPath({
binDirectory: plan.bin_directory,
home: path.dirname(plan.profile_path),
profilePath: plan.profile_path,
...(plan.disabled ? { disabled: true } : {}),
});
if (refreshed.status !== plan.status || refreshed.block !== plan.block) {
throw new Error("shell_path_plan_stale");
}
if (plan.status === "present") {
return { ...plan, created: false };
}
const existing = (await readProfile(plan.profile_path)) ?? "";
const block = plan.block ?? ownedBlock(existing, plan.bin_directory);
await writeProfileAtomically(plan.profile_path, `${existing}${block}`);
return { ...plan, created: true };
}
export async function removeShellPath(
plan: ShellPathPlan,
): Promise<"removed" | "not-present"> {
const existing = await readProfile(plan.profile_path);
if (existing === null) return "not-present";
const marker = plan.block ?? ownedBlock(existing, plan.bin_directory);
const index = existing.indexOf(marker);
if (index === -1) return "not-present";
const before = existing.slice(0, index);
const after = existing.slice(index + marker.length);
await writeProfileAtomically(plan.profile_path, `${before}${after}`);
return "removed";
}
async function readProfile(profilePath: string): Promise<string | null> {
try {
const info = await stat(profilePath);
if (!info.isFile()) return null;
return await readFile(profilePath, "utf8");
} catch {
return null;
}
}
async function writeProfileAtomically(
profilePath: string,
content: string,
): Promise<void> {
// A fresh `--home` may not exist yet; create it (owner-only) before writing
// the temp profile, otherwise the write fails with a raw ENOENT. Surface a
// structured code for any other failure.
await mkdir(path.dirname(profilePath), {
recursive: true,
mode: 0o700,
}).catch(() => {
throw new Error("shell_path_home_unwritable");
});
const temporary = `${profilePath}.memhub.${process.pid}.tmp`;
try {
await writeFile(temporary, content, { encoding: "utf8", mode: 0o644 });
await rename(temporary, profilePath);
} catch (error) {
await rm(temporary, { force: true });
throw error;
}
}
/** True when the profile already exports `directory` on PATH in some form. */
function profileExportsDirectory(content: string, directory: string): boolean {
for (const raw of content.split("\n")) {
const line = raw.trim();
if (line === "" || line.startsWith("#")) continue;
if (!/\bPATH\b/.test(line) && !/\bpath\b/.test(line)) continue;
// Tokens are split on the separators that can appear inside a PATH
// assignment; the directory counts only as a whole `:`-delimited element,
// so `/x/bin-extra` never matches `/x/bin`.
const tokens = line.split(/[:\s="']+/);
if (tokens.includes(directory)) return true;
}
return false;
}
export function renderShellPathPlan(plan: ShellPathPlan): string {
if (plan.status === "blocked") {
return `PATH 未配置:${plan.blocked_reason}\n`;
}
if (plan.status === "present") {
return `PATH 已包含 ${plan.bin_directory}(${plan.profile_path})\n`;
}
return `将在 ${plan.profile_path} 添加 PATH 条目:${plan.bin_directory}\n`;
}