nilometer 0.0.0-stage → 0.2.0

package/dist/core/install/install.js

@@ -0,0 +1,185 @@
+/**
+ * @file The `init` and `uninstall` operations: register the status line hook, and reverse it.
+ *
+ * Implements README § How it works ("Chaining, not clobbering"), docs/development.md P1.3, and the
+ * `statusline-collector` skill's `init` steps: back up first, wrap an existing command, write
+ * atomically, be idempotent, and make `uninstall` restore the original exactly.
+ *
+ * Both operations return a plain outcome object. Wording for the user belongs to the CLI layer,
+ * so outcomes can be tested without asserting on prose.
+ */
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { backupSettings, locateSettings, readSettings, serializeSettings, writeFileAtomic, } from "../settings/settings-file.js";
+import { buildHookCommand, dataDirFromHookCommand, isCommandEntry, planInstall, planUninstall, } from "../settings/statusline.js";
+import { HOOK_RELATIVE_PATH, INSTALLED_HOOK_FILE, resolveDataDir } from "./locations.js";
+import { ensurePrivateDir, installHook, removePath } from "./private-files.js";
+import { readInstallRecord, removeInstallRecord, writeInstallRecord } from "./record.js";
+/** Layout used when `init` creates a settings file from scratch: what Claude Code writes. */
+export const DEFAULT_FORMAT = { indent: 2, trailingNewline: true };
+/**
+ * Resolves the settings path, data directory, and hook command for a run.
+ * @param options - Install options.
+ * @returns The three resolved locations.
+ */
+export function resolveTargets(options) {
+    const settingsPath = locateSettings({
+        home: options.home,
+        override: options.settingsOverride,
+        claudeConfigDir: options.env.CLAUDE_CONFIG_DIR,
+    });
+    const dataDir = resolveDataDir({
+        home: options.home,
+        env: options.env,
+        override: options.dataDirOverride,
+    });
+    // The command names the copy in the data directory, which nothing moves, not the one in the
+    // package, whose path changes with the Node version or the checkout's location (D-056).
+    const hookPath = join(dataDir, INSTALLED_HOOK_FILE);
+    const hookCommand = buildHookCommand(hookPath, dataDir);
+    return { settingsPath, dataDir, hookCommand, hookPath };
+}
+/**
+ * Registers the status line hook in Claude Code's settings. Safe to run repeatedly.
+ * @param options - Locations, environment, and clock.
+ * @returns What happened, with the paths involved.
+ * @throws {import("../settings/settings-file.js").SettingsError} If the settings file can't be
+ *   parsed; nothing is changed.
+ * @throws {import("./record.js").InstallRecordError} If an existing install record is corrupt.
+ */
+export function runInit(options) {
+    const { settingsPath, dataDir, hookCommand, hookPath } = resolveTargets(options);
+    const read = readSettings(settingsPath);
+    const settings = read.kind === "ok" ? read.settings : null;
+    const plan = planInstall(settings, hookCommand);
+    // Before the settings can name it, and on every run: a package whose hook changed needs the copy
+    // refreshed, even when the command itself is already correct (D-056).
+    const platform = options.platform ?? process.platform;
+    let hookRefreshed = false;
+    if (plan.action !== "refuse") {
+        ensurePrivateDir(dataDir, platform);
+        hookRefreshed = installHook(join(options.packageRoot, HOOK_RELATIVE_PATH), hookPath, platform);
+    }
+    const base = { settingsPath, dataDir, hookRefreshed };
+    switch (plan.action) {
+        case "none":
+            return { ...base, action: "already-installed", backupPath: null, wrappedCommand: wrapped() };
+        case "refuse":
+            return { ...base, action: "refused-unsupported", backupPath: null, wrappedCommand: null };
+        case "update-command": {
+            // The record lives in the data directory. If this data directory has none, the hook was
+            // installed with another one, and moving on would lose the user's original command.
+            if (readInstallRecord(dataDir) === null) {
+                return { ...base, action: "refused-other-install", backupPath: null, wrappedCommand: null };
+            }
+            const backupPath = backupSettings(settingsPath, options.now);
+            writeSettings(settingsPath, plan.settings, read.kind === "ok" ? read.format : DEFAULT_FORMAT);
+            return { ...base, action: "updated", backupPath, wrappedCommand: wrapped() };
+        }
+        case "install": {
+            const backupPath = backupSettings(settingsPath, options.now);
+            // Record first: once settings point at the hook, its next run must find the original command.
+            writeInstallRecord(dataDir, {
+                version: 1,
+                settingsPath,
+                settingsExisted: read.kind === "ok",
+                backupPath,
+                original: plan.original,
+                installedAt: options.now.toISOString(),
+            });
+            writeSettings(settingsPath, plan.settings, read.kind === "ok" ? read.format : DEFAULT_FORMAT);
+            return { ...base, action: "installed", backupPath, wrappedCommand: wrapped() };
+        }
+    }
+    /**
+     * Reads which original command the hook wraps, from the record in this data directory.
+     * @returns The wrapped command, or null if there is none.
+     */
+    function wrapped() {
+        return readInstallRecord(dataDir)?.original?.command ?? null;
+    }
+}
+/**
+ * Serializes settings and writes them atomically, creating the directory if needed.
+ * @param path - Settings file path.
+ * @param settings - Settings to write.
+ * @param format - Layout to use.
+ */
+function writeSettings(path, settings, format) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileAtomic(path, serializeSettings(settings, format));
+}
+/**
+ * Removes the hook from Claude Code's settings and restores what `init` replaced.
+ * Collected data (spool, error log) is kept.
+ * @param options - Locations, environment, and clock.
+ * @returns What happened, with the paths involved.
+ * @throws {import("../settings/settings-file.js").SettingsError} If the settings file can't be
+ *   parsed; nothing is changed.
+ * @throws {import("./record.js").InstallRecordError} If the install record is corrupt.
+ */
+export function runUninstall(options) {
+    const targets = resolveTargets(options);
+    let dataDir = targets.dataDir;
+    let record = readInstallRecord(dataDir);
+    // The record knows which file was changed, even if flags or environment differ today.
+    const settingsPath = record?.settingsPath ?? targets.settingsPath;
+    const read = readSettings(settingsPath);
+    if (record === null && read.kind === "ok") {
+        // `init --data-dir X` followed by a plain `uninstall` looks for the record in the default
+        // directory and doesn't find it. Without the record, the plan below would delete the user's
+        // own status line instead of restoring it, so recover the directory from the command that's
+        // about to be removed — the one other place `init` wrote that path down (D-050).
+        const entry = read.settings["statusLine"];
+        const installedAt = isCommandEntry(entry) ? dataDirFromHookCommand(entry.command) : null;
+        const recovered = installedAt === null ? null : readInstallRecord(installedAt);
+        if (installedAt !== null && recovered !== null) {
+            record = recovered;
+            dataDir = installedAt;
+        }
+    }
+    const settings = read.kind === "ok" ? read.settings : null;
+    const plan = planUninstall(settings, record?.original ?? null);
+    const base = {
+        settingsPath,
+        dataDir,
+        recordMissing: record === null,
+        restoredCommand: record?.original?.command ?? null,
+        notRemoved: [],
+    };
+    if (plan.action === "none" || read.kind !== "ok") {
+        const action = plan.action === "none" ? plan.reason : "not-installed";
+        return { ...base, action, backupPath: null, exactBytes: false };
+    }
+    const backupPath = backupSettings(settingsPath, options.now);
+    // init created this file and nothing else was added since: the faithful undo is no file at all.
+    if (record !== null && !record.settingsExisted && Object.keys(plan.settings).length === 0) {
+        // Verified, not assumed: a removal that silently does nothing would leave the hook registered
+        // while `uninstall` reported success, and it would keep recording (D-061).
+        const gone = removePath(settingsPath);
+        removeInstallRecord(dataDir);
+        return {
+            ...base,
+            action: "removed-settings-file",
+            backupPath,
+            exactBytes: true,
+            notRemoved: gone ? [] : [settingsPath],
+        };
+    }
+    // If the result equals the pre-install file, write its exact bytes: a re-serialization could
+    // differ in whitespace the JSON parser discarded.
+    const original = record?.backupPath ?? null;
+    if (original !== null && existsSync(original)) {
+        const originalRaw = readFileSync(original, "utf8");
+        if (isDeepStrictEqual(JSON.parse(originalRaw), plan.settings)) {
+            writeFileAtomic(settingsPath, originalRaw);
+            removeInstallRecord(dataDir);
+            return { ...base, action: "restored", backupPath, exactBytes: true };
+        }
+    }
+    writeFileAtomic(settingsPath, serializeSettings(plan.settings, read.format));
+    removeInstallRecord(dataDir);
+    return { ...base, action: "restored", backupPath, exactBytes: false };
+}
+//# sourceMappingURL=install.js.map

package/dist/core/install/locations.js

@@ -0,0 +1,89 @@
+/**
+ * @file Where the tool keeps its data and where the hook script lives.
+ *
+ * Implements docs/development.md P1.3 and the `statusline-collector` skill ("Spool path: under the tool's data
+ * directory, never inside `~/.claude`"). The data directory holds the spool, the hook's error log,
+ * and the install record; later phases add the database there.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { expandHome } from "../util/paths.js";
+/** Directory name used under the XDG data home. */
+export const DATA_DIR_NAME = "nilometer";
+/**
+ * Resolves the tool's data directory.
+ *
+ * Order: `--data-dir`, then `$NILOMETER_HOME`, then `$XDG_DATA_HOME/nilometer`,
+ * then `~/.local/share/nilometer`. XDG's default is used on macOS too, so every platform
+ * has one documented location instead of a per-OS guess.
+ * @param options - Home directory, environment, and flag override.
+ * @returns An absolute data directory path (it may not exist yet).
+ */
+export function resolveDataDir(options) {
+    const explicit = [options.override, options.env.NILOMETER_HOME].find((value) => value !== undefined && value !== "");
+    if (explicit !== undefined) {
+        // Always absolute (D-050): `init` writes this path into the status line command, and the hook
+        // resolves a relative one against whatever project Claude Code runs in. A folder committed to a
+        // repository could then supply the wrapped command the hook executes.
+        return resolve(expandHome(explicit, options.home));
+    }
+    const xdg = options.env.XDG_DATA_HOME;
+    // XDG says relative values are invalid and must be ignored.
+    if (xdg !== undefined && xdg.startsWith("/")) {
+        return join(xdg, DATA_DIR_NAME);
+    }
+    return join(options.home, ".local", "share", DATA_DIR_NAME);
+}
+/** Path of the hook script relative to the package root. */
+export const HOOK_RELATIVE_PATH = join("hooks", "statusline.sh");
+/**
+ * The hook's name inside the data directory, where `init` installs a copy of it (D-056).
+ *
+ * The status line command has to name a path that nothing moves. A path inside the package moves
+ * whenever the package does: a global npm install lives under the Node version in use, so upgrading
+ * Node leaves the command pointing at a file that no longer exists, and readings stop with no
+ * error. The data directory is chosen by the user and never moves on its own.
+ */
+export const INSTALLED_HOOK_FILE = "statusline.sh";
+/**
+ * Finds the package root by walking up from a directory until `hooks/statusline.sh` and
+ * `package.json` both exist.
+ *
+ * Works whether code runs from source (`core/install/`) or from the build (`dist/core/install/`),
+ * because the build doesn't copy the shell script.
+ * @param startDir - Directory to start from, usually this module's own directory.
+ * @param exists - File existence check, injectable for tests.
+ * @returns The package root directory.
+ * @throws {Error} If no ancestor contains both files.
+ */
+export function findPackageRoot(startDir, exists = existsSync) {
+    let current = startDir;
+    for (;;) {
+        if (exists(join(current, "package.json")) && exists(join(current, HOOK_RELATIVE_PATH))) {
+            return current;
+        }
+        const parent = dirname(current);
+        // dirname of the filesystem root is the root itself: nowhere left to look.
+        if (parent === current) {
+            throw new Error(`could not find ${HOOK_RELATIVE_PATH} above ${startDir}`);
+        }
+        current = parent;
+    }
+}
+/**
+ * Reads the package's own version, for `nilometer --version` (G5.5).
+ * @param packageRoot - From {@link findPackageRoot}.
+ * @param read - Reads a file's text, injectable for tests.
+ * @returns The `version` in its package.json, or `unknown` when that can't be read: the version is
+ *   only ever printed, so a damaged file shouldn't stop a command.
+ */
+export function packageVersion(packageRoot, read = (path) => readFileSync(path, "utf8")) {
+    try {
+        const { version } = JSON.parse(read(join(packageRoot, "package.json")));
+        return typeof version === "string" ? version : "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+//# sourceMappingURL=locations.js.map

package/dist/core/install/private-files.js

@@ -0,0 +1,259 @@
+/**
+ * @file Owner-only storage for Nilometer's data (D-043).
+ *
+ * The database holds copies of session log lines (prompts, code, file paths) and the spool holds
+ * status line payloads. Claude Code keeps its own transcripts owner-only (`~/.claude` 0700,
+ * transcripts 0600; observed 2026-09-13), so Nilometer's copies must be no easier to read:
+ * directories 0700, files 0600. New paths are created that way, and existing installs are tightened
+ * the next time Nilometer opens them. Nothing here ever loosens a mode.
+ *
+ * On Windows none of this applies (D-049): Node's `chmod` there only toggles the read-only attribute,
+ * so a mode can't be tightened and reads back as 666 whatever was set. Tightening is skipped rather
+ * than reported as done, and the data relies on the user profile folder's permissions.
+ */
+import { chmodSync, closeSync, existsSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, rmdirSync, unlinkSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+/** Mode for directories Nilometer owns. */
+export const PRIVATE_DIR_MODE = 0o700;
+/** Mode for files Nilometer writes. */
+export const PRIVATE_FILE_MODE = 0o600;
+/** Files Nilometer keeps in its data directory; their presence also identifies one. */
+export const DATA_DIR_FILES = [
+    "usage.db",
+    "usage.db-wal",
+    "usage.db-shm",
+    "statusline.spool.jsonl",
+    "hook-errors.log",
+    "install-record.json",
+    "wrapped-command",
+    "statusline.sh",
+];
+/** Subdirectories of the data directory whose files are all Nilometer's. */
+export const DATA_DIR_SUBDIRS = ["reports"];
+/**
+ * Tells whether POSIX permission modes mean anything on a platform.
+ * @param platform - A `process.platform` value.
+ * @returns False on Windows, where `chmod` only toggles read-only (D-049).
+ */
+export function hasPosixModes(platform) {
+    return platform !== "win32";
+}
+/**
+ * Removes group and other permission bits from an existing path, never loosening anything.
+ * @param path - A file or directory.
+ * @param platform - The platform, for tests; defaults to this one.
+ * @returns True when the mode changed; false when it was already owner-only, is missing, is a
+ *   symbolic link (chmod would follow the link and change a file Nilometer doesn't own), or the
+ *   platform has no POSIX modes.
+ */
+export function tightenMode(path, platform = process.platform) {
+    if (!hasPosixModes(platform) || !existsSync(path)) {
+        return false;
+    }
+    const stat = lstatSync(path);
+    if (stat.isSymbolicLink()) {
+        return false;
+    }
+    const mode = stat.mode & 0o777;
+    if ((mode & 0o077) === 0) {
+        return false;
+    }
+    chmodSync(path, mode & 0o700);
+    return true;
+}
+/**
+ * Creates a directory owner-only if it doesn't exist.
+ * @param dir - The directory.
+ * @param platform - The platform, for tests; defaults to this one.
+ * @returns True when this call created it.
+ */
+export function ensurePrivateDir(dir, platform = process.platform) {
+    if (existsSync(dir)) {
+        return false;
+    }
+    mkdirSync(dir, { recursive: true, mode: PRIVATE_DIR_MODE });
+    if (hasPosixModes(platform)) {
+        // mkdir's mode is filtered by the umask, and only the last component gets it exactly; chmod makes it certain.
+        chmodSync(dir, PRIVATE_DIR_MODE);
+    }
+    return true;
+}
+/**
+ * Creates an empty file owner-only if it doesn't exist, so a library that then opens it keeps that mode.
+ * @param path - The file.
+ * @param platform - The platform, for tests; defaults to this one.
+ * @returns True when this call created it.
+ * @throws {Error} If the file can't be created for a reason other than already existing.
+ */
+export function ensurePrivateFile(path, platform = process.platform) {
+    if (existsSync(path)) {
+        return false;
+    }
+    // "wx": another process creating it first is fine; this only needs the file to exist privately.
+    try {
+        closeSync(openSync(path, "wx", PRIVATE_FILE_MODE));
+    }
+    catch (error) {
+        if (error.code !== "EEXIST") {
+            throw error;
+        }
+        return false;
+    }
+    if (hasPosixModes(platform)) {
+        chmodSync(path, PRIVATE_FILE_MODE);
+    }
+    return true;
+}
+/**
+ * Makes a data directory and everything Nilometer keeps in it owner-only.
+ *
+ * A directory created here is private from the start. An existing directory is tightened only if it
+ * already holds a Nilometer file, so pointing `--data-dir` at a shared folder by mistake never
+ * changes that folder's permissions; Nilometer's own files inside it are still tightened.
+ * @param dataDir - The data directory.
+ * @param platform - The platform, for tests; defaults to this one.
+ * @returns Paths whose permissions were tightened (empty for a new or already private directory,
+ *   and always empty on Windows, where there's nothing to tighten; D-049).
+ */
+export function securePrivateDataDir(dataDir, platform = process.platform) {
+    if (ensurePrivateDir(dataDir, platform) || !hasPosixModes(platform)) {
+        return [];
+    }
+    const tightened = [];
+    const owned = DATA_DIR_FILES.some((name) => existsSync(join(dataDir, name)));
+    if (owned && tightenMode(dataDir)) {
+        tightened.push(dataDir);
+    }
+    for (const name of DATA_DIR_FILES) {
+        const path = join(dataDir, name);
+        if (tightenMode(path)) {
+            tightened.push(path);
+        }
+    }
+    for (const sub of DATA_DIR_SUBDIRS) {
+        const dir = join(dataDir, sub);
+        if (!existsSync(dir) || lstatSync(dir).isSymbolicLink()) {
+            continue;
+        }
+        if (tightenMode(dir)) {
+            tightened.push(dir);
+        }
+        for (const entry of readdirSync(dir).sort()) {
+            const path = join(dir, entry);
+            if (tightenMode(path)) {
+                tightened.push(path);
+            }
+        }
+    }
+    return tightened;
+}
+/**
+ * Describes a tightening for the user, once, when it happens.
+ * @param tightened - Paths from {@link securePrivateDataDir}.
+ * @returns One line, or null when nothing changed.
+ */
+export function describeTightened(tightened) {
+    if (tightened.length === 0) {
+        return null;
+    }
+    const noun = tightened.length === 1 ? "path was" : "paths were";
+    return `Made Nilometer's data owner-only: ${tightened.length} ${noun} readable by other accounts on this computer.`;
+}
+/**
+ * Installs the hook script into the data directory, replacing an older copy.
+ *
+ * The status line command names this copy, not the one in the package, so upgrading Node or moving
+ * the checkout can't leave the command pointing at nothing (D-056). Written through a temporary
+ * file and a rename, so a hook that is running during an upgrade never reads a half-written script.
+ * @param source - The hook inside the package.
+ * @param destination - Where it goes, inside the data directory.
+ * @param platform - The platform, for tests; defaults to this one.
+ * @returns True when the copy changed, so `init` can say the hook was refreshed.
+ * @throws {Error} If the destination is a symbolic link. Its contents are executed on every reply,
+ *   and `init` only ever writes a regular file there (D-050).
+ */
+export function installHook(source, destination, platform = process.platform) {
+    if (existsSync(destination) && lstatSync(destination).isSymbolicLink()) {
+        throw new Error(`${destination} is a symbolic link; refusing to write the hook through it`);
+    }
+    const wanted = readFileSync(source);
+    if (existsSync(destination) && readFileSync(destination).equals(wanted)) {
+        return false;
+    }
+    // Same directory as the destination, so the rename is atomic.
+    const temp = `${destination}.tmp-${process.pid}-${Date.now()}`;
+    try {
+        writeFileSync(temp, wanted, { mode: PRIVATE_FILE_MODE });
+        if (hasPosixModes(platform)) {
+            // writeFile's mode is filtered by the umask; chmod makes it exact.
+            chmodSync(temp, PRIVATE_FILE_MODE);
+        }
+        renameSync(temp, destination);
+    }
+    catch (error) {
+        rmSync(temp, { force: true });
+        throw error;
+    }
+    return true;
+}
+/**
+ * Removes a file or directory tree, then checks that it is gone.
+ *
+ * Not `rmSync`: on Windows it silently removes nothing when any part of the path holds a non-ASCII
+ * character, and `force: true` hides that it did nothing (observed on Node 24.12, win32; not
+ * reproducible on macOS Node 24.21). `unlinkSync` and `rmdirSync` work on those same paths, so the
+ * tree is walked and taken apart with them. The check afterwards is the part that matters: a
+ * deletion this code cannot verify is reported as a survivor, never as a success (D-061).
+ * @param path - The file or directory to remove.
+ * @returns True when nothing is at the path afterwards.
+ */
+export function removePath(path) {
+    try {
+        if (!existsSync(path)) {
+            return true;
+        }
+        if (lstatSync(path).isDirectory()) {
+            for (const name of readdirSync(path)) {
+                removePath(join(path, name));
+            }
+            rmdirSync(path);
+        }
+        else {
+            unlinkSync(path);
+        }
+    }
+    catch {
+        // Whatever went wrong, the answer is the same question: is it still there?
+    }
+    return !existsSync(path);
+}
+/**
+ * Removes the files Nilometer keeps in a data directory, and the directory if nothing else is left.
+ *
+ * Only the names Nilometer writes are removed ({@link DATA_DIR_FILES}, {@link DATA_DIR_SUBDIRS}),
+ * and only what is confirmed gone is reported as removed.
+ * A user can point `--data-dir` at a folder that holds other things, and deleting a directory
+ * because of what it is called would take those with it (D-043 leaves shared folders alone). What
+ * was left behind is reported rather than removed (R2.5).
+ * @param dataDir - The data directory.
+ * @returns What was removed and what was left.
+ */
+export function deleteDataFiles(dataDir) {
+    const removed = [];
+    const failed = [];
+    if (!existsSync(dataDir)) {
+        return { removed, failed, directoryRemoved: false, kept: [] };
+    }
+    const ours = new Set([...DATA_DIR_FILES, ...DATA_DIR_SUBDIRS]);
+    for (const name of readdirSync(dataDir)) {
+        if (ours.has(name)) {
+            // Only what is confirmed gone counts as removed: claiming otherwise is the defect (D-061).
+            (removePath(join(dataDir, name)) ? removed : failed).push(name);
+        }
+    }
+    const left = readdirSync(dataDir);
+    const kept = left.filter((name) => !failed.includes(name));
+    const directoryRemoved = left.length === 0 && removePath(dataDir);
+    return { removed, failed, directoryRemoved, kept };
+}
+//# sourceMappingURL=private-files.js.map

package/dist/core/install/record.js

@@ -0,0 +1,103 @@
+/**
+ * @file The install record: what `init` changed, so `uninstall` can put it back.
+ *
+ * Implements the `statusline-collector` skill's `init`/`uninstall` rules. Two files in the data
+ * directory:
+ * - `install-record.json`: the settings path, whether it existed, the backup path, and the user's
+ *   original `statusLine` entry (or null).
+ * - `wrapped-command`: the original command as plain text, the only thing the shell hook reads.
+ *   It exists only when there was an original command.
+ */
+import { existsSync, lstatSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { ensurePrivateDir, removePath, tightenMode } from "./private-files.js";
+import { writeFileAtomic } from "../settings/settings-file.js";
+import { isCommandEntry } from "../settings/statusline.js";
+/** File name of the install record inside the data directory. */
+export const RECORD_FILE = "install-record.json";
+/** File name of the wrapped command the hook runs (see hooks/statusline.sh). */
+export const WRAPPED_COMMAND_FILE = "wrapped-command";
+/** An install record that exists but can't be trusted. Nothing is changed when this is raised. */
+export class InstallRecordError extends Error {
+    /**
+     * Creates an install record error.
+     * @param path - Path of the unreadable record.
+     * @param reason - What is wrong with it.
+     */
+    constructor(path, reason) {
+        super(`install record ${path} is unusable: ${reason}`);
+        this.name = "InstallRecordError";
+    }
+}
+/**
+ * Writes the install record and the hook's wrapped-command file.
+ *
+ * Called before settings are changed, so the hook finds the user's original command on its very
+ * first run and the status bar never shows the default in between.
+ * @param dataDir - The tool's data directory; created if missing.
+ * @param record - The record to write.
+ */
+export function writeInstallRecord(dataDir, record) {
+    ensurePrivateDir(dataDir);
+    writeFileAtomic(join(dataDir, RECORD_FILE), `${JSON.stringify(record, null, 2)}\n`);
+    const wrappedPath = join(dataDir, WRAPPED_COMMAND_FILE);
+    if (record.original === null) {
+        // A stale file from an earlier install would make the hook run a command that's gone.
+        removePath(wrappedPath);
+    }
+    else {
+        writeFileAtomic(wrappedPath, record.original.command);
+    }
+    // writeFileAtomic keeps an existing file's mode; an install from before D-043 may have left 0644.
+    tightenMode(join(dataDir, RECORD_FILE));
+    tightenMode(wrappedPath);
+}
+/**
+ * Reads the install record, validating its shape.
+ * @param dataDir - The tool's data directory.
+ * @returns The record, or null if none exists.
+ * @throws {InstallRecordError} If the file exists but isn't a valid record.
+ */
+export function readInstallRecord(dataDir) {
+    const path = join(dataDir, RECORD_FILE);
+    if (!existsSync(path)) {
+        return null;
+    }
+    // The record decides what `uninstall` writes back into settings.json, so a link to a file
+    // Nilometer didn't write is refused rather than followed (D-050).
+    if (lstatSync(path).isSymbolicLink()) {
+        throw new InstallRecordError(path, "a symbolic link, not the file init wrote");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        throw new InstallRecordError(path, "not valid JSON");
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new InstallRecordError(path, "not a JSON object");
+    }
+    const record = parsed;
+    // Validate every field uninstall relies on; a guess here could restore the wrong settings.
+    const valid = record["version"] === 1 &&
+        typeof record["settingsPath"] === "string" &&
+        typeof record["settingsExisted"] === "boolean" &&
+        (record["backupPath"] === null || typeof record["backupPath"] === "string") &&
+        (record["original"] === null || isCommandEntry(record["original"])) &&
+        typeof record["installedAt"] === "string";
+    if (!valid) {
+        throw new InstallRecordError(path, "missing or mistyped fields");
+    }
+    return record;
+}
+/**
+ * Removes the install record and wrapped-command file, keeping all collected data.
+ * @param dataDir - The tool's data directory.
+ */
+export function removeInstallRecord(dataDir) {
+    // removePath, not rmSync: rmSync silently removes nothing on a non-ASCII Windows path (D-061).
+    removePath(join(dataDir, RECORD_FILE));
+    removePath(join(dataDir, WRAPPED_COMMAND_FILE));
+}
+//# sourceMappingURL=record.js.map