@the-librarian/cli 1.0.0-rc.3 → 1.0.0-rc.31

package/dist/server/autoupdate.d.ts

@@ -0,0 +1,184 @@
+declare const AUTOUPDATE_CADENCES: readonly ["daily", "weekly"];
+type AutoUpdateCadence = (typeof AUTOUPDATE_CADENCES)[number];
+/** The oneshot service unit that runs the `--run` wrapper (single instance per host). */
+export declare const AUTOUPDATE_SERVICE_NAME = "the-librarian-autoupdate.service";
+/** The timer unit that fires the oneshot service ~hourly. */
+export declare const AUTOUPDATE_TIMER_NAME = "the-librarian-autoupdate.timer";
+/** A stable marker that tags OUR crontab line, so we can find/replace/remove it idempotently. */
+export declare const CRON_MARKER = "# the-librarian-autoupdate";
+/**
+ * The substring every OUR systemd unit's `Description=` carries (both the service
+ * and the timer descriptions start with it). `uninstall` reads a unit file and
+ * confirms this marker BEFORE deleting it (FIX I2) — so a same-named unit a human
+ * authored is never `rm`'d out from under them.
+ */
+export declare const UNIT_DESCRIPTION_MARKER = "The Librarian \u2014 auto-update";
+/** The absolute path the oneshot service is installed at (system unit, via sudo). */
+export declare function servicePath(): string;
+/** The absolute path the timer is installed at (system unit, via sudo). */
+export declare function timerPath(): string;
+/** A teaching error from autoupdate ops; the runtime renders `.message` as one stderr line. */
+export declare class AutoUpdateError extends Error {
+    constructor(message: string);
+}
+export interface AutoUpdateResult {
+    /** Human-readable report for stdout. */
+    output: string;
+}
+export interface AutoUpdateOptions {
+    /** Platform — gates the macOS deferral + systemd-vs-cron choice. Default `process.platform`. */
+    platform?: NodeJS.Platform | undefined;
+    /** Override home (tests). Threads into `server update`/`status`. */
+    home?: string | undefined;
+    /** Deploy dir override. Default: `~/.librarian/server`. Threads into update/status. */
+    dir?: string | undefined;
+}
+export interface EnableOptions extends AutoUpdateOptions {
+    /** Cadence to write into the running server. Default daily. Validated daily|weekly. */
+    cadence?: string | undefined;
+}
+export interface RunOptions extends AutoUpdateOptions {
+    /**
+     * Sink for the wrapper's one-line log entries (the timer's journal). Defaults
+     * to a `process.stderr` writer; tests inject a recorder. Every wrapper outcome
+     * (skip / update / failure) emits exactly one line here — and the wrapper never
+     * throws, so the timer's unit always exits 0.
+     */
+    log?: ((line: string) => void) | undefined;
+    /** Health-wait bound for the inner `server update` (small in tests). */
+    healthAttempts?: number | undefined;
+    /** Milliseconds between health polls for the inner update (0 in tests). */
+    healthIntervalMs?: number | undefined;
+    /** Injected current time for the due-check (tests). Default `new Date()`. */
+    now?: Date | undefined;
+}
+/** Inputs to the pure service generator (only the librarian path — NEVER a secret). */
+export interface ServiceUnitInput {
+    /** Absolute path to the `librarian` binary the oneshot runs with `server autoupdate --run`. */
+    librarianPath: string;
+}
+/**
+ * Generate the oneshot service unit text. PURE + unit-tested. Contains NO secret —
+ * it runs `librarian server autoupdate --run`, which reads the settings from the
+ * running container itself (via `docker exec`), so nothing sensitive is written
+ * into this world-readable unit file. `Type=oneshot` because the wrapper runs to
+ * completion each fire (it is the timer's job to schedule, not the service's).
+ */
+export declare function generateServiceUnit(input: ServiceUnitInput): string;
+/**
+ * Generate the timer unit text. PURE + unit-tested. Fires the oneshot service
+ * roughly hourly (`OnCalendar=hourly`, with `Persistent=true` so a missed fire
+ * while the host was off runs at next boot). The FREQUENT fire is deliberate: the
+ * cadence (daily/weekly) is a due-check IN the wrapper, NOT the timer period — so
+ * the dashboard can change cadence (a setting) with no host action (spec §4). A
+ * randomized delay spreads load and avoids every host updating on the exact hour.
+ */
+export declare function generateTimerUnit(): string;
+/**
+ * The crontab line for the cron fallback (systemd absent). Fires the wrapper at
+ * minute 17 of every hour (off the top-of-hour to spread load), tagged with
+ * {@link CRON_MARKER} so it can be found/replaced/removed idempotently. NO secret
+ * — same reasoning as the systemd unit (the wrapper reads settings from the
+ * container at run time).
+ */
+export declare function cronLine(librarianPath: string): string;
+/** The one-line macOS-deferred notice (boot persistence + autoupdate are Linux-only for now). */
+export declare const MACOS_NOTICE: string;
+/** The configured auto-update state read from the running server. */
+export interface RunningConfig {
+    enabled: boolean;
+    cadence: AutoUpdateCadence;
+    lastRunAt: string | null;
+}
+/**
+ * Read the auto-update config from the RUNNING server via `docker exec node -e`
+ * (the internal tRPC listener, loopback inside the container). Returns null when
+ * the container is down / the exec fails / the response is unusable — the caller
+ * treats null as "unreachable" and SKIPS (never auto-updates an unknown server).
+ * Never throws.
+ */
+export declare function readRunningConfig(): Promise<RunningConfig | null>;
+/**
+ * Write the auto-update config into the RUNNING server (so the dashboard reflects
+ * the CLI's enable/cadence) via `docker exec node -e` → internal tRPC `set`.
+ * Returns true on success, false when the container is down / the write failed.
+ * Never throws — a write failure during `enable` is surfaced as a non-fatal hint
+ * (the timer is still installed; the operator can toggle from the dashboard).
+ */
+export declare function writeRunningConfig(input: {
+    enabled?: boolean;
+    cadence?: AutoUpdateCadence;
+}): Promise<boolean>;
+/**
+ * Stamp `last_run_at` to NOW in the running server (the internal tRPC `stampRun`)
+ * after a SUCCESSFUL auto-update, so the next due-check advances by one cadence
+ * window. Returns true on success, false when the (freshly recreated) container
+ * isn't reachable yet / the call failed — a failed stamp is non-fatal (the update
+ * itself succeeded; the worst case is one extra due-check next fire). Never throws.
+ */
+export declare function stampRunInServer(): Promise<boolean>;
+/**
+ * Install the host scheduler + write the enabled/cadence settings into the running
+ * server. On Linux with systemd: write the oneshot service + the .timer to
+ * `/etc/systemd/system`, `daemon-reload`, then `enable --now` the TIMER (the
+ * service is oneshot — only the timer is enabled). Idempotent: re-running rewrites
+ * the SAME unit paths and re-enables, never duplicating. Where systemd is absent:
+ * install an hourly cron line (idempotent via {@link CRON_MARKER}). On macOS: print
+ * the deferred notice and skip cleanly.
+ *
+ * The settings write (enabled=true + cadence) is best-effort: a down server is a
+ * non-fatal hint (the timer is installed; the operator toggles from the dashboard
+ * once the server is up). The timer is what makes auto-update actually happen.
+ */
+export declare function enableAutoUpdate(options?: EnableOptions): Promise<AutoUpdateResult>;
+/**
+ * Disable auto-update WITHOUT removing the timer (spec §3 SC2): flip
+ * `enabled=false` in the running server so the next `--run` no-ops, leaving the
+ * timer installed. Idempotent. A down server is a teaching error (we can't flip a
+ * setting on a server we can't reach) — the operator can also toggle it off from
+ * the dashboard.
+ */
+export declare function disableAutoUpdate(options?: AutoUpdateOptions): Promise<AutoUpdateResult>;
+/**
+ * Remove the host scheduler entirely (spec §3 SC2): on systemd, `disable --now`
+ * the timer (tolerating "not loaded"), remove BOTH unit files, then
+ * `daemon-reload`. Where systemd is absent, strip our tagged crontab line. Safe if
+ * already absent — idempotent, never a crash. Does NOT touch the server's
+ * `enabled` setting (the timer is gone, so it no longer matters; leaving the
+ * setting avoids a needless server round-trip on a down server). On macOS: notice.
+ */
+export declare function uninstallAutoUpdate(options?: AutoUpdateOptions): Promise<AutoUpdateResult>;
+/**
+ * Report the auto-update state (spec §3 SC3): is the timer/cron installed?, the
+ * server's enabled/cadence/last-run (read from the running server), and the
+ * up-to-date badge (reusing `server status`' deployed-vs-latest render). A down
+ * server degrades the server-side fields to "unknown (server unreachable)" but
+ * still reports the host-side timer state and exits 0.
+ */
+export declare function autoUpdateStatus(options?: AutoUpdateOptions): Promise<AutoUpdateResult>;
+/** The fixed lock path: `~/.librarian/server/.autoupdate.lock` (no root needed). */
+export declare function autoUpdateLockPath(options: {
+    home?: string | undefined;
+    dir?: string | undefined;
+}): string;
+/**
+ * The wrapper the timer/cron fires (spec §3 SC4/SC7). Reads the auto-update
+ * settings from the RUNNING server, applies the due-check, and conditionally runs
+ * `server update`. FULLY FAIL-SOFT — it NEVER throws (the timer's unit always
+ * exits 0); every outcome is one log line:
+ *
+ *   - Server UNREACHABLE → SKIP (never auto-update a server in an unknown state).
+ *   - NOT (enabled && due) → SKIP (the no-op the disabled/not-due case wants).
+ *   - enabled && due → run `server update`. On SUCCESS, stamp `last_run_at`
+ *     (so the next due-check advances). On FAILURE (the update's own health-check
+ *     rollback left the prior container running), log + do NOT stamp (so the next
+ *     fire retries).
+ *
+ * The due-check is computed HOST-SIDE from the config the server returned (so the
+ * single source of truth — the core helper's logic — is mirrored here without a
+ * second round-trip): enabled AND the cadence has elapsed since `lastRunAt`
+ * (never-run → due).
+ */
+export declare function runAutoUpdate(options?: RunOptions): Promise<AutoUpdateResult>;
+export {};
+//# sourceMappingURL=autoupdate.d.ts.map

package/dist/server/autoupdate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"autoupdate.d.ts","sourceRoot":"","sources":["../../src/server/autoupdate.ts"],"names":[],"mappings":"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"}