@richhaase/c2 0.3.2 → 0.4.0

package/src/data.test.ts

@@ -0,0 +1,236 @@
+import { expect, test } from "bun:test";
+import { mkdir, mkdtemp, readdir, readFile, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { initStore, inspectDataDir, moveStore, storeSummary } from "./data.ts";
+import { pathsFor } from "./paths.ts";
+import { readMeta, readWorkouts } from "./storage.ts";
+
+const NOW = new Date("2026-07-05T12:00:00");
+
+async function tempRoot(): Promise<string> {
+  return mkdtemp(join(tmpdir(), "c2-data-test-"));
+}
+
+const WORKOUT_LINE = JSON.stringify({
+  id: 1,
+  user_id: 1,
+  date: "2026-07-01 08:00:00",
+  distance: 8000,
+  type: "rower",
+  time: 12000,
+  time_formatted: "20:00.0",
+});
+
+test("inspect reports missing directory", async () => {
+  const base = await tempRoot();
+  const paths = pathsFor(join(base, "nope"));
+  const insp = await inspectDataDir(paths);
+  expect(insp.state).toBe("missing");
+  expect(insp.writable).toBe(true);
+});
+
+test("inspect reports empty, store, legacy store, and foreign", async () => {
+  const base = await tempRoot();
+
+  const empty = pathsFor(join(base, "empty"));
+  await mkdir(empty.root);
+  expect((await inspectDataDir(empty)).state).toBe("empty");
+
+  const store = pathsFor(join(base, "store"));
+  await mkdir(store.root);
+  await initStore(store, NOW);
+  expect((await inspectDataDir(store)).state).toBe("store");
+
+  const legacy = pathsFor(join(base, "legacy"));
+  await mkdir(join(legacy.root, "strokes"), { recursive: true });
+  await writeFile(legacy.workouts, `${WORKOUT_LINE}\n`, "utf-8");
+  expect((await inspectDataDir(legacy)).state).toBe("store");
+
+  const foreign = pathsFor(join(base, "foreign"));
+  await mkdir(foreign.root);
+  await writeFile(join(foreign.root, "novel.docx"), "chapter one", "utf-8");
+  expect((await inspectDataDir(foreign)).state).toBe("foreign");
+});
+
+test("initStore creates directories and meta once", async () => {
+  const base = await tempRoot();
+  const paths = pathsFor(join(base, "init"));
+  await mkdir(paths.root);
+  await initStore(paths, NOW);
+
+  const meta = await readMeta(paths);
+  expect(meta?.schema_version).toBe(1);
+  expect(meta?.created).toBe(NOW.toISOString());
+
+  await initStore(paths, new Date("2027-01-01T00:00:00"));
+  const again = await readMeta(paths);
+  expect(again?.created).toBe(NOW.toISOString());
+});
+
+test("storeSummary counts contents", async () => {
+  const base = await tempRoot();
+  const paths = pathsFor(join(base, "sum"));
+  await mkdir(paths.root);
+  await initStore(paths, NOW);
+  await writeFile(paths.workouts, `${WORKOUT_LINE}\n`, "utf-8");
+  await writeFile(paths.strokeFile(1), '{"t":1}\n', "utf-8");
+  await writeFile(
+    join(paths.notesDir, "01A.json"),
+    JSON.stringify({
+      id: "01A",
+      date: "2026-07-01T08:00:00-06:00",
+      type: "observation",
+      body: "counted",
+      author: "athlete",
+    }),
+    "utf-8",
+  );
+
+  const summary = await storeSummary(paths);
+  expect(summary.workouts).toBe(1);
+  expect(summary.firstDate).toBe("2026-07-01");
+  expect(summary.strokeFiles).toBe(1);
+  expect(summary.notes).toBe(1);
+  expect(summary.schemaVersion).toBe(1);
+});
+
+test("missing nested paths are creatable, not rejected", async () => {
+  const base = await tempRoot();
+  const nested = pathsFor(join(base, "a", "b", "c"));
+  const insp = await inspectDataDir(nested);
+  expect(insp.state).toBe("missing");
+  expect(insp.writable).toBe(true);
+
+  await initStore(nested, NOW);
+  expect((await inspectDataDir(nested)).state).toBe("store");
+});
+
+test("moveStore tolerates pre-existing dotfiles in the target", async () => {
+  const base = await tempRoot();
+  const from = pathsFor(join(base, "src"));
+  await mkdir(from.root);
+  await initStore(from, NOW);
+  await writeFile(from.workouts, `${WORKOUT_LINE}\n`, "utf-8");
+
+  const to = pathsFor(join(base, "gitrepo"));
+  await mkdir(join(to.root, ".git"), { recursive: true });
+  await writeFile(join(to.root, ".git", "HEAD"), "ref: refs/heads/main\n", "utf-8");
+  await writeFile(join(to.root, ".DS_Store"), "junk", "utf-8");
+
+  const src = await treeStatsPublic(from.root);
+  const copied = await moveStore(from, to);
+  expect(copied.files).toBe(src.files);
+  expect((await readWorkouts(to)).length).toBe(1);
+});
+
+async function treeStatsPublic(dir: string): Promise<{ files: number }> {
+  const { readdir: rd, stat: st } = await import("node:fs/promises");
+  let files = 0;
+  for (const e of await rd(dir, { withFileTypes: true })) {
+    const full = join(dir, e.name);
+    if (e.isDirectory()) files += (await treeStatsPublic(full)).files;
+    else {
+      await st(full);
+      files++;
+    }
+  }
+  return { files };
+}
+
+test("moveStore never copies dotfiles and preserves target VCS metadata", async () => {
+  const base = await tempRoot();
+  const from = pathsFor(join(base, "src"));
+  await mkdir(from.root);
+  await initStore(from, NOW);
+  await writeFile(from.workouts, `${WORKOUT_LINE}\n`, "utf-8");
+  await writeFile(join(from.root, ".DS_Store"), "source junk", "utf-8");
+  await mkdir(join(from.root, ".git"));
+  await writeFile(join(from.root, ".git", "HEAD"), "ref: refs/heads/source\n", "utf-8");
+
+  const to = pathsFor(join(base, "synced"));
+  await mkdir(join(to.root, ".git"), { recursive: true });
+  await writeFile(join(to.root, ".git", "HEAD"), "ref: refs/heads/target\n", "utf-8");
+  await writeFile(join(to.root, ".DS_Store"), "different pre-existing junk!", "utf-8");
+
+  const copied = await moveStore(from, to);
+  expect(copied.files).toBeGreaterThanOrEqual(2);
+  expect((await readWorkouts(to)).length).toBe(1);
+  expect(await readFile(join(to.root, ".git", "HEAD"), "utf-8")).toBe("ref: refs/heads/target\n");
+  expect(await readFile(join(to.root, ".DS_Store"), "utf-8")).toBe("different pre-existing junk!");
+});
+
+test("generic folder names alone are not adopted as stores", async () => {
+  const base = await tempRoot();
+
+  const notesOnly = pathsFor(join(base, "notes-only"));
+  await mkdir(join(notesOnly.root, "notes"), { recursive: true });
+  expect((await inspectDataDir(notesOnly)).state).toBe("foreign");
+
+  const planOnly = pathsFor(join(base, "plan-only"));
+  await mkdir(planOnly.root);
+  await writeFile(planOnly.plan, "# someone else's plan\n", "utf-8");
+  expect((await inspectDataDir(planOnly)).state).toBe("foreign");
+});
+
+test("a directory with only a foreign meta.json is not adopted", async () => {
+  const base = await tempRoot();
+  const paths = pathsFor(join(base, "other-tool"));
+  await mkdir(paths.root);
+  await writeFile(paths.meta, JSON.stringify({ name: "some other tool" }), "utf-8");
+  expect((await inspectDataDir(paths)).state).toBe("foreign");
+});
+
+test("a store missing meta.json but with current-layout dirs is recognized", async () => {
+  const base = await tempRoot();
+  const paths = pathsFor(join(base, "meta-lost"));
+  await mkdir(join(paths.root, "strokes"), { recursive: true });
+  await mkdir(join(paths.root, "reports"), { recursive: true });
+  await writeFile(paths.workouts, `${WORKOUT_LINE}\n`, "utf-8");
+  await writeFile(paths.plan, "# plan\n", "utf-8");
+  expect((await inspectDataDir(paths)).state).toBe("store");
+});
+
+test("a file in the path yields foreign, not a raw ENOTDIR", async () => {
+  const base = await tempRoot();
+  const filePath = join(base, "regular-file");
+  await writeFile(filePath, "hi", "utf-8");
+  const nested = pathsFor(join(filePath, "sub"));
+  const insp = await inspectDataDir(nested);
+  expect(insp.state).toBe("foreign");
+  expect(insp.writable).toBe(false);
+});
+
+test("corrupt meta.json is tolerated, not fatal", async () => {
+  const base = await tempRoot();
+  const paths = pathsFor(join(base, "corrupt"));
+  await mkdir(paths.root);
+  await initStore(paths, NOW);
+  await writeFile(paths.meta, "{ truncated", "utf-8");
+
+  const insp = await inspectDataDir(paths);
+  expect(insp.state).toBe("store");
+  expect(await readMeta(paths)).toBeNull();
+  const summary = await storeSummary(paths);
+  expect(summary.schemaVersion).toBeNull();
+});
+
+test("moveStore copies, verifies, and refuses non-empty targets", async () => {
+  const base = await tempRoot();
+  const from = pathsFor(join(base, "src"));
+  await mkdir(from.root);
+  await initStore(from, NOW);
+  await writeFile(from.workouts, `${WORKOUT_LINE}\n`, "utf-8");
+  await writeFile(from.strokeFile(1), '{"t":1}\n', "utf-8");
+
+  const to = pathsFor(join(base, "dst"));
+  const copied = await moveStore(from, to);
+  expect(copied.files).toBeGreaterThanOrEqual(3);
+  expect((await readWorkouts(to)).length).toBe(1);
+  expect((await readdir(to.strokesDir)).length).toBe(1);
+
+  const occupied = pathsFor(join(base, "occupied"));
+  await mkdir(occupied.root);
+  await writeFile(join(occupied.root, "file.txt"), "x", "utf-8");
+  await expect(moveStore(from, occupied)).rejects.toThrow("not empty");
+});

package/src/data.ts

@@ -0,0 +1,200 @@
+import { cp, mkdir, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import { calendarDay } from "./models.ts";
+import { readAllNotes } from "./notes.ts";
+import type { DataPaths } from "./paths.ts";
+import { readMeta, readWorkouts, SCHEMA_VERSION, writeMeta } from "./storage.ts";
+
+export type DirState = "missing" | "store" | "empty" | "foreign";
+
+export interface DirInspection {
+  path: string;
+  state: DirState;
+  writable: boolean;
+}
+
+export interface StoreSummary {
+  workouts: number;
+  firstDate: string;
+  lastDate: string;
+  strokeFiles: number;
+  notes: number;
+  schemaVersion: number | null;
+  lastSync: string | null;
+}
+
+const STORE_MARKERS = new Set([
+  "workouts.jsonl",
+  "strokes",
+  "notes",
+  "reports",
+  "plan.md",
+  "playbook.md",
+]);
+
+export async function inspectDataDir(paths: DataPaths): Promise<DirInspection> {
+  let state: DirState;
+  try {
+    const s = await stat(paths.root);
+    if (!s.isDirectory()) {
+      return { path: paths.root, state: "foreign", writable: false };
+    }
+    const meta = await readMeta(paths);
+    const entries = (await readdir(paths.root)).filter((e) => !e.startsWith("."));
+    if (meta != null && typeof meta.schema_version === "number") {
+      state = "store";
+    } else if (entries.length === 0) {
+      state = "empty";
+    } else {
+      const hasStrongMarker = entries.includes("workouts.jsonl") || entries.includes("strokes");
+      const allKnown = entries.every((e) => STORE_MARKERS.has(e) || e === "meta.json");
+      state = hasStrongMarker && allKnown ? "store" : "foreign";
+    }
+  } catch (err: unknown) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === "ENOTDIR") {
+      return { path: paths.root, state: "foreign", writable: false };
+    }
+    if (code !== "ENOENT") throw err;
+    return { path: paths.root, state: "missing", writable: await parentWritable(paths.root) };
+  }
+  return { path: paths.root, state, writable: await probeWritable(paths.root) };
+}
+
+async function parentWritable(path: string): Promise<boolean> {
+  let current = path;
+  for (;;) {
+    const parent = dirname(current);
+    if (parent === current) return false;
+    try {
+      await stat(parent);
+      return probeWritable(parent);
+    } catch (err: unknown) {
+      if ((err as NodeJS.ErrnoException).code !== "ENOENT") return false;
+      current = parent;
+    }
+  }
+}
+
+async function probeWritable(dir: string): Promise<boolean> {
+  const probe = join(dir, `.c2-probe-${process.pid}`);
+  try {
+    await writeFile(probe, "", "utf-8");
+    await rm(probe);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function rejectForeignStore(paths: DataPaths): Promise<string | null> {
+  const inspection = await inspectDataDir(paths);
+  if (inspection.state === "foreign") {
+    return `${paths.root} exists but is not a c2 data store. Fix data_dir via \`c2 setup\`.`;
+  }
+  return null;
+}
+
+export async function ensureStoreForWrite(paths: DataPaths, now: Date): Promise<string | null> {
+  const inspection = await inspectDataDir(paths);
+  if (inspection.state === "foreign") {
+    return `${paths.root} exists but is not a c2 data store. Fix data_dir via \`c2 setup\`.`;
+  }
+  if (!inspection.writable) {
+    return `Cannot write to ${paths.root}.`;
+  }
+  await initStore(paths, now);
+  return null;
+}
+
+export async function initStore(paths: DataPaths, now: Date): Promise<void> {
+  await mkdir(paths.strokesDir, { recursive: true });
+  await mkdir(paths.archiveDir, { recursive: true });
+  await mkdir(paths.reportsDir, { recursive: true });
+  const meta = await readMeta(paths);
+  if (meta == null) {
+    await writeMeta(paths, { schema_version: SCHEMA_VERSION, created: now.toISOString() });
+  }
+}
+
+async function listIfPresent(dir: string): Promise<string[]> {
+  try {
+    return await readdir(dir);
+  } catch (err: unknown) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code === "ENOENT" || code === "ENOTDIR") return [];
+    throw err;
+  }
+}
+
+export async function storeSummary(paths: DataPaths): Promise<StoreSummary> {
+  const workouts = await readWorkouts(paths);
+  const days = workouts.map(calendarDay).sort();
+  const strokeFiles = (await listIfPresent(paths.strokesDir)).filter((f) =>
+    f.endsWith(".jsonl"),
+  ).length;
+  const notes = (await readAllNotes(paths)).length;
+  const meta = await readMeta(paths);
+  return {
+    workouts: workouts.length,
+    firstDate: days[0] ?? "",
+    lastDate: days[days.length - 1] ?? "",
+    strokeFiles,
+    notes,
+    schemaVersion: meta?.schema_version ?? null,
+    lastSync: meta?.last_sync ?? null,
+  };
+}
+
+export async function moveStore(
+  from: DataPaths,
+  to: DataPaths,
+): Promise<{ files: number; bytes: number }> {
+  const target = await inspectDataDir(to);
+  if (target.state === "store" || target.state === "foreign") {
+    throw new Error(`target ${to.root} is not empty`);
+  }
+  if (!target.writable) {
+    throw new Error(`target ${to.root} is not writable`);
+  }
+  await mkdir(to.root, { recursive: true });
+  await cp(from.root, to.root, {
+    recursive: true,
+    filter: (src) => src === from.root || !basename(src).startsWith("."),
+  });
+  return verifyCopy(from.root, to.root);
+}
+
+async function verifyCopy(
+  fromDir: string,
+  toDir: string,
+): Promise<{ files: number; bytes: number }> {
+  let files = 0;
+  let bytes = 0;
+  for (const e of await readdir(fromDir, { withFileTypes: true })) {
+    if (e.name.startsWith(".")) continue;
+    const src = join(fromDir, e.name);
+    const dst = join(toDir, e.name);
+    if (e.isDirectory()) {
+      const sub = await verifyCopy(src, dst);
+      files += sub.files;
+      bytes += sub.bytes;
+    } else {
+      const srcStat = await stat(src);
+      let dstStat: Awaited<ReturnType<typeof stat>>;
+      try {
+        dstStat = await stat(dst);
+      } catch {
+        throw new Error(`copy verification failed: ${dst} is missing`);
+      }
+      if (dstStat.size !== srcStat.size) {
+        throw new Error(
+          `copy verification failed: ${dst} has ${dstStat.size} bytes, expected ${srcStat.size}`,
+        );
+      }
+      files++;
+      bytes += srcStat.size;
+    }
+  }
+  return { files, bytes };
+}

package/src/display.test.ts

@@ -155,7 +155,6 @@ describe("formatWorkoutLine", () => {
   });
 
   test("appends [IVL rest M:SS.S] tag for interval workouts", () => {
-    // Real 2026-04-11 session: 6x500m, 14:22.6 work, 6:00 rest.
     const w = makeWorkout({
       date: "2026-04-11 09:14:00",
       distance: 3000,
@@ -170,7 +169,6 @@ describe("formatWorkoutLine", () => {
     });
     const line = formatWorkoutLine(w, "01/02");
     expect(line).toContain("[IVL rest 6:00.0]");
-    // Pace comes from work time, not elapsed — must be 2:23.8, not 3:23.8.
     expect(line).toContain("2:23.8/500m");
   });
 

package/src/display.ts

@@ -1,5 +1,12 @@
 import type { Workout } from "./models.ts";
-import { formatSeconds, isIntervalWorkout, pace500m, parsedDate, restSeconds } from "./models.ts";
+import {
+  formatSeconds,
+  isIntervalWorkout,
+  pace500m,
+  pace500mSeconds,
+  parsedDate,
+  restSeconds,
+} from "./models.ts";
 
 export function formatMeters(m: number): string {
   return m.toLocaleString("en-US");
@@ -51,6 +58,28 @@ export function formatWorkoutLine(w: Workout, dateFormat: string): string {
   return `${dateStr}  ${distance.padStart(7)}  ${w.time_formatted.padStart(8)}  ${pace.padStart(7)}/500m  ${spm.padStart(5)}  ${hr.padStart(6)}  ${df.padStart(4)}${tagSuffix}`;
 }
 
+export function workoutJSON(w: Workout) {
+  const paceSecs = pace500mSeconds(w);
+  const rest = restSeconds(w);
+  return {
+    id: w.id,
+    date: w.date,
+    distance: w.distance,
+    time_tenths: w.time,
+    time_formatted: w.time_formatted,
+    pace_500m: paceSecs > 0 ? pace500m(w) : null,
+    pace_500m_seconds: paceSecs > 0 ? Math.round(paceSecs * 10) / 10 : null,
+    stroke_rate: w.stroke_rate ?? null,
+    hr_avg: w.heart_rate?.average ?? null,
+    drag_factor: w.drag_factor ?? null,
+    workout_type: w.workout_type ?? null,
+    interval: isIntervalWorkout(w),
+    rest_seconds: rest > 0 ? rest : null,
+    comments: w.comments ?? null,
+    has_stroke_data: w.stroke_data ?? false,
+  };
+}
+
 export function sparkBar(value: number, max: number): string {
   if (max === 0) return "";
   const BAR_WIDTH = 20;
@@ -70,5 +99,5 @@ export function trendArrow(prev: number, curr: number): string {
 
 export function paceArrow(prev: number, curr: number): string {
   if (prev === 0) return " ";
-  return trendArrow(curr, prev); // reversed: lower pace is better
+  return trendArrow(curr, prev);
 }

package/src/doctor.ts

@@ -0,0 +1,174 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { isNoteShaped, serializeNote } from "./notes.ts";
+import type { DataPaths } from "./paths.ts";
+
+export interface DoctorReport {
+  issues: string[];
+  checkedFiles: number;
+}
+
+async function readOrNull(path: string, label: string, issues: string[]): Promise<string | null> {
+  try {
+    return await readFile(path, "utf-8");
+  } catch (err: unknown) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code !== "ENOENT") {
+      issues.push(`${label}: unreadable (${code ?? (err as Error).message})`);
+    }
+    return null;
+  }
+}
+
+async function listDir(dir: string, label: string, issues: string[]): Promise<string[]> {
+  try {
+    return await readdir(dir);
+  } catch (err: unknown) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code !== "ENOENT") {
+      issues.push(`${label}: unreadable (${code ?? (err as Error).message})`);
+    }
+    return [];
+  }
+}
+
+const STROKE_FIELDS = ["t", "d", "p", "spm", "hr"] as const;
+
+function isStrokeShaped(parsed: unknown): boolean {
+  if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) return false;
+  const row = parsed as Record<string, unknown>;
+  return STROKE_FIELDS.every((k) => row[k] === undefined || typeof row[k] === "number");
+}
+
+export async function runDoctor(paths: DataPaths): Promise<DoctorReport> {
+  const issues: string[] = [];
+  let checkedFiles = 0;
+
+  const meta = await readOrNull(paths.meta, "meta.json", issues);
+  if (meta != null) {
+    checkedFiles++;
+    try {
+      const parsed = JSON.parse(meta);
+      if (typeof parsed?.schema_version !== "number") {
+        issues.push("meta.json: missing numeric schema_version");
+      }
+    } catch {
+      issues.push("meta.json: not valid JSON");
+    }
+  }
+
+  const workouts = await readOrNull(paths.workouts, "workouts.jsonl", issues);
+  if (workouts != null) {
+    checkedFiles++;
+    let lineNo = 0;
+    for (const line of workouts.split("\n")) {
+      lineNo++;
+      if (line.trim() === "") continue;
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(line);
+      } catch {
+        issues.push(`workouts.jsonl: line ${lineNo} is not valid JSON`);
+        continue;
+      }
+      const w = parsed as { id?: unknown; date?: unknown; distance?: unknown; time?: unknown };
+      if (
+        parsed == null ||
+        typeof parsed !== "object" ||
+        typeof w.id !== "number" ||
+        typeof w.date !== "string" ||
+        typeof w.distance !== "number" ||
+        typeof w.time !== "number"
+      ) {
+        issues.push(`workouts.jsonl: line ${lineNo} malformed workout record`);
+      }
+    }
+  }
+
+  for (const f of await listDir(paths.strokesDir, "strokes/", issues)) {
+    if (!f.endsWith(".jsonl")) continue;
+    const text = await readOrNull(join(paths.strokesDir, f), `strokes/${f}`, issues);
+    if (text == null) continue;
+    checkedFiles++;
+    let lineNo = 0;
+    for (const line of text.split("\n")) {
+      lineNo++;
+      if (line.trim() === "") continue;
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(line);
+      } catch {
+        issues.push(`strokes/${f}: line ${lineNo} is not valid JSON`);
+        continue;
+      }
+      if (!isStrokeShaped(parsed)) {
+        issues.push(`strokes/${f}: line ${lineNo} malformed stroke record`);
+      }
+    }
+  }
+
+  const looseContent = new Map<string, { content: string; file: string }>();
+  const divergentIds = new Set<string>();
+  for (const f of await listDir(paths.notesDir, "notes/", issues)) {
+    if (!f.endsWith(".json")) continue;
+    const text = await readOrNull(join(paths.notesDir, f), `notes/${f}`, issues);
+    if (text == null) continue;
+    checkedFiles++;
+    try {
+      const parsed = JSON.parse(text) as unknown;
+      if (!isNoteShaped(parsed)) {
+        issues.push(`notes/${f}: malformed note record`);
+      } else {
+        const content = serializeNote(parsed);
+        const prior = looseContent.get(parsed.id);
+        if (prior != null && prior.content !== content && !divergentIds.has(parsed.id)) {
+          divergentIds.add(parsed.id);
+          issues.push(
+            `notes: divergent copies of note ${parsed.id} (${prior.file}, ${f}); reconcile before they compact`,
+          );
+        }
+        looseContent.set(parsed.id, { content, file: f });
+      }
+    } catch {
+      issues.push(`notes/${f}: not valid JSON`);
+    }
+  }
+
+  const archiveIds = new Set<string>();
+  for (const f of await listDir(paths.archiveDir, "notes/archive/", issues)) {
+    if (!f.endsWith(".jsonl")) continue;
+    const text = await readOrNull(join(paths.archiveDir, f), `notes/archive/${f}`, issues);
+    if (text == null) continue;
+    checkedFiles++;
+    let prevMs = Number.NEGATIVE_INFINITY;
+    let prevId = "";
+    let lineNo = 0;
+    for (const line of text.split("\n")) {
+      lineNo++;
+      if (line.trim() === "") continue;
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(line);
+      } catch {
+        issues.push(`notes/archive/${f}: line ${lineNo} is not valid JSON`);
+        continue;
+      }
+      if (!isNoteShaped(parsed)) {
+        issues.push(`notes/archive/${f}: line ${lineNo} malformed note record`);
+        continue;
+      }
+      const ms = new Date(parsed.date).getTime();
+      if (ms < prevMs || (ms === prevMs && parsed.id < prevId)) {
+        issues.push(`notes/archive/${f}: line ${lineNo} out of (date, id) order`);
+      }
+      prevMs = ms;
+      prevId = parsed.id;
+      if (archiveIds.has(parsed.id)) {
+        issues.push(`notes/archive/${f}: duplicate note id ${parsed.id}`);
+      }
+      archiveIds.add(parsed.id);
+    }
+  }
+
+  return { issues, checkedFiles };
+}

package/src/envelope.ts

@@ -0,0 +1,17 @@
+export interface Envelope<T> {
+  schema: string;
+  generated_at: string;
+  data: T;
+}
+
+export function envelope<T>(schema: string, data: T, now?: Date): Envelope<T> {
+  return {
+    schema,
+    generated_at: (now ?? new Date()).toISOString(),
+    data,
+  };
+}
+
+export function printJSON<T>(schema: string, data: T): void {
+  console.log(JSON.stringify(envelope(schema, data), null, 2));
+}