@joystyk/ops 0.0.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# @joystyk/ops
+
+## 0.2.0
+
+### Minor Changes
+
+- bb095c7: Share canonical IPv4 and IPv6 /64 rate-limit keys across Node services. Keep room
+  initialization diagnostics on the server behind a client-safe reference, and expire old
+  message-rate strikes. Extend hidden-information conformance checks with transition-aware
+  perturbations so private events remain testable when recipients gain cards.
+
+## 0.1.0
+
+### Minor Changes
+
+- Prepare the first compiled library release: ESM and API declarations for every public entry point, runtime assets, and checks against installed npm tarballs. Games and applications remain private.

package/README.md

@@ -1,5 +1,35 @@
 # @joystyk/ops
 
-The first Joystyk library release is not yet available. This placeholder reserves the package name.
+Node operations helpers: Prometheus counters and gauges, database backup rotation, and validated runtime configuration. Run metrics on a private listener and use fixed label vocabularies.
 
-Source: https://github.com/joystyk-games/game-libraries
+`rateLimitKey(address)` gives Node services one canonical network limit key: an IPv4 address,
+or the first 64 bits of an IPv6 address. IPv4-mapped IPv6 forms share the IPv4 key. Apply it
+after validating the socket peer and trusted forwarding headers; it does not establish proxy
+trust. Keep the key in memory or hash it before storage, and never log it.
+
+## npm package
+
+The first `0.1.0` release is being prepared; it has not been published. Once available:
+
+```sh
+npm install @joystyk/ops
+```
+
+Requires Node 24.15 or later. This package runs on the server.
+
+| Import | Format |
+| --- | --- |
+| `@joystyk/ops` | ES module and TypeScript declarations |
+
+Only the entries listed above are public API. Installed packages contain compiled ESM,
+type declarations and runtime assets. Repository-relative links describe the Joystyk
+workspace and are not needed to use the npm package.
+
+```ts
+import { createMetrics } from '@joystyk/ops';
+
+const metrics = createMetrics();
+const requests = metrics.counter('requests_total', 'Requests served');
+requests.inc({ status: 'ok' });
+console.log(metrics.render());
+```

package/dist/backup.d.ts

@@ -0,0 +1,36 @@
+export interface Keep {
+    /** The newest copies to keep, whatever their age. At least 1. */
+    readonly newest: number;
+    /** Also keep the newest copy of each of this many most recent UTC days. */
+    readonly daily: number;
+}
+export declare const DEFAULT_KEEP: Keep;
+/** 2026-10-08T03:15:00.123Z → 20261008T031500Z: sortable, and safe in a file name. */
+export declare const stampOf: (date: Date) => string;
+/** The prefix a database's backups share: `rooms` for /data/rooms.sqlite. */
+export declare const backupPrefix: (database: string) => string;
+export declare const backupName: (database: string, date: Date) => string;
+/**
+ * The backups to delete among `names` (file names in the backup folder). Only names this
+ * module writes for `prefix` count; anything else in the folder is left alone.
+ */
+export declare function backupsToPrune(names: readonly string[], prefix: string, keep: Keep): string[];
+export type BackupResult = {
+    readonly event: 'backup_written';
+    readonly file: string;
+    readonly bytes: number;
+    readonly pruned: number;
+    readonly ms: number;
+} | {
+    readonly event: 'backup_skipped';
+    readonly reason: 'no database';
+    readonly database: string;
+};
+export interface BackupOptions {
+    readonly keep?: Keep;
+    /** A missing database is skipped instead of failing (the content service's, before its first run). */
+    readonly ifExists?: boolean;
+    readonly now?: () => Date;
+}
+/** Copies `source` into `dir`, checks the copy and prunes old ones. Throws when the backup fails. */
+export declare function backupDatabase(source: string, dir: string, options?: BackupOptions): Promise<BackupResult>;

package/dist/backup.js

@@ -0,0 +1,100 @@
+import { existsSync, linkSync, mkdirSync, readdirSync, rmSync, statSync } from "node:fs";
+import { basename, extname, join, resolve } from "node:path";
+import { DatabaseSync, backup } from "node:sqlite";
+//#region src/backup.ts
+var DEFAULT_KEEP = {
+	newest: 14,
+	daily: 14
+};
+var STAMP = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})Z$/;
+var PARTIAL = ".partial";
+/** A `.partial` file older than this belongs to a backup that was cut short. */
+var STALE_PARTIAL_MS = 36e5;
+/** 2026-10-08T03:15:00.123Z → 20261008T031500Z: sortable, and safe in a file name. */
+var stampOf = (date) => date.toISOString().replace(/\.\d{3}Z$/, "Z").replace(/[-:]/g, "");
+/** The prefix a database's backups share: `rooms` for /data/rooms.sqlite. */
+var backupPrefix = (database) => basename(database, extname(database));
+var backupName = (database, date) => `${backupPrefix(database)}-${stampOf(date)}.sqlite`;
+/**
+* The backups to delete among `names` (file names in the backup folder). Only names this
+* module writes for `prefix` count; anything else in the folder is left alone.
+*/
+function backupsToPrune(names, prefix, keep) {
+	const ours = names.filter((name) => name.startsWith(`${prefix}-`) && name.endsWith(".sqlite")).map((name) => ({
+		name,
+		stamp: name.slice(prefix.length + 1, -7)
+	})).filter((b) => STAMP.test(b.stamp)).sort((a, b) => a.stamp < b.stamp ? 1 : a.stamp > b.stamp ? -1 : 0);
+	const kept = new Set(ours.slice(0, Math.max(0, keep.newest)).map((b) => b.name));
+	const days = /* @__PURE__ */ new Set();
+	for (const b of ours) {
+		const day = b.stamp.slice(0, 8);
+		if (days.has(day)) continue;
+		if (days.size >= Math.max(0, keep.daily)) break;
+		days.add(day);
+		kept.add(b.name);
+	}
+	return ours.filter((b) => !kept.has(b.name)).map((b) => b.name);
+}
+/** Copies `source` into `dir`, checks the copy and prunes old ones. Throws when the backup fails. */
+async function backupDatabase(source, dir, options = {}) {
+	const keep = options.keep ?? DEFAULT_KEEP;
+	const now = options.now ?? (() => /* @__PURE__ */ new Date());
+	if (!Number.isInteger(keep.newest) || !Number.isInteger(keep.daily) || keep.newest < 1 || keep.daily < 0) throw new Error("keep.newest must be an integer of at least 1, and keep.daily at least 0");
+	if (!existsSync(source)) {
+		if (options.ifExists === true) return {
+			event: "backup_skipped",
+			reason: "no database",
+			database: resolve(source)
+		};
+		throw new Error(`the database ${source} does not exist`);
+	}
+	const started = performance.now();
+	const prefix = backupPrefix(source);
+	mkdirSync(dir, { recursive: true });
+	removeStalePartials(dir, prefix, now().getTime());
+	const target = join(dir, backupName(source, now()));
+	const partial = `${target}${PARTIAL}`;
+	if (existsSync(target)) throw new Error(`${target} exists; backups are never overwritten`);
+	try {
+		const db = new DatabaseSync(source, { readOnly: true });
+		try {
+			await backup(db, partial);
+		} finally {
+			db.close();
+		}
+		const copy = new DatabaseSync(partial);
+		try {
+			copy.exec("PRAGMA journal_mode = DELETE");
+			const row = copy.prepare("PRAGMA integrity_check").get();
+			if (row?.integrity_check !== "ok") throw new Error(`the backup failed its integrity check: ${JSON.stringify(row)}`);
+		} finally {
+			copy.close();
+		}
+		linkSync(partial, target);
+	} finally {
+		rmSync(partial, { force: true });
+	}
+	const pruned = backupsToPrune(readdirSync(dir), prefix, keep);
+	for (const name of pruned) rmSync(join(dir, name), { force: true });
+	return {
+		event: "backup_written",
+		file: resolve(target),
+		bytes: statSync(target).size,
+		pruned: pruned.length,
+		ms: Math.round(performance.now() - started)
+	};
+}
+/** Deletes `.partial` files this module left behind when a process stopped mid-backup. */
+function removeStalePartials(dir, prefix, now) {
+	for (const name of readdirSync(dir)) {
+		if (!name.startsWith(`${prefix}-`) || !name.endsWith(`.sqlite${PARTIAL}`)) continue;
+		const path = join(dir, name);
+		try {
+			if (now - statSync(path).mtimeMs > STALE_PARTIAL_MS) rmSync(path, { force: true });
+		} catch {}
+	}
+}
+//#endregion
+export { DEFAULT_KEEP, backupDatabase, backupName, backupPrefix, backupsToPrune, stampOf };
+
+//# sourceMappingURL=backup.js.map

package/dist/backup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backup.js","names":[],"sources":["../src/backup.ts"],"sourcesContent":["// Online backup of a live SQLite database (room-server.md section 6.6; Greed's\n// scripts/backup.ts). Safe while the service writes: node:sqlite's backup() copies a consistent\n// snapshot page by page. The copy is written under a `.partial` name, checked with\n// PRAGMA integrity_check, then linked into place, so a backup cut short (a container stopping)\n// never leaves a file that looks complete, and an existing file is never overwritten. Old copies\n// are pruned: the newest `keep.newest`, plus the newest copy of each of the last `keep.daily`\n// UTC days.\n//\n// This file imports only Node built-ins: every image copies it next to\n// scripts/sqlite-backup.ts, the command deploy/backup.sh runs, without the rest of the package.\nimport { existsSync, linkSync, mkdirSync, readdirSync, rmSync, statSync } from 'node:fs';\nimport { basename, extname, join, resolve } from 'node:path';\nimport { backup, DatabaseSync } from 'node:sqlite';\n\nexport interface Keep {\n  /** The newest copies to keep, whatever their age. At least 1. */\n  readonly newest: number;\n  /** Also keep the newest copy of each of this many most recent UTC days. */\n  readonly daily: number;\n}\n\nexport const DEFAULT_KEEP: Keep = { newest: 14, daily: 14 };\n\nconst STAMP = /^(\\d{4})(\\d{2})(\\d{2})T(\\d{2})(\\d{2})(\\d{2})Z$/;\nconst PARTIAL = '.partial';\n/** A `.partial` file older than this belongs to a backup that was cut short. */\nconst STALE_PARTIAL_MS = 60 * 60_000;\n\n/** 2026-10-08T03:15:00.123Z → 20261008T031500Z: sortable, and safe in a file name. */\nexport const stampOf = (date: Date): string =>\n  date\n    .toISOString()\n    .replace(/\\.\\d{3}Z$/, 'Z')\n    .replace(/[-:]/g, '');\n\n/** The prefix a database's backups share: `rooms` for /data/rooms.sqlite. */\nexport const backupPrefix = (database: string): string => basename(database, extname(database));\n\nexport const backupName = (database: string, date: Date): string => `${backupPrefix(database)}-${stampOf(date)}.sqlite`;\n\n/**\n * The backups to delete among `names` (file names in the backup folder). Only names this\n * module writes for `prefix` count; anything else in the folder is left alone.\n */\nexport function backupsToPrune(names: readonly string[], prefix: string, keep: Keep): string[] {\n  const ours = names\n    .filter((name) => name.startsWith(`${prefix}-`) && name.endsWith('.sqlite'))\n    .map((name) => ({ name, stamp: name.slice(prefix.length + 1, -'.sqlite'.length) }))\n    .filter((b) => STAMP.test(b.stamp))\n    .sort((a, b) => (a.stamp < b.stamp ? 1 : a.stamp > b.stamp ? -1 : 0));\n  const kept = new Set(ours.slice(0, Math.max(0, keep.newest)).map((b) => b.name));\n  const days = new Set<string>();\n  for (const b of ours) {\n    const day = b.stamp.slice(0, 8);\n    if (days.has(day)) continue;\n    if (days.size >= Math.max(0, keep.daily)) break;\n    days.add(day);\n    kept.add(b.name);\n  }\n  return ours.filter((b) => !kept.has(b.name)).map((b) => b.name);\n}\n\nexport type BackupResult =\n  | {\n      readonly event: 'backup_written';\n      readonly file: string;\n      readonly bytes: number;\n      readonly pruned: number;\n      readonly ms: number;\n    }\n  | { readonly event: 'backup_skipped'; readonly reason: 'no database'; readonly database: string };\n\nexport interface BackupOptions {\n  readonly keep?: Keep;\n  /** A missing database is skipped instead of failing (the content service's, before its first run). */\n  readonly ifExists?: boolean;\n  readonly now?: () => Date;\n}\n\n/** Copies `source` into `dir`, checks the copy and prunes old ones. Throws when the backup fails. */\nexport async function backupDatabase(source: string, dir: string, options: BackupOptions = {}): Promise<BackupResult> {\n  const keep = options.keep ?? DEFAULT_KEEP;\n  const now = options.now ?? (() => new Date());\n  if (!Number.isInteger(keep.newest) || !Number.isInteger(keep.daily) || keep.newest < 1 || keep.daily < 0) {\n    throw new Error('keep.newest must be an integer of at least 1, and keep.daily at least 0');\n  }\n  if (!existsSync(source)) {\n    if (options.ifExists === true) return { event: 'backup_skipped', reason: 'no database', database: resolve(source) };\n    throw new Error(`the database ${source} does not exist`);\n  }\n  const started = performance.now();\n  const prefix = backupPrefix(source);\n  mkdirSync(dir, { recursive: true });\n  removeStalePartials(dir, prefix, now().getTime());\n  const target = join(dir, backupName(source, now()));\n  const partial = `${target}${PARTIAL}`;\n  if (existsSync(target)) throw new Error(`${target} exists; backups are never overwritten`);\n\n  try {\n    const db = new DatabaseSync(source, { readOnly: true });\n    try {\n      await backup(db, partial);\n    } finally {\n      db.close();\n    }\n    // The copy inherits WAL mode; switch it to a rollback journal so it stays one self-contained file.\n    const copy = new DatabaseSync(partial);\n    try {\n      copy.exec('PRAGMA journal_mode = DELETE');\n      const row = copy.prepare('PRAGMA integrity_check').get() as { integrity_check?: unknown } | undefined;\n      if (row?.integrity_check !== 'ok')\n        throw new Error(`the backup failed its integrity check: ${JSON.stringify(row)}`);\n    } finally {\n      copy.close();\n    }\n    // A hard link fails if the target appeared meanwhile, where a rename would replace it.\n    linkSync(partial, target);\n  } finally {\n    rmSync(partial, { force: true });\n  }\n\n  const pruned = backupsToPrune(readdirSync(dir), prefix, keep);\n  for (const name of pruned) rmSync(join(dir, name), { force: true });\n  return {\n    event: 'backup_written',\n    file: resolve(target),\n    bytes: statSync(target).size,\n    pruned: pruned.length,\n    ms: Math.round(performance.now() - started),\n  };\n}\n\n/** Deletes `.partial` files this module left behind when a process stopped mid-backup. */\nfunction removeStalePartials(dir: string, prefix: string, now: number): void {\n  for (const name of readdirSync(dir)) {\n    if (!name.startsWith(`${prefix}-`) || !name.endsWith(`.sqlite${PARTIAL}`)) continue;\n    const path = join(dir, name);\n    try {\n      if (now - statSync(path).mtimeMs > STALE_PARTIAL_MS) rmSync(path, { force: true });\n    } catch {\n      // Gone already.\n    }\n  }\n}\n"],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { backupDatabase, backupName, backupPrefix, backupsToPrune, DEFAULT_KEEP, stampOf, type BackupOptions, type BackupResult, type Keep, } from './backup.js';
+export { closeServer, createMetrics, METRICS_CONTENT_TYPE, startMetricsServer, type Counter, type Labels, type Metrics, } from './metrics.js';
+export { rateLimitKey } from './network.js';
+export { describeSchedule, nextBackupAt, parseOpsEnv, scheduleBackups, startSchedule, systemTimers, type BackupReport, type BackupSchedule, type BackupSettings, type MetricsSettings, type OpsSettings, type ScheduleBackupsOptions, type ScheduledDatabase, type Scheduler, type Timers, } from './schedule.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+import { DEFAULT_KEEP, backupDatabase, backupName, backupPrefix, backupsToPrune, stampOf } from "./backup.js";
+import { METRICS_CONTENT_TYPE, closeServer, createMetrics, startMetricsServer } from "./metrics.js";
+import { rateLimitKey } from "./network.js";
+import { describeSchedule, nextBackupAt, parseOpsEnv, scheduleBackups, startSchedule, systemTimers } from "./schedule.js";
+export { DEFAULT_KEEP, METRICS_CONTENT_TYPE, backupDatabase, backupName, backupPrefix, backupsToPrune, closeServer, createMetrics, describeSchedule, nextBackupAt, parseOpsEnv, rateLimitKey, scheduleBackups, stampOf, startMetricsServer, startSchedule, systemTimers };

package/dist/metrics.d.ts

@@ -0,0 +1,21 @@
+import { type Server } from 'node:http';
+export type Labels = Readonly<Record<string, string>>;
+export interface Counter {
+    inc(labels?: Labels, by?: number): void;
+    /** The current value for these labels (tests, and gauges derived from counters). */
+    value(labels?: Labels): number;
+}
+export interface Metrics {
+    /** A counter; `seed` lists label sets reported as 0 before their first increment. */
+    counter(name: string, help: string, seed?: readonly Labels[]): Counter;
+    /** A gauge read at scrape time. */
+    gauge(name: string, help: string, read: () => number): void;
+    /** Every metric, in registration order, in Prometheus text format. */
+    render(): string;
+}
+export declare const createMetrics: () => Metrics;
+export declare const METRICS_CONTENT_TYPE = "text/plain; version=0.0.4; charset=utf-8";
+/** Serves `GET /metrics` on its own port. Anything else is 404. Resolves once listening. */
+export declare const startMetricsServer: (host: string, port: number, render: () => string) => Promise<Server>;
+/** Closes a listener and resolves when it has closed. */
+export declare const closeServer: (server: Server) => Promise<void>;

package/dist/metrics.js

@@ -0,0 +1,96 @@
+import { createServer } from "node:http";
+//#region src/metrics.ts
+var NAME = /^[a-zA-Z_:][a-zA-Z0-9_:]*$/;
+var LABEL = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+var escapeLabel = (value) => value.replace(/\\/g, "\\\\").replace(/\n/g, "\\n").replace(/"/g, "\\\"");
+var escapeHelp = (value) => value.replace(/\\/g, "\\\\").replace(/\n/g, "\\n");
+var labelKey = (labels) => {
+	const names = Object.keys(labels).sort();
+	for (const name of names) if (!LABEL.test(name)) throw new Error(`invalid label name ${name}`);
+	return names.length === 0 ? "" : `{${names.map((name) => `${name}="${escapeLabel(labels[name] ?? "")}"`).join(",")}}`;
+};
+var formatValue = (value) => Number.isFinite(value) ? String(value) : Number.isNaN(value) ? "NaN" : value > 0 ? "+Inf" : "-Inf";
+var createMetrics = () => {
+	const sections = [];
+	const names = /* @__PURE__ */ new Set();
+	const register = (name) => {
+		if (!NAME.test(name)) throw new Error(`invalid metric name ${name}`);
+		if (names.has(name)) throw new Error(`${name} is registered twice`);
+		names.add(name);
+	};
+	return {
+		counter: (name, help, seed = []) => {
+			register(name);
+			const values = /* @__PURE__ */ new Map();
+			for (const labels of seed) values.set(labelKey(labels), 0);
+			if (seed.length === 0) values.set("", 0);
+			sections.push(() => [
+				`# HELP ${name} ${escapeHelp(help)}`,
+				`# TYPE ${name} counter`,
+				...[...values].map(([key, value]) => `${name}${key} ${formatValue(value)}`)
+			].join("\n"));
+			return {
+				inc: (labels = {}, by = 1) => {
+					if (!(by >= 0)) throw new Error("a counter only goes up");
+					const key = labelKey(labels);
+					values.set(key, (values.get(key) ?? 0) + by);
+					if (key !== "" && seed.length === 0 && values.get("") === 0) values.delete("");
+				},
+				value: (labels = {}) => values.get(labelKey(labels)) ?? 0
+			};
+		},
+		gauge: (name, help, read) => {
+			register(name);
+			sections.push(() => {
+				let value;
+				try {
+					value = read();
+				} catch {
+					value = NaN;
+				}
+				return [
+					`# HELP ${name} ${escapeHelp(help)}`,
+					`# TYPE ${name} gauge`,
+					`${name} ${formatValue(value)}`
+				].join("\n");
+			});
+		},
+		render: () => `${sections.map((section) => section()).join("\n")}\n`
+	};
+};
+var METRICS_CONTENT_TYPE = "text/plain; version=0.0.4; charset=utf-8";
+/** Serves `GET /metrics` on its own port. Anything else is 404. Resolves once listening. */
+var startMetricsServer = (host, port, render) => new Promise((resolve, reject) => {
+	const server = createServer((request, response) => {
+		if (new URL(request.url ?? "/", "http://metrics.invalid").pathname !== "/metrics") {
+			response.writeHead(404, { "content-type": "text/plain; charset=utf-8" }).end("Not found\n");
+			return;
+		}
+		if (request.method !== "GET" && request.method !== "HEAD") {
+			response.writeHead(405, {
+				allow: "GET, HEAD",
+				"content-type": "text/plain; charset=utf-8"
+			}).end("Method not allowed\n");
+			return;
+		}
+		const body = render();
+		response.writeHead(200, {
+			"content-type": METRICS_CONTENT_TYPE,
+			"cache-control": "no-store"
+		}).end(request.method === "HEAD" ? void 0 : body);
+	});
+	server.once("error", reject);
+	server.listen(port, host, () => {
+		server.off("error", reject);
+		resolve(server);
+	});
+});
+/** Closes a listener and resolves when it has closed. */
+var closeServer = (server) => new Promise((resolve) => {
+	server.close(() => resolve());
+	server.closeAllConnections();
+});
+//#endregion
+export { METRICS_CONTENT_TYPE, closeServer, createMetrics, startMetricsServer };
+
+//# sourceMappingURL=metrics.js.map

package/dist/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","names":[],"sources":["../src/metrics.ts"],"sourcesContent":["// A minimal Prometheus text-format registry (exposition format 0.0.4) and its listener. The\n// services count a handful of things (DEPLOY.md, \"Metrics\"); a client library would be more\n// than they need. Labels carry only fixed vocabularies, such as a status class, a game ID or a\n// log event name: never an address, a token, a room code or a name, because every visitor may\n// be a child (D-26).\n//\n// The listener runs on its own port (METRICS_PORT), never the service's public one. Traefik\n// routes only the port its labels name, and Compose publishes nothing, so the metrics are\n// reachable only from containers on the same Docker network.\nimport { createServer, type Server } from 'node:http';\n\nexport type Labels = Readonly<Record<string, string>>;\n\nexport interface Counter {\n  inc(labels?: Labels, by?: number): void;\n  /** The current value for these labels (tests, and gauges derived from counters). */\n  value(labels?: Labels): number;\n}\n\nexport interface Metrics {\n  /** A counter; `seed` lists label sets reported as 0 before their first increment. */\n  counter(name: string, help: string, seed?: readonly Labels[]): Counter;\n  /** A gauge read at scrape time. */\n  gauge(name: string, help: string, read: () => number): void;\n  /** Every metric, in registration order, in Prometheus text format. */\n  render(): string;\n}\n\nconst NAME = /^[a-zA-Z_:][a-zA-Z0-9_:]*$/;\nconst LABEL = /^[a-zA-Z_][a-zA-Z0-9_]*$/;\n\nconst escapeLabel = (value: string): string => value.replace(/\\\\/g, '\\\\\\\\').replace(/\\n/g, '\\\\n').replace(/\"/g, '\\\\\"');\nconst escapeHelp = (value: string): string => value.replace(/\\\\/g, '\\\\\\\\').replace(/\\n/g, '\\\\n');\n\nconst labelKey = (labels: Labels): string => {\n  const names = Object.keys(labels).sort();\n  for (const name of names) if (!LABEL.test(name)) throw new Error(`invalid label name ${name}`);\n  return names.length === 0 ? '' : `{${names.map((name) => `${name}=\"${escapeLabel(labels[name] ?? '')}\"`).join(',')}}`;\n};\n\nconst formatValue = (value: number): string =>\n  Number.isFinite(value) ? String(value) : Number.isNaN(value) ? 'NaN' : value > 0 ? '+Inf' : '-Inf';\n\nexport const createMetrics = (): Metrics => {\n  const sections: (() => string)[] = [];\n  const names = new Set<string>();\n  const register = (name: string): void => {\n    if (!NAME.test(name)) throw new Error(`invalid metric name ${name}`);\n    if (names.has(name)) throw new Error(`${name} is registered twice`);\n    names.add(name);\n  };\n\n  return {\n    counter: (name, help, seed = []) => {\n      register(name);\n      const values = new Map<string, number>();\n      for (const labels of seed) values.set(labelKey(labels), 0);\n      if (seed.length === 0) values.set('', 0);\n      sections.push(() =>\n        [\n          `# HELP ${name} ${escapeHelp(help)}`,\n          `# TYPE ${name} counter`,\n          ...[...values].map(([key, value]) => `${name}${key} ${formatValue(value)}`),\n        ].join('\\n'),\n      );\n      return {\n        inc: (labels = {}, by = 1) => {\n          if (!(by >= 0)) throw new Error('a counter only goes up');\n          const key = labelKey(labels);\n          values.set(key, (values.get(key) ?? 0) + by);\n          // An unlabelled zero is only a placeholder once labelled values exist.\n          if (key !== '' && seed.length === 0 && values.get('') === 0) values.delete('');\n        },\n        value: (labels = {}) => values.get(labelKey(labels)) ?? 0,\n      };\n    },\n    gauge: (name, help, read) => {\n      register(name);\n      sections.push(() => {\n        let value: number;\n        try {\n          value = read();\n        } catch {\n          value = Number.NaN;\n        }\n        return [`# HELP ${name} ${escapeHelp(help)}`, `# TYPE ${name} gauge`, `${name} ${formatValue(value)}`].join(\n          '\\n',\n        );\n      });\n    },\n    render: () => `${sections.map((section) => section()).join('\\n')}\\n`,\n  };\n};\n\nexport const METRICS_CONTENT_TYPE = 'text/plain; version=0.0.4; charset=utf-8';\n\n/** Serves `GET /metrics` on its own port. Anything else is 404. Resolves once listening. */\nexport const startMetricsServer = (host: string, port: number, render: () => string): Promise<Server> =>\n  new Promise((resolve, reject) => {\n    const server = createServer((request, response) => {\n      const path = new URL(request.url ?? '/', 'http://metrics.invalid').pathname;\n      if (path !== '/metrics') {\n        response.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' }).end('Not found\\n');\n        return;\n      }\n      if (request.method !== 'GET' && request.method !== 'HEAD') {\n        response\n          .writeHead(405, { allow: 'GET, HEAD', 'content-type': 'text/plain; charset=utf-8' })\n          .end('Method not allowed\\n');\n        return;\n      }\n      const body = render();\n      response\n        .writeHead(200, { 'content-type': METRICS_CONTENT_TYPE, 'cache-control': 'no-store' })\n        .end(request.method === 'HEAD' ? undefined : body);\n    });\n    server.once('error', reject);\n    server.listen(port, host, () => {\n      server.off('error', reject);\n      resolve(server);\n    });\n  });\n\n/** Closes a listener and resolves when it has closed. */\nexport const closeServer = (server: Server): Promise<void> =>\n  new Promise((resolve) => {\n    server.close(() => resolve());\n    server.closeAllConnections();\n  });\n"],"mappings":"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"}

package/dist/network.d.ts

@@ -0,0 +1,2 @@
+/** Canonical rate-limit key: IPv4 per address, IPv6 per /64, mapped IPv4 as IPv4. */
+export declare function rateLimitKey(address: string): string;

package/dist/network.js

@@ -0,0 +1,27 @@
+import { isIP } from "node:net";
+//#region src/network.ts
+/** Canonical rate-limit key: IPv4 per address, IPv6 per /64, mapped IPv4 as IPv4. */
+function rateLimitKey(address) {
+	const family = isIP(address);
+	if (family === 4) return address;
+	if (family !== 6) return "unknown";
+	const [head = "", tail] = new URL(`http://[${address.split("%")[0]}]/`).hostname.slice(1, -1).split("::");
+	const left = head === "" ? [] : head.split(":");
+	const right = tail === void 0 || tail === "" ? [] : tail.split(":");
+	const words = (tail === void 0 ? left : [
+		...left,
+		...Array(8 - left.length - right.length).fill("0"),
+		...right
+	]).map((word) => parseInt(word, 16));
+	if (words.slice(0, 5).every((word) => word === 0) && words[5] === 65535) return [
+		words[6] >>> 8,
+		words[6] & 255,
+		words[7] >>> 8,
+		words[7] & 255
+	].join(".");
+	return `${words.slice(0, 4).map((word) => word.toString(16)).join(":")}::/64`;
+}
+//#endregion
+export { rateLimitKey };
+
+//# sourceMappingURL=network.js.map

package/dist/network.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"network.js","names":[],"sources":["../src/network.ts"],"sourcesContent":["import { isIP } from 'node:net';\n\n/** Canonical rate-limit key: IPv4 per address, IPv6 per /64, mapped IPv4 as IPv4. */\nexport function rateLimitKey(address: string): string {\n  const family = isIP(address);\n  if (family === 4) return address;\n  if (family !== 6) return 'unknown';\n  // WHATWG parsing canonicalizes compressed, mixed-case and dotted-tail forms without IO.\n  const host = new URL(`http://[${address.split('%')[0]}]/`).hostname.slice(1, -1);\n  const [head = '', tail] = host.split('::');\n  const left = head === '' ? [] : head.split(':');\n  const right = tail === undefined || tail === '' ? [] : tail.split(':');\n  const words = (\n    tail === undefined ? left : [...left, ...Array<string>(8 - left.length - right.length).fill('0'), ...right]\n  ).map((word) => parseInt(word, 16));\n  if (words.slice(0, 5).every((word) => word === 0) && words[5] === 0xffff) {\n    return [words[6]! >>> 8, words[6]! & 255, words[7]! >>> 8, words[7]! & 255].join('.');\n  }\n  return `${words\n    .slice(0, 4)\n    .map((word) => word.toString(16))\n    .join(':')}::/64`;\n}\n"],"mappings":";;;AAGA,SAAgB,aAAa,SAAyB;CACpD,MAAM,SAAS,KAAK,OAAO;CAC3B,IAAI,WAAW,GAAG,OAAO;CACzB,IAAI,WAAW,GAAG,OAAO;CAGzB,MAAM,CAAC,OAAO,IAAI,QADL,IAAI,IAAI,WAAW,QAAQ,MAAM,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,SAAS,MAAM,GAAG,EACnD,CAAA,CAAK,MAAM,IAAI;CACzC,MAAM,OAAO,SAAS,KAAK,CAAC,IAAI,KAAK,MAAM,GAAG;CAC9C,MAAM,QAAQ,SAAS,KAAA,KAAa,SAAS,KAAK,CAAC,IAAI,KAAK,MAAM,GAAG;CACrE,MAAM,SACJ,SAAS,KAAA,IAAY,OAAO;EAAC,GAAG;EAAM,GAAG,MAAc,IAAI,KAAK,SAAS,MAAM,MAAM,CAAC,CAAC,KAAK,GAAG;EAAG,GAAG;CAAK,EAAA,CAC1G,KAAK,SAAS,SAAS,MAAM,EAAE,CAAC;CAClC,IAAI,MAAM,MAAM,GAAG,CAAC,CAAC,CAAC,OAAO,SAAS,SAAS,CAAC,KAAK,MAAM,OAAO,OAChE,OAAO;EAAC,MAAM,OAAQ;EAAG,MAAM,KAAM;EAAK,MAAM,OAAQ;EAAG,MAAM,KAAM;CAAG,CAAC,CAAC,KAAK,GAAG;CAEtF,OAAO,GAAG,MACP,MAAM,GAAG,CAAC,CAAC,CACX,KAAK,SAAS,KAAK,SAAS,EAAE,CAAC,CAAC,CAChC,KAAK,GAAG,EAAE;AACf"}

package/dist/schedule.d.ts

@@ -0,0 +1,68 @@
+import { type BackupResult, type Keep } from './backup.js';
+export interface BackupSchedule {
+    /** Minutes between backups; divides a day. */
+    readonly intervalMinutes: number;
+    /** Minutes past each interval boundary, in UTC. */
+    readonly offsetMinutes: number;
+}
+/** The first scheduled instant strictly after `now`. */
+export declare const nextBackupAt: (now: number, schedule: BackupSchedule) => number;
+export interface BackupSettings {
+    /** Null when BACKUP_INTERVAL_MINUTES is 0: only on-demand backups (deploy/backup.sh). */
+    readonly schedule: BackupSchedule | null;
+    readonly keep: Keep;
+}
+export interface MetricsSettings {
+    readonly host: string;
+    readonly port: number;
+}
+export interface OpsSettings {
+    readonly backup: BackupSettings;
+    /** Null when METRICS_PORT is unset: no metrics listener. */
+    readonly metrics: MetricsSettings | null;
+}
+/** Reads the backup and metrics settings from the environment, or lists every problem. */
+export declare const parseOpsEnv: (env: Readonly<Record<string, string | undefined>>) => {
+    ok: true;
+    settings: OpsSettings;
+} | {
+    ok: false;
+    issues: string[];
+};
+export declare const describeSchedule: (schedule: BackupSchedule | null) => string;
+export interface Timers {
+    now(): number;
+    /** Calls `fire` after `ms`; the returned function cancels it. */
+    after(ms: number, fire: () => void): () => void;
+}
+export declare const systemTimers: Timers;
+export interface Scheduler {
+    /** The next scheduled run (epoch ms), or null once stopped. */
+    next(): number | null;
+    /** Cancels the timer and waits for a run in progress. */
+    stop(): Promise<void>;
+}
+/** Runs `run` on the schedule until stopped. `run` must not throw; it reports its own outcome. */
+export declare const startSchedule: (schedule: BackupSchedule, run: () => Promise<void>, timers?: Timers) => Scheduler;
+export interface ScheduledDatabase {
+    /** The live database file. */
+    readonly file: string;
+    /** Where its copies go; default `backups/` beside it. */
+    readonly dir?: string;
+    /** Skip, rather than fail, while the database doesn't exist yet. */
+    readonly ifExists?: boolean;
+}
+export type BackupReport = BackupResult | {
+    readonly event: 'backup_failed';
+    readonly database: string;
+    readonly error: string;
+};
+export interface ScheduleBackupsOptions {
+    readonly settings: BackupSettings;
+    readonly databases: readonly ScheduledDatabase[];
+    /** One call per database per run: the service writes it as a log line in its own format. */
+    readonly report: (report: BackupReport) => void;
+    readonly timers?: Timers;
+}
+/** Backs up each database on the schedule. Returns null when the schedule is off. */
+export declare const scheduleBackups: (options: ScheduleBackupsOptions) => Scheduler | null;

package/dist/schedule.js

@@ -0,0 +1,126 @@
+import { DEFAULT_KEEP, backupDatabase } from "./backup.js";
+import { dirname, join } from "node:path";
+import * as z from "zod";
+//#region src/schedule.ts
+/** The first scheduled instant strictly after `now`. */
+var nextBackupAt = (now, schedule) => {
+	const period = schedule.intervalMinutes * 6e4;
+	const offset = schedule.offsetMinutes * 6e4;
+	return (Math.floor((now - offset) / period) + 1) * period + offset;
+};
+var blankToUndefined = (value) => typeof value === "string" && value.trim() === "" ? void 0 : value;
+var optional = (schema) => z.preprocess(blankToUndefined, schema.optional());
+var int = (min, max) => z.coerce.number().int().min(min).max(max);
+var OpsEnv = z.object({
+	/** Minutes between scheduled backups; must divide 1440. 0 turns the schedule off. */
+	BACKUP_INTERVAL_MINUTES: optional(int(0, 1440).refine((m) => m === 0 || 1440 % m === 0, "must be 0 (off) or divide 1440 (a day), e.g. 60, 360, 1440")).default(1440),
+	/** The UTC time the schedule is anchored on, HH:MM. */
+	BACKUP_AT: optional(z.string().regex(/^([01]\d|2[0-3]):[0-5]\d$/, "must be a UTC time such as 03:17")).default("03:17"),
+	/** The newest backups kept per database. */
+	BACKUP_KEEP: optional(int(1, 1e4)).default(DEFAULT_KEEP.newest),
+	/** Also keep the newest backup of each of this many most recent UTC days. */
+	BACKUP_KEEP_DAILY: optional(int(0, 1e4)).default(DEFAULT_KEEP.daily),
+	/** The internal metrics port. Unset: no metrics listener. */
+	METRICS_PORT: optional(int(1, 65535)),
+	METRICS_HOST: optional(z.string()).default("0.0.0.0")
+});
+/** Reads the backup and metrics settings from the environment, or lists every problem. */
+var parseOpsEnv = (env) => {
+	const parsed = OpsEnv.safeParse(env);
+	if (!parsed.success) return {
+		ok: false,
+		issues: parsed.error.issues.map((issue) => `${issue.path.join(".") || "env"}: ${issue.message}`)
+	};
+	const e = parsed.data;
+	const [hours, minutes] = e.BACKUP_AT.split(":").map(Number);
+	const anchor = (hours ?? 0) * 60 + (minutes ?? 0);
+	return {
+		ok: true,
+		settings: {
+			backup: {
+				schedule: e.BACKUP_INTERVAL_MINUTES === 0 ? null : {
+					intervalMinutes: e.BACKUP_INTERVAL_MINUTES,
+					offsetMinutes: anchor % e.BACKUP_INTERVAL_MINUTES
+				},
+				keep: {
+					newest: e.BACKUP_KEEP,
+					daily: e.BACKUP_KEEP_DAILY
+				}
+			},
+			metrics: e.METRICS_PORT === void 0 ? null : {
+				host: e.METRICS_HOST,
+				port: e.METRICS_PORT
+			}
+		}
+	};
+};
+var describeSchedule = (schedule) => {
+	if (schedule === null) return "off";
+	const hhmm = (m) => `${String(Math.floor(m / 60)).padStart(2, "0")}:${String(m % 60).padStart(2, "0")}`;
+	return schedule.intervalMinutes === 1440 ? `daily at ${hhmm(schedule.offsetMinutes)} UTC` : `every ${String(schedule.intervalMinutes)} min at +${String(schedule.offsetMinutes)} min (UTC)`;
+};
+var systemTimers = {
+	now: () => Date.now(),
+	after: (ms, fire) => {
+		const handle = setTimeout(fire, Math.max(0, ms));
+		handle.unref();
+		return () => clearTimeout(handle);
+	}
+};
+/** Runs `run` on the schedule until stopped. `run` must not throw; it reports its own outcome. */
+var startSchedule = (schedule, run, timers = systemTimers) => {
+	let stopped = false;
+	let nextAt = null;
+	let cancel = null;
+	let running = null;
+	const arm = () => {
+		if (stopped) return;
+		const at = nextBackupAt(timers.now(), schedule);
+		nextAt = at;
+		const wake = () => {
+			if (stopped) return;
+			if (timers.now() < at) {
+				cancel = timers.after(at - timers.now(), wake);
+				return;
+			}
+			running = run().finally(() => {
+				running = null;
+				arm();
+			});
+		};
+		cancel = timers.after(at - timers.now(), wake);
+	};
+	arm();
+	return {
+		next: () => stopped ? null : nextAt,
+		stop: async () => {
+			stopped = true;
+			nextAt = null;
+			cancel?.();
+			await running;
+		}
+	};
+};
+/** Backs up each database on the schedule. Returns null when the schedule is off. */
+var scheduleBackups = (options) => {
+	const { schedule, keep } = options.settings;
+	if (schedule === null) return null;
+	return startSchedule(schedule, async () => {
+		for (const db of options.databases) try {
+			options.report(await backupDatabase(db.file, db.dir ?? join(dirname(db.file), "backups"), {
+				keep,
+				ifExists: db.ifExists === true
+			}));
+		} catch (error) {
+			options.report({
+				event: "backup_failed",
+				database: db.file,
+				error: error instanceof Error ? error.message : String(error)
+			});
+		}
+	}, options.timers);
+};
+//#endregion
+export { describeSchedule, nextBackupAt, parseOpsEnv, scheduleBackups, startSchedule, systemTimers };
+
+//# sourceMappingURL=schedule.js.map

package/dist/schedule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schedule.js","names":[],"sources":["../src/schedule.ts"],"sourcesContent":["// Scheduled backups inside each service's own process (D-62, the same rule as D-56 for the\n// content service): no host cron, no cron daemon and no cron library. A backup runs every\n// BACKUP_INTERVAL_MINUTES at fixed UTC times anchored on BACKUP_AT, so the default (1440 and\n// 03:17) is one backup a night at 03:17 UTC, and 60 gives one at 17 minutes past every hour.\n// Each wait is computed afresh from the wall clock, so the schedule never drifts, and UTC has no\n// daylight saving to skip or repeat an hour. Nothing runs at startup: a container that restarts\n// in a loop must not fill its volume with copies.\nimport { dirname, join } from 'node:path';\nimport * as z from 'zod';\nimport { backupDatabase, DEFAULT_KEEP, type BackupResult, type Keep } from './backup.ts';\n\nexport interface BackupSchedule {\n  /** Minutes between backups; divides a day. */\n  readonly intervalMinutes: number;\n  /** Minutes past each interval boundary, in UTC. */\n  readonly offsetMinutes: number;\n}\n\n/** The first scheduled instant strictly after `now`. */\nexport const nextBackupAt = (now: number, schedule: BackupSchedule): number => {\n  const period = schedule.intervalMinutes * 60_000;\n  const offset = schedule.offsetMinutes * 60_000;\n  return (Math.floor((now - offset) / period) + 1) * period + offset;\n};\n\nexport interface BackupSettings {\n  /** Null when BACKUP_INTERVAL_MINUTES is 0: only on-demand backups (deploy/backup.sh). */\n  readonly schedule: BackupSchedule | null;\n  readonly keep: Keep;\n}\n\nexport interface MetricsSettings {\n  readonly host: string;\n  readonly port: number;\n}\n\nexport interface OpsSettings {\n  readonly backup: BackupSettings;\n  /** Null when METRICS_PORT is unset: no metrics listener. */\n  readonly metrics: MetricsSettings | null;\n}\n\nconst blankToUndefined = (value: unknown) => (typeof value === 'string' && value.trim() === '' ? undefined : value);\nconst optional = <T extends z.ZodType>(schema: T) => z.preprocess(blankToUndefined, schema.optional());\nconst int = (min: number, max: number) => z.coerce.number().int().min(min).max(max);\n\nconst OpsEnv = z.object({\n  /** Minutes between scheduled backups; must divide 1440. 0 turns the schedule off. */\n  BACKUP_INTERVAL_MINUTES: optional(\n    int(0, 1440).refine((m) => m === 0 || 1440 % m === 0, 'must be 0 (off) or divide 1440 (a day), e.g. 60, 360, 1440'),\n  ).default(1440),\n  /** The UTC time the schedule is anchored on, HH:MM. */\n  BACKUP_AT: optional(z.string().regex(/^([01]\\d|2[0-3]):[0-5]\\d$/, 'must be a UTC time such as 03:17')).default(\n    '03:17',\n  ),\n  /** The newest backups kept per database. */\n  BACKUP_KEEP: optional(int(1, 10_000)).default(DEFAULT_KEEP.newest),\n  /** Also keep the newest backup of each of this many most recent UTC days. */\n  BACKUP_KEEP_DAILY: optional(int(0, 10_000)).default(DEFAULT_KEEP.daily),\n  /** The internal metrics port. Unset: no metrics listener. */\n  METRICS_PORT: optional(int(1, 65_535)),\n  METRICS_HOST: optional(z.string()).default('0.0.0.0'),\n});\n\n/** Reads the backup and metrics settings from the environment, or lists every problem. */\nexport const parseOpsEnv = (\n  env: Readonly<Record<string, string | undefined>>,\n): { ok: true; settings: OpsSettings } | { ok: false; issues: string[] } => {\n  const parsed = OpsEnv.safeParse(env);\n  if (!parsed.success)\n    return {\n      ok: false,\n      issues: parsed.error.issues.map((issue) => `${issue.path.join('.') || 'env'}: ${issue.message}`),\n    };\n  const e = parsed.data;\n  const [hours, minutes] = e.BACKUP_AT.split(':').map(Number);\n  const anchor = (hours ?? 0) * 60 + (minutes ?? 0);\n  return {\n    ok: true,\n    settings: {\n      backup: {\n        schedule:\n          e.BACKUP_INTERVAL_MINUTES === 0\n            ? null\n            : { intervalMinutes: e.BACKUP_INTERVAL_MINUTES, offsetMinutes: anchor % e.BACKUP_INTERVAL_MINUTES },\n        keep: { newest: e.BACKUP_KEEP, daily: e.BACKUP_KEEP_DAILY },\n      },\n      metrics: e.METRICS_PORT === undefined ? null : { host: e.METRICS_HOST, port: e.METRICS_PORT },\n    },\n  };\n};\n\nexport const describeSchedule = (schedule: BackupSchedule | null): string => {\n  if (schedule === null) return 'off';\n  const hhmm = (m: number) => `${String(Math.floor(m / 60)).padStart(2, '0')}:${String(m % 60).padStart(2, '0')}`;\n  return schedule.intervalMinutes === 1440\n    ? `daily at ${hhmm(schedule.offsetMinutes)} UTC`\n    : `every ${String(schedule.intervalMinutes)} min at +${String(schedule.offsetMinutes)} min (UTC)`;\n};\n\nexport interface Timers {\n  now(): number;\n  /** Calls `fire` after `ms`; the returned function cancels it. */\n  after(ms: number, fire: () => void): () => void;\n}\n\nexport const systemTimers: Timers = {\n  now: () => Date.now(),\n  after: (ms, fire) => {\n    const handle = setTimeout(fire, Math.max(0, ms));\n    // The service's own server keeps the process alive; a pending backup must not.\n    handle.unref();\n    return () => clearTimeout(handle);\n  },\n};\n\nexport interface Scheduler {\n  /** The next scheduled run (epoch ms), or null once stopped. */\n  next(): number | null;\n  /** Cancels the timer and waits for a run in progress. */\n  stop(): Promise<void>;\n}\n\n/** Runs `run` on the schedule until stopped. `run` must not throw; it reports its own outcome. */\nexport const startSchedule = (\n  schedule: BackupSchedule,\n  run: () => Promise<void>,\n  timers: Timers = systemTimers,\n): Scheduler => {\n  let stopped = false;\n  let nextAt: number | null = null;\n  let cancel: (() => void) | null = null;\n  let running: Promise<void> | null = null;\n\n  const arm = (): void => {\n    if (stopped) return;\n    const at = nextBackupAt(timers.now(), schedule);\n    nextAt = at;\n    const wake = (): void => {\n      if (stopped) return;\n      // Timers can fire early; wait out the rest rather than running before the scheduled time.\n      if (timers.now() < at) {\n        cancel = timers.after(at - timers.now(), wake);\n        return;\n      }\n      running = run().finally(() => {\n        running = null;\n        arm();\n      });\n    };\n    cancel = timers.after(at - timers.now(), wake);\n  };\n  arm();\n\n  return {\n    next: () => (stopped ? null : nextAt),\n    stop: async () => {\n      stopped = true;\n      nextAt = null;\n      cancel?.();\n      await running;\n    },\n  };\n};\n\nexport interface ScheduledDatabase {\n  /** The live database file. */\n  readonly file: string;\n  /** Where its copies go; default `backups/` beside it. */\n  readonly dir?: string;\n  /** Skip, rather than fail, while the database doesn't exist yet. */\n  readonly ifExists?: boolean;\n}\n\nexport type BackupReport =\n  BackupResult | { readonly event: 'backup_failed'; readonly database: string; readonly error: string };\n\nexport interface ScheduleBackupsOptions {\n  readonly settings: BackupSettings;\n  readonly databases: readonly ScheduledDatabase[];\n  /** One call per database per run: the service writes it as a log line in its own format. */\n  readonly report: (report: BackupReport) => void;\n  readonly timers?: Timers;\n}\n\n/** Backs up each database on the schedule. Returns null when the schedule is off. */\nexport const scheduleBackups = (options: ScheduleBackupsOptions): Scheduler | null => {\n  const { schedule, keep } = options.settings;\n  if (schedule === null) return null;\n  return startSchedule(\n    schedule,\n    async () => {\n      for (const db of options.databases) {\n        try {\n          options.report(\n            await backupDatabase(db.file, db.dir ?? join(dirname(db.file), 'backups'), {\n              keep,\n              ifExists: db.ifExists === true,\n            }),\n          );\n        } catch (error) {\n          options.report({\n            event: 'backup_failed',\n            database: db.file,\n            error: error instanceof Error ? error.message : String(error),\n          });\n        }\n      }\n    },\n    options.timers,\n  );\n};\n"],"mappings":"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"}

package/package.json

@@ -1,20 +1,49 @@
 {
   "name": "@joystyk/ops",
-  "version": "0.0.0",
-  "description": "Reserved for the first Joystyk library release.",
+  "version": "0.2.0",
+  "description": "Node operations helpers: scheduled SQLite backups, internal Prometheus metrics and canonical network rate-limit keys.",
+  "private": false,
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "zod": "4.6.5"
+  },
+  "devDependencies": {
+    "@types/node": "24.10.1",
+    "typescript": "5.9.3",
+    "vitest": "4.1.11"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=24.15.0"
+  },
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/joystyk-games/game-libraries.git",
     "directory": "packages/ops"
   },
-  "homepage": "https://github.com/joystyk-games/game-libraries",
-  "files": [
-    "README.md",
-    "LICENSE",
-    "NOTICE"
-  ],
-  "publishConfig": {
-    "access": "public"
+  "homepage": "https://github.com/joystyk-games/game-libraries/tree/main/packages/ops#readme",
+  "bugs": {
+    "url": "https://github.com/joystyk-games/game-libraries/issues"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "node ../../scripts/build-package.ts"
   }
-}
+}