@trazum/cli 1.41.0 → 1.43.0

package/src/store-fs.ts

@@ -0,0 +1,157 @@
+/**
+ * Where the store actually lives.
+ *
+ * The core decides what a record is and when two are the same; this decides
+ * where the bytes go. Split that way for the reason every module here is:
+ * `@trazum/core` stays browser-safe, and the CLI keeps its monopoly on I/O.
+ *
+ * **Append-only, one buffer per write.** A pull appends a single block and
+ * never rewrites what is already there. Two consequences worth stating: a
+ * crash during a write loses the tail of one block rather than a year of
+ * measurements, and two runs writing at once interleave whole blocks rather
+ * than half-lines. Compaction is a separate, explicit errand — `store
+ * --prune` — because collapsing a log is the one operation that destroys
+ * something, and it should never happen as a side effect of a pull.
+ *
+ * **A line that will not parse is kept, counted and skipped.** The store is a
+ * file a human may open, a backup may truncate and a merge may mangle. Losing
+ * the whole month because one line is broken would be the worst possible
+ * response; so would silently pretending the month is complete.
+ */
+
+import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { resolveStore } from '@trazum/core';
+import type { ResolvedStore, StoreRecord } from '@trazum/core';
+
+/** The directory name, relative to wherever the caller roots the store. */
+export const STORE_DIR = '.trazum/store';
+
+/** Records are filed by the UTC month their window starts in. */
+function monthOf(record: StoreRecord): string {
+  return new Date(record.fromMs).toISOString().slice(0, 7);
+}
+
+export interface StoreReadResult {
+  resolved: ResolvedStore;
+  /** Lines that would not parse: counted and named by file, never dropped quietly. */
+  unreadable: { file: string; line: number }[];
+  /** Files read, so an empty store can be told from an unread one. */
+  files: string[];
+}
+
+/**
+ * Reads every record in the store.
+ *
+ * Returns an empty result rather than throwing when the store does not exist:
+ * "you have not stored anything yet" is a state, not an error, and the caller
+ * says so in a sentence that names `trazum connect`.
+ */
+export async function readStore(root: string): Promise<StoreReadResult> {
+  const dir = join(root, STORE_DIR);
+  const records: StoreRecord[] = [];
+  const unreadable: { file: string; line: number }[] = [];
+  const files: string[] = [];
+
+  let providers: string[];
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    providers = entries.filter((e) => e.isDirectory()).map((e) => e.name);
+  } catch {
+    return { resolved: resolveStore([]), unreadable, files };
+  }
+
+  for (const provider of providers.sort()) {
+    const providerDir = join(dir, provider);
+    let months: string[];
+    try {
+      months = (await readdir(providerDir)).filter((name) => name.endsWith('.jsonl')).sort();
+    } catch {
+      continue;
+    }
+    for (const month of months) {
+      const path = join(providerDir, month);
+      files.push(join(STORE_DIR, provider, month));
+      const text = await readFile(path, 'utf8');
+      for (const [index, line] of text.split('\n').entries()) {
+        if (line.trim() === '') continue;
+        try {
+          const parsed = JSON.parse(line) as StoreRecord;
+          if (typeof parsed?.provider === 'string' && typeof parsed?.fromMs === 'number') {
+            records.push(parsed);
+          } else {
+            unreadable.push({ file: join(STORE_DIR, provider, month), line: index + 1 });
+          }
+        } catch {
+          unreadable.push({ file: join(STORE_DIR, provider, month), line: index + 1 });
+        }
+      }
+    }
+  }
+
+  return { resolved: resolveStore(records), unreadable, files };
+}
+
+/**
+ * Appends records, grouped into one write per month file.
+ *
+ * Nothing already on disk is read, rewritten or resolved here: convergence
+ * happens when the store is *read*, which is what keeps a write cheap enough
+ * to run on a schedule and impossible to corrupt by racing.
+ */
+export async function appendRecords(root: string, records: readonly StoreRecord[]): Promise<number> {
+  if (records.length === 0) return 0;
+  const byFile = new Map<string, StoreRecord[]>();
+  for (const record of records) {
+    const key = join(record.provider, `${monthOf(record)}.jsonl`);
+    const list = byFile.get(key) ?? [];
+    list.push(record);
+    byFile.set(key, list);
+  }
+
+  for (const [relative, list] of byFile) {
+    const path = join(root, STORE_DIR, relative);
+    await mkdir(join(path, '..'), { recursive: true });
+    const block = `${list.map((record) => JSON.stringify(record)).join('\n')}\n`;
+    await writeFile(path, block, { flag: 'a', mode: 0o600 });
+  }
+  return records.length;
+}
+
+/**
+ * Rewrites the store with exactly the records given.
+ *
+ * The one operation that destroys something, so it is only ever reached from
+ * an explicit `--prune`. Each month file is written whole, and a month left
+ * with nothing is written empty rather than removed — a missing file and an
+ * empty one say different things to whoever looks next.
+ */
+export async function rewriteStore(root: string, records: readonly StoreRecord[]): Promise<void> {
+  const dir = join(root, STORE_DIR);
+  const existing = new Set<string>();
+  try {
+    for (const provider of await readdir(dir)) {
+      for (const month of await readdir(join(dir, provider)).catch(() => [])) {
+        if (month.endsWith('.jsonl')) existing.add(join(provider, month));
+      }
+    }
+  } catch {
+    // Nothing stored yet: the writes below create what is needed.
+  }
+
+  const byFile = new Map<string, StoreRecord[]>();
+  for (const record of records) {
+    const key = join(record.provider, `${monthOf(record)}.jsonl`);
+    const list = byFile.get(key) ?? [];
+    list.push(record);
+    byFile.set(key, list);
+  }
+
+  for (const relative of new Set([...existing, ...byFile.keys()])) {
+    const list = byFile.get(relative) ?? [];
+    const path = join(dir, relative);
+    await mkdir(join(path, '..'), { recursive: true });
+    const block = list.length === 0 ? '' : `${list.map((r) => JSON.stringify(r)).join('\n')}\n`;
+    await writeFile(path, block, { mode: 0o600 });
+  }
+}

package/src/watch-run.ts

@@ -0,0 +1,126 @@
+/**
+ * One cycle of watching, and the state that survives a restart.
+ *
+ * `--once` is the primitive: pull the window, keep it, evaluate the gates,
+ * emit what crossed, save state. A cron entry runs exactly that, and so does
+ * every test. The foreground loop is this function in a timer, so there is one
+ * code path and no daemon-only behaviour that nobody exercises.
+ *
+ * **The state file is what makes a restart honest.** Without it a resumed
+ * watcher re-alerts on yesterday's crossing (noise nobody reads) and implies
+ * it was watching the whole time (a claim it cannot make). With it, the
+ * crossing stays quiet and the unwatched stretch gets named once.
+ */
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { SAFE_FETCH_INIT } from '@trazum/core/node';
+import type { WatchCrossing } from '@trazum/core';
+
+export const WATCH_STATE_FILE = '.trazum/watch.json';
+
+export const WATCH_STATE_VERSION = 1;
+
+export interface WatchState {
+  v: number;
+  /** When the last cycle ran, so a long silence can be told from a first run. */
+  lastCycleMs: number;
+  /** How far the measurements reached, for the coverage gap. */
+  lastCoveredToMs: number | null;
+  /** Gate keys already alerted on, so a restart is not amnesia. */
+  fired: Record<string, number>;
+}
+
+export async function readWatchState(root: string): Promise<WatchState | null> {
+  try {
+    const parsed = JSON.parse(await readFile(join(root, WATCH_STATE_FILE), 'utf8')) as WatchState;
+    if (parsed?.v !== WATCH_STATE_VERSION) return null;
+    return parsed;
+  } catch {
+    // No state, or state this version cannot read: a first cycle either way,
+    // which is a state the caller reports rather than an error.
+    return null;
+  }
+}
+
+export async function writeWatchState(root: string, state: WatchState): Promise<void> {
+  const path = join(root, WATCH_STATE_FILE);
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+}
+
+/**
+ * Whether a webhook URL is one this tool will post to.
+ *
+ * **This is not the SSRF case and the difference matters.** `checkedEndpoint`
+ * exists because a *request body* must never name a host: an anonymous caller
+ * pointing a shared server at an internal address is somebody else's machine
+ * reaching somewhere it was never meant to. Here the URL is in the operator's
+ * own config, on their own machine, and pointing it at their own alerting
+ * daemon on loopback is the ordinary case rather than the attack.
+ *
+ * So loopback is allowed and plain http is allowed *only* there, while two
+ * rules stay absolute: no credentials embedded in the URL, because a URL ends
+ * up in logs and shell history; and https everywhere else, because an alert
+ * carries spend figures across a network.
+ */
+export type WebhookRejection = 'invalid-url' | 'credentials-in-url' | 'insecure-scheme';
+
+export function checkWebhook(raw: string): { ok: true; url: URL } | { ok: false; reason: WebhookRejection } {
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    return { ok: false, reason: 'invalid-url' };
+  }
+  if (url.username !== '' || url.password !== '') {
+    return { ok: false, reason: 'credentials-in-url' };
+  }
+  const loopback =
+    url.hostname === 'localhost' ||
+    url.hostname === '127.0.0.1' ||
+    url.hostname === '[::1]' ||
+    url.hostname === '::1';
+  if (url.protocol === 'https:') return { ok: true, url };
+  if (url.protocol === 'http:' && loopback) return { ok: true, url };
+  return { ok: false, reason: 'insecure-scheme' };
+}
+
+/**
+ * The alert payload.
+ *
+ * Figures and gate names, never prompt text — the store has never held any and
+ * neither does this. Every crossing carries its own provenance, so a receiver
+ * that fans these into a dashboard cannot lose track of what kind of number it
+ * is holding.
+ */
+export interface WatchAlert {
+  schemaVersion: 1;
+  firedAtMs: number;
+  crossings: WatchCrossing[];
+}
+
+export async function postWebhook(
+  url: URL,
+  alert: WatchAlert,
+  fetchImpl: typeof fetch = fetch,
+): Promise<{ ok: boolean; status: number | null; error: string | null }> {
+  try {
+    const response = await fetchImpl(url.toString(), {
+      ...SAFE_FETCH_INIT,
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(alert),
+      signal: AbortSignal.timeout(10_000),
+    });
+    return { ok: response.ok, status: response.status, error: null };
+  } catch (error) {
+    /**
+     * A webhook that will not deliver must not take the alert down with it.
+     * The exit code and the stdout event have already carried the crossing;
+     * losing those because a receiver is down would make the quietest failure
+     * the loudest one.
+     */
+    return { ok: false, status: null, error: error instanceof Error ? error.message : String(error) };
+  }
+}