nilometer 0.0.0-stage → 0.1.0

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

package/dist/core/plans/plan-prices.js

@@ -0,0 +1,128 @@
+/**
+ * @file Plan prices the user enters, shown beside API list price (D-027).
+ *
+ * Nothing on disk records which plan the user pays for or its price, so the user enters it with
+ * `plan-price set`. One row per month from which a price applies; entering the same month again
+ * replaces that row. These rows are user data: rebuilds never touch them, and they never belong in
+ * the repository.
+ */
+import { join } from "node:path";
+import { openDatabase, transaction } from "../db/database.js";
+import { DATABASE_FILE } from "../ingest/command.js";
+import { resolveDataDir } from "../install/locations.js";
+import { securePrivateDataDir } from "../install/private-files.js";
+/** An entry that can't be stored; its message names the field. */
+export class PlanPriceError extends Error {
+    /**
+     * Creates the error.
+     * @param message - What's wrong with the entry.
+     */
+    constructor(message) {
+        super(message);
+        this.name = "PlanPriceError";
+    }
+}
+/** `YYYY-MM` with a real month. */
+const MONTH = /^\d{4}-(0[1-9]|1[0-2])$/;
+/** Longest accepted plan name, so a pasted paragraph isn't stored as a name. */
+export const MAX_PLAN_NAME_LENGTH = 100;
+/**
+ * Validates an entry from user input.
+ * @param month - `YYYY-MM`.
+ * @param usd - Price text or number, e.g. `"200"` or `"17.50"`.
+ * @param planName - Plan name.
+ * @returns The entry with the name trimmed and the price as a number.
+ * @throws {PlanPriceError} If the month isn't `YYYY-MM`, the price isn't a finite non-negative
+ *   decimal number, or the name is empty or longer than {@link MAX_PLAN_NAME_LENGTH}.
+ */
+export function validatePlanPrice(month, usd, planName) {
+    if (!MONTH.test(month)) {
+        throw new PlanPriceError(`month must be YYYY-MM, got "${month}"`);
+    }
+    // Plain decimals only: "1e3", "0x10", and "" are numbers to Number() but not prices anyone types.
+    const text = String(usd).trim();
+    if (!/^\d+(\.\d+)?$/.test(text)) {
+        throw new PlanPriceError(`price must be a non-negative USD amount like 200 or 17.50, got "${text}"`);
+    }
+    const name = planName.trim();
+    if (name === "" || name.length > MAX_PLAN_NAME_LENGTH) {
+        throw new PlanPriceError(`plan name must be 1 to ${MAX_PLAN_NAME_LENGTH} characters`);
+    }
+    return { month, planName: name, usdPerMonth: Number(text) };
+}
+/**
+ * Stores an entry, replacing any row for the same month.
+ * @param db - Open, migrated database.
+ * @param entry - A validated entry.
+ * @param now - Clock for `entered_at`.
+ * @returns The row it replaced, or null when the month had none.
+ */
+export function setPlanPrice(db, entry, now) {
+    return transaction(db, () => {
+        const previous = readRow(db, entry.month);
+        db.prepare(`INSERT INTO plan_prices (effective_month, plan_name, usd_per_month, entered_at) VALUES (?, ?, ?, ?)
+       ON CONFLICT (effective_month) DO UPDATE SET
+         plan_name = excluded.plan_name, usd_per_month = excluded.usd_per_month, entered_at = excluded.entered_at`).run(entry.month, entry.planName, entry.usdPerMonth, now().toISOString());
+        return previous;
+    });
+}
+/**
+ * Lists every stored plan price, oldest month first.
+ * @param db - Open, migrated database.
+ * @returns The rows.
+ */
+export function listPlanPrices(db) {
+    return db
+        .prepare("SELECT effective_month, plan_name, usd_per_month, entered_at FROM plan_prices ORDER BY effective_month")
+        .all().map(toRow);
+}
+/**
+ * Converts a stored row to its API shape.
+ * @param row - The row from SQLite.
+ * @returns The plan price.
+ */
+function toRow(row) {
+    return {
+        month: row.effective_month,
+        planName: row.plan_name,
+        usdPerMonth: row.usd_per_month,
+        enteredAt: row.entered_at,
+    };
+}
+/**
+ * Reads one month's row.
+ * @param db - Open, migrated database.
+ * @param month - `YYYY-MM`.
+ * @returns The row, or null.
+ */
+function readRow(db, month) {
+    const row = db
+        .prepare("SELECT effective_month, plan_name, usd_per_month, entered_at FROM plan_prices WHERE effective_month = ?")
+        .get(month);
+    return row === undefined ? null : toRow(row);
+}
+/**
+ * Opens the data directory's database, runs an operation on it, and closes it.
+ * @param options - Where the database lives.
+ * @param use - The operation.
+ * @returns The database path, the operation's result, and any data paths made owner-only.
+ */
+export function withPlanDatabase(options, use) {
+    const dataDir = resolveDataDir({
+        home: options.home,
+        env: options.env,
+        override: options.dataDirOverride,
+    });
+    // A plan price can be entered before init or the first ingest has created the directory; either
+    // way the directory and its files end up owner-only (D-043).
+    const tightened = securePrivateDataDir(dataDir);
+    const databasePath = join(dataDir, DATABASE_FILE);
+    const db = openDatabase(databasePath, join(options.packageRoot, "core", "schema"));
+    try {
+        return { databasePath, result: use(db), tightened };
+    }
+    finally {
+        db.close();
+    }
+}
+//# sourceMappingURL=plan-prices.js.map