nilometer 0.0.0-stage → 0.1.0

package/dist/core/plans/repository-aliases.js

@@ -0,0 +1,136 @@
+/**
+ * @file Repository aliases the user enters, so a renamed or moved project counts as one (D-092).
+ *
+ * Nothing in the logs links a repository's old path to its new one (D-028). The user enters the
+ * link with `nilometer alias set <old> <new>`; `request_repositories` then counts the old path's
+ * requests under the new one and keeps the old path beside each, so every number still traces back.
+ * Like plan prices, these rows are user data: rebuilds never touch them.
+ */
+import { isAbsolute, posix, win32 } from "node:path";
+import { transaction } from "../db/database.js";
+/** An alias that can't be stored or removed; its message says why. */
+export class RepositoryAliasError extends Error {
+    /**
+     * Creates the error.
+     * @param message - What's wrong.
+     */
+    constructor(message) {
+        super(message);
+        this.name = "RepositoryAliasError";
+    }
+}
+/**
+ * Turns a path the user typed into the form repositories are stored in: `~/` expanded against the
+ * home directory, and no trailing separator. A Windows path keeps its drive letter (D-049).
+ * @param path - The path as typed.
+ * @param home - The home directory, for `~/`.
+ * @returns The path, ready to compare with stored repositories.
+ * @throws {RepositoryAliasError} If it isn't absolute after `~/` is expanded.
+ */
+export function normalizeRepositoryPath(path, home) {
+    const typed = path.trim();
+    const expanded = typed === "~" || typed.startsWith("~/") ? home + typed.slice(1) : typed;
+    if (!isAbsolute(expanded) && !win32.isAbsolute(expanded) && !posix.isAbsolute(expanded)) {
+        throw new RepositoryAliasError(`a repository path must be absolute, got "${typed}"`);
+    }
+    // A trailing separator would never match a stored repository; the root itself keeps its own.
+    return expanded.length > 1 ? expanded.replace(/[\\/]+$/, "") : expanded;
+}
+/**
+ * Validates an entry from user input.
+ * @param from - The old path, as typed.
+ * @param to - The new path, as typed.
+ * @param home - The home directory, for `~/`.
+ * @returns Both paths normalized.
+ * @throws {RepositoryAliasError} If either isn't absolute, or both are the same path.
+ */
+export function validateAlias(from, to, home) {
+    const entry = {
+        from: normalizeRepositoryPath(from, home),
+        to: normalizeRepositoryPath(to, home),
+    };
+    if (entry.from === entry.to) {
+        throw new RepositoryAliasError(`an alias joins two different paths; both are ${entry.from}`);
+    }
+    return entry;
+}
+/**
+ * Stores an alias, replacing any for the same old path.
+ * @param db - Open, migrated database.
+ * @param entry - A validated entry.
+ * @param now - Clock for `entered_at`.
+ * @returns The alias it replaced, or null when the old path had none.
+ * @throws {RepositoryAliasError} If no request is attributed to the old path, or the alias would
+ *   chain: its new path is another alias's old one, or its old path is another alias's new one.
+ */
+export function setAlias(db, entry, now) {
+    return transaction(db, () => {
+        // Attributed before any alias: the path a request had, whether or not an alias moved it since.
+        const recorded = db
+            .prepare("SELECT 1 FROM request_repositories WHERE COALESCE(aliased_from, repository) = ? LIMIT 1")
+            .get(entry.from);
+        if (recorded === undefined) {
+            throw new RepositoryAliasError(`no Claude Code request is recorded under ${entry.from}; nilometer report --json lists each repository's full path`);
+        }
+        // One step only: a chain or a loop would make "counts under" depend on the order rows are read.
+        const chained = db
+            .prepare(`SELECT from_repository, to_repository FROM repository_aliases
+         WHERE (from_repository = :to) OR (to_repository = :from AND from_repository <> :from)
+         LIMIT 1`)
+            .get({ from: entry.from, to: entry.to });
+        if (chained !== undefined) {
+            throw new RepositoryAliasError(`aliases go one step: ${chained.from_repository} already counts under ${chained.to_repository}`);
+        }
+        const previous = readRow(db, entry.from);
+        db.prepare(`INSERT INTO repository_aliases (from_repository, to_repository, entered_at) VALUES (?, ?, ?)
+       ON CONFLICT (from_repository) DO UPDATE SET
+         to_repository = excluded.to_repository, entered_at = excluded.entered_at`).run(entry.from, entry.to, now().toISOString());
+        return previous;
+    });
+}
+/**
+ * Removes the alias for an old path.
+ * @param db - Open, migrated database.
+ * @param from - The old path, normalized.
+ * @returns The alias removed.
+ * @throws {RepositoryAliasError} If there's no alias for it.
+ */
+export function removeAlias(db, from) {
+    const previous = readRow(db, from);
+    if (previous === null) {
+        throw new RepositoryAliasError(`there's no alias for ${from}`);
+    }
+    db.prepare("DELETE FROM repository_aliases WHERE from_repository = ?").run(from);
+    return previous;
+}
+/**
+ * Lists every alias, by old path.
+ * @param db - Open, migrated database.
+ * @returns The rows.
+ */
+export function listAliases(db) {
+    return db
+        .prepare("SELECT from_repository, to_repository, entered_at FROM repository_aliases ORDER BY from_repository")
+        .all().map(toRow);
+}
+/**
+ * Reads the alias for one old path.
+ * @param db - Open, migrated database.
+ * @param from - The old path.
+ * @returns The row, or null when there is none.
+ */
+function readRow(db, from) {
+    const row = db
+        .prepare("SELECT from_repository, to_repository, entered_at FROM repository_aliases WHERE from_repository = ?")
+        .get(from);
+    return row === undefined ? null : toRow(row);
+}
+/**
+ * Converts a stored row.
+ * @param row - The row as SQLite returns it.
+ * @returns The alias.
+ */
+function toRow(row) {
+    return { from: row.from_repository, to: row.to_repository, enteredAt: row.entered_at };
+}
+//# sourceMappingURL=repository-aliases.js.map

package/dist/core/pricing/prices.js

@@ -0,0 +1,147 @@
+/**
+ * @file Loading the dated price table and syncing it into the database (docs/development.md P5.1, D-005, D-020).
+ *
+ * `prices.json` is the source of truth: committed, reviewed, and read from Anthropic's pricing page
+ * on the date each row records. The loader validates every field strictly, because a wrong rate
+ * silently mispriced every tool studied (D-005), and replaces the `prices` table on each ingest so a
+ * correction takes effect without a migration.
+ */
+import { readFileSync } from "node:fs";
+import { transaction } from "../db/database.js";
+/** A price table that fails validation. Nothing is written when this is raised. */
+export class PriceTableError extends Error {
+    /**
+     * Creates a price table error.
+     * @param message - Which row and field are invalid.
+     */
+    constructor(message) {
+        super(message);
+        this.name = "PriceTableError";
+    }
+}
+/** Rate fields every rates object must have. */
+const RATE_FIELDS = ["input", "output", "cache_write_5m", "cache_write_1h", "cache_read"];
+/** A `YYYY-MM-DD` date string. */
+const DAY = /^\d{4}-\d{2}-\d{2}$/;
+/**
+ * Validates a rates object.
+ * @param value - The candidate value.
+ * @param where - Location for error messages.
+ * @returns The rates.
+ * @throws {PriceTableError} If any rate is missing, not a number, or negative.
+ */
+export function validateRates(value, where) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new PriceTableError(`${where} must be an object`);
+    }
+    const record = value;
+    for (const field of RATE_FIELDS) {
+        const rate = record[field];
+        if (typeof rate !== "number" || !Number.isFinite(rate) || rate < 0) {
+            throw new PriceTableError(`${where}.${field} must be a non-negative number`);
+        }
+    }
+    return {
+        input: record["input"],
+        output: record["output"],
+        cache_write_5m: record["cache_write_5m"],
+        cache_write_1h: record["cache_write_1h"],
+        cache_read: record["cache_read"],
+    };
+}
+/**
+ * Validates a parsed price table document.
+ * @param document - Parsed JSON with a `rows` array.
+ * @returns Validated rows.
+ * @throws {PriceTableError} If the document or any row is invalid, or a (model, effective_from)
+ *   pair repeats.
+ */
+export function validatePriceTable(document) {
+    const rows = document?.rows;
+    if (!Array.isArray(rows)) {
+        throw new PriceTableError("price table must have a rows array");
+    }
+    const seen = new Set();
+    return rows.map((row, index) => {
+        const where = `rows[${index}]`;
+        const rates = validateRates(row, where);
+        const record = row;
+        /**
+         * Reads a required non-empty string field of this row.
+         * @param field - Field name.
+         * @returns The string.
+         * @throws {PriceTableError} If the field is missing, empty, or not a string.
+         */
+        const text = (field) => {
+            const value = record[field];
+            if (typeof value !== "string" || value === "") {
+                throw new PriceTableError(`${where}.${field} must be a non-empty string`);
+            }
+            return value;
+        };
+        const modelId = text("model_id");
+        const effectiveFrom = text("effective_from");
+        const verifiedOn = text("verified_on");
+        if (!DAY.test(effectiveFrom) || !DAY.test(verifiedOn)) {
+            throw new PriceTableError(`${where} dates must be YYYY-MM-DD`);
+        }
+        const key = `${modelId}@${effectiveFrom}`;
+        // Two rows for the same model and day would make the rate in effect ambiguous.
+        if (seen.has(key)) {
+            throw new PriceTableError(`${where} repeats ${key}`);
+        }
+        seen.add(key);
+        const max = record["standard_rate_max_input_tokens"];
+        if (max !== null && (typeof max !== "number" || !Number.isInteger(max) || max <= 0)) {
+            throw new PriceTableError(`${where}.standard_rate_max_input_tokens must be null or a positive integer`);
+        }
+        return {
+            model_id: modelId,
+            effective_from: effectiveFrom,
+            ...rates,
+            fast: record["fast"] === null ? null : validateRates(record["fast"], `${where}.fast`),
+            standard_rate_max_input_tokens: max,
+            source_url: text("source_url"),
+            verified_on: verifiedOn,
+        };
+    });
+}
+/**
+ * Reads and validates the price table file.
+ * @param path - Path to `prices.json`.
+ * @returns Validated rows.
+ * @throws {PriceTableError} If the file isn't valid JSON or fails validation.
+ */
+export function loadPriceTable(path) {
+    let document;
+    try {
+        document = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        throw new PriceTableError(`${path} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return validatePriceTable(document);
+}
+/**
+ * Replaces the database's price rows with the given table, in one transaction.
+ * @param db - Open, migrated database.
+ * @param rows - Validated rows.
+ * @returns Number of rows written.
+ */
+export function syncPrices(db, rows) {
+    const insert = db.prepare(`INSERT INTO prices (model_id, effective_from, input_per_mtok, output_per_mtok,
+       cache_write_5m_per_mtok, cache_write_1h_per_mtok, cache_read_per_mtok,
+       fast_input_per_mtok, fast_output_per_mtok, fast_cache_write_5m_per_mtok,
+       fast_cache_write_1h_per_mtok, fast_cache_read_per_mtok,
+       standard_rate_max_input_tokens, source_url, verified_on)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+    transaction(db, () => {
+        // The file is the whole truth: rows removed from it must disappear from the table too.
+        db.prepare("DELETE FROM prices").run();
+        for (const row of rows) {
+            insert.run(row.model_id, row.effective_from, row.input, row.output, row.cache_write_5m, row.cache_write_1h, row.cache_read, row.fast?.input ?? null, row.fast?.output ?? null, row.fast?.cache_write_5m ?? null, row.fast?.cache_write_1h ?? null, row.fast?.cache_read ?? null, row.standard_rate_max_input_tokens, row.source_url, row.verified_on);
+        }
+    });
+    return rows.length;
+}
+//# sourceMappingURL=prices.js.map

package/dist/core/settings/settings-file.js

@@ -0,0 +1,215 @@
+/**
+ * @file Reading, backing up, and atomically writing Claude Code's `settings.json`.
+ *
+ * Implements README § How it works ("Chaining, not clobbering") and the `statusline-collector`
+ * skill's `init` rules. The settings file belongs to the user, so every operation here:
+ * - backs up before writing,
+ * - refuses to "fix" a file it can't parse (report, don't fix),
+ * - writes atomically (temp file + rename), so a crash never leaves a half-written file,
+ * - keeps the file's key order, indentation, trailing newline, and permissions, so the diff
+ *   shows only the change that was made.
+ */
+import { chmodSync, copyFileSync, existsSync, lstatSync, readFileSync, realpathSync, renameSync, statSync, writeFileSync, } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { removePath } from "../install/private-files.js";
+import { expandHome } from "../util/paths.js";
+/** A settings file that exists but can't be safely edited. The file is never modified. */
+export class SettingsError extends Error {
+    /** Machine-readable reason, used by `init` to choose its message. */
+    code;
+    /** Path of the offending file. */
+    path;
+    /**
+     * Creates a settings error.
+     * @param code - Machine-readable reason.
+     * @param path - Path of the offending file.
+     * @param message - Human-readable explanation.
+     */
+    constructor(code, path, message) {
+        super(message);
+        this.name = "SettingsError";
+        this.code = code;
+        this.path = path;
+    }
+}
+/**
+ * Decides which settings file `init` operates on.
+ *
+ * Order: an explicit `--settings` path, then `$CLAUDE_CONFIG_DIR/settings.json`, then
+ * `~/.claude/settings.json`. Project-level settings are never chosen: the hook is per user.
+ * @param options - Home directory, flag override, and environment.
+ * @returns Absolute or home-expanded path to the settings file (which may not exist yet).
+ */
+export function locateSettings(options) {
+    if (options.override !== undefined && options.override !== "") {
+        return expandHome(options.override, options.home);
+    }
+    if (options.claudeConfigDir !== undefined && options.claudeConfigDir !== "") {
+        return join(expandHome(options.claudeConfigDir, options.home), "settings.json");
+    }
+    return join(options.home, ".claude", "settings.json");
+}
+/**
+ * Detects the indentation and trailing newline of a JSON text.
+ *
+ * Uses the first indented line; a file with no indented lines (e.g. `{}`) falls back to two
+ * spaces, the formatting Claude Code itself writes.
+ * @param raw - The file's text.
+ * @returns The layout to reuse when rewriting the file.
+ */
+export function detectFormat(raw) {
+    const trailingNewline = raw.endsWith("\n");
+    // The first line that starts with whitespace followed by content defines the indent unit.
+    const match = /^([ \t]+)\S/m.exec(raw);
+    const leading = match?.[1];
+    if (leading === undefined) {
+        return { indent: 2, trailingNewline };
+    }
+    return { indent: leading.startsWith("\t") ? "\t" : leading.length, trailingNewline };
+}
+/**
+ * Reports whether a path is a symbolic link, without following it.
+ * @param path - Path to inspect.
+ * @returns True if the path itself is a symbolic link.
+ */
+function isLink(path) {
+    try {
+        return lstatSync(path).isSymbolicLink();
+    }
+    catch {
+        // No such path, or its parent can't be read: not a link this code has to handle.
+        return false;
+    }
+}
+/**
+ * Reads and parses a settings file without modifying it.
+ * @param path - Path to the settings file.
+ * @returns `missing` if the file doesn't exist, otherwise the parsed settings with raw text.
+ * @throws {SettingsError} If the file is empty, isn't valid JSON, or isn't a JSON object.
+ */
+export function readSettings(path) {
+    // A symbolic link to a file that isn't there yet would otherwise look like "no settings file",
+    // and `init` would create whatever the link points at, which may be any path on the machine
+    // (D-050). A link to an existing file is followed: that's how a dotfiles repository is set up.
+    if (!existsSync(path) && isLink(path)) {
+        throw new SettingsError("dangling-link", path, `${path} is a symbolic link to a file that doesn't exist; refusing to create its target`);
+    }
+    if (!existsSync(path)) {
+        return { kind: "missing", path };
+    }
+    const raw = readFileSync(path, "utf8");
+    // An empty file isn't silently treated as `{}`: that would be fixing the user's file.
+    if (raw.trim() === "") {
+        throw new SettingsError("empty", path, `${path} is empty; refusing to guess its contents`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new SettingsError("invalid-json", path, `${path} is not valid JSON: ${reason}`);
+    }
+    // Arrays and primitives are valid JSON but not settings; editing them could destroy data.
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new SettingsError("not-an-object", path, `${path} does not contain a JSON object`);
+    }
+    return {
+        kind: "ok",
+        path,
+        settings: parsed,
+        raw,
+        format: detectFormat(raw),
+    };
+}
+/**
+ * Formats a UTC timestamp for use in a backup filename.
+ * @param now - The moment to format.
+ * @returns `YYYYMMDD-HHMMSS` in UTC, safe in filenames on every platform.
+ */
+export function backupStamp(now) {
+    // toISOString is always UTC, so backups sort chronologically regardless of the machine's zone.
+    const iso = now.toISOString();
+    return `${iso.slice(0, 4)}${iso.slice(5, 7)}${iso.slice(8, 10)}-${iso.slice(11, 13)}${iso.slice(14, 16)}${iso.slice(17, 19)}`;
+}
+/**
+ * Copies the settings file to a timestamped backup next to it, never overwriting a backup.
+ * @param path - Path to the settings file.
+ * @param now - Current time, injected for deterministic names in tests.
+ * @returns Path of the backup created, or `null` if there was no file to back up.
+ */
+export function backupSettings(path, now) {
+    if (!existsSync(path)) {
+        return null;
+    }
+    const base = `${path}.bak-${backupStamp(now)}`;
+    let candidate = base;
+    // Two runs within the same second must not overwrite each other's backup.
+    for (let suffix = 1; existsSync(candidate); suffix += 1) {
+        candidate = `${base}-${suffix}`;
+    }
+    copyFileSync(path, candidate);
+    // Settings can hold secrets (API keys in `env`), and a backup is one more copy: owner-only (D-043).
+    chmodSync(candidate, 0o600);
+    return candidate;
+}
+/**
+ * Serializes settings using a detected layout.
+ * @param settings - The settings object; key order is preserved.
+ * @param format - Indentation and trailing-newline style to use.
+ * @returns The JSON text to write.
+ */
+export function serializeSettings(settings, format) {
+    const text = JSON.stringify(settings, null, format.indent);
+    return format.trailingNewline ? `${text}\n` : text;
+}
+/** The real filesystem implementation of {@link AtomicFs}. */
+export const NODE_ATOMIC_FS = {
+    writeFileSync: (path, data, options) => {
+        writeFileSync(path, data, options);
+    },
+    renameSync: (from, to) => {
+        renameSync(from, to);
+    },
+    rmSync: (path) => {
+        // removePath, not rmSync: rmSync silently removes nothing on a non-ASCII Windows path, which
+        // would leave this temp file beside the settings file after a failed write (D-061).
+        removePath(path);
+    },
+    modeOf: (path) => (existsSync(path) ? statSync(path).mode & 0o777 : null),
+    chmodSync: (path, mode) => {
+        chmodSync(path, mode);
+    },
+    resolveLink: (path) => (isLink(path) ? realpathSync(path) : path),
+};
+/**
+ * Writes text to a file atomically: a temp file in the same directory, then a rename.
+ *
+ * Rename within one directory is atomic, so readers see either the old file or the new one,
+ * never a partial write. The original file's permissions are kept (settings may be 0600).
+ * @param path - Destination file.
+ * @param text - Complete new contents.
+ * @param fs - Filesystem operations; defaults to the real filesystem.
+ * @throws {Error} Whatever the filesystem throws. The temp file is removed first, and the
+ *   original file is untouched unless the rename itself succeeded.
+ */
+export function writeFileAtomic(path, text, fs = NODE_ATOMIC_FS) {
+    // A rename replaces a symbolic link with a regular file, which would quietly detach a settings
+    // file that a dotfiles repository links to. Write to what the link points at instead (D-050).
+    const destination = fs.resolveLink(path);
+    // Same directory as the destination: rename across filesystems isn't atomic.
+    const temp = join(dirname(destination), `.${basename(destination)}.tmp-${process.pid}-${Date.now()}`);
+    // An existing file keeps its mode; a new one is owner-only, since settings can hold secrets (D-043).
+    const mode = fs.modeOf(destination) ?? 0o600;
+    try {
+        fs.writeFileSync(temp, text, { mode });
+        // writeFile's mode is filtered by the umask; chmod makes the result match the original exactly.
+        fs.chmodSync(temp, mode);
+        fs.renameSync(temp, destination);
+    }
+    catch (error) {
+        fs.rmSync(temp, { force: true });
+        throw error;
+    }
+}
+//# sourceMappingURL=settings-file.js.map