@robbeverhelst/do 1.281.0 → 1.283.0

package/dist/do.js

@@ -1038,7 +1038,7 @@ function flagBool(flags, name) {
 
 // src/commands.ts
 import { mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
-import { basename, dirname as dirname2, join as join3 } from "path";
+import { basename as basename2, dirname as dirname2, join as join4 } from "path";
 
 // ../../node_modules/drizzle-orm/entity.js
 var entityKind = Symbol.for("drizzle:entityKind");
@@ -4191,6 +4191,7 @@ var contacts = pgTable("contacts", {
   tenantId: text("tenant_id").notNull().references(() => tenants.id),
   kind: contactKind("kind").notNull().default("person"),
   email: text("email"),
+  emailInvalidAt: timestamp("email_invalid_at", { withTimezone: true }),
   phone: text("phone"),
   company: text("company"),
   website: text("website"),
@@ -22235,7 +22236,14 @@ var setHealthLabAnalyteInputSchema = object({
 
 // ../../packages/schema/src/contracts/files.ts
 var FILE_TEXT_MAX = 1e6;
-var FILE_SOURCES = ["upload", "chat", "doccle", "doccle_zip", "scan"];
+var FILE_SOURCES = [
+  "upload",
+  "chat",
+  "doccle",
+  "doccle_zip",
+  "scan",
+  "game_save"
+];
 var fileSourceSchema = union([
   _enum2(FILE_SOURCES),
   string2().regex(/^gmail:[A-Za-z0-9_-]{1,200}$/, "gmail:<message id>")
@@ -24144,7 +24152,8 @@ var contactSchema = createSelectSchema(contacts, {
   lastContactedAt: exports_coerce.date().nullable(),
   userId: string2().nullable().default(null),
   rhythmDays: number2().int().nullable().default(null),
-  rhythmSnoozedUntil: string2().nullable().default(null)
+  rhythmSnoozedUntil: string2().nullable().default(null),
+  emailInvalidAt: exports_coerce.date().nullable().default(null)
 });
 var contactImportantDateSchema = object({
   id: ulidSchema,
@@ -24188,7 +24197,7 @@ var createContactInputSchema = createInsertSchema(contacts, {
   lastContactedAt: exports_coerce.date().nullish(),
   rhythmDays: contactPeopleInputShape.rhythmDays,
   rhythmSnoozedUntil: contactPeopleInputShape.rhythmSnoozedUntil
-}).omit({ tenantId: true, keepInTouchRuleId: true, userId: true }).extend({
+}).omit({ tenantId: true, keepInTouchRuleId: true, userId: true, emailInvalidAt: true }).extend({
   title: string2().min(1),
   parentId: ulidSchema.nullish(),
   importantDates: array(contactImportantDateInputSchema).optional(),
@@ -24205,7 +24214,7 @@ var updateContactInputSchema = createUpdateSchema(contacts, {
   lastContactedAt: exports_coerce.date().nullish(),
   rhythmDays: contactPeopleInputShape.rhythmDays,
   rhythmSnoozedUntil: contactPeopleInputShape.rhythmSnoozedUntil
-}).omit({ id: true, tenantId: true, keepInTouchRuleId: true, userId: true }).extend({
+}).omit({ id: true, tenantId: true, keepInTouchRuleId: true, userId: true, emailInvalidAt: true }).extend({
   title: string2().min(1).optional(),
   parentId: ulidSchema.nullish(),
   importantDates: array(contactImportantDateInputSchema).optional(),
@@ -25394,6 +25403,35 @@ var runInstallSchema = object({
   lastBackup: isoDate.nullish(),
   notes: text5.nullish()
 }).strict();
+var SAVE_SCREENSHOT_MAX_BASE64 = 1500000;
+var runSaveFields = {
+  game: _enum2(["skyrim"]).default("skyrim"),
+  fileName: shortText.nullish(),
+  saveNumber: number2().int().min(0).max(1e9),
+  playerName: name,
+  level: number2().int().min(0).max(1e4),
+  location: shortText,
+  race: shortText.nullish(),
+  sex: _enum2(["male", "female"]).nullish(),
+  playTimeMinutes: number2().int().min(0).max(1e4 * 60).nullish(),
+  savedAt: string2().datetime({ offset: true }).nullish(),
+  gameDate: object({
+    text: shortText.pipe(string2().min(1)),
+    hour: number2().min(0).max(24).nullish(),
+    daysPassed: number2().min(0).max(1e6).nullish()
+  }).strict().nullish(),
+  plugins: array(shortText).max(600).optional(),
+  stats: record(shortText, number2().int()).refine((r) => Object.keys(r).length <= 300, "at most 300 stats").optional()
+};
+var runSaveSchema = object({
+  ...runSaveFields,
+  screenshotFileId: string2().min(1).max(64).nullish(),
+  uploadedAt: string2().datetime({ offset: true })
+}).strict();
+var uploadRunSaveHeaderInputSchema = object({
+  ...runSaveFields,
+  screenshot: string2().max(SAVE_SCREENSHOT_MAX_BASE64).regex(/^[A-Za-z0-9+/]+={0,2}$/, "must be base64").nullish()
+}).strict();
 var runFacetSchema = object({
   theme: runThemeSchema.default("generic"),
   edition: shortText.nullish(),
@@ -25414,6 +25452,7 @@ var runFacetSchema = object({
   achievements: runAchievementsSchema.nullish(),
   rareFinds: runRareFindsSchema.nullish(),
   install: runInstallSchema.nullish(),
+  save: runSaveSchema.nullish(),
   money: object({ goal: shortText.nullish(), purpose: shortText.nullish() }).strict().nullish(),
   links: array(object({ label: name, url: string2().url().max(2000) }).strict()).max(50).optional()
 }).strict();
@@ -25441,6 +25480,7 @@ var runValueSectionValues = [
   "achievements",
   "rareFinds",
   "install",
+  "save",
   "money"
 ];
 var runValueSectionSchema = _enum2(runValueSectionValues);
@@ -25544,6 +25584,12 @@ var runChangesResultSchema = object({
   sessionId: string2(),
   batch: runChangeBatchSchema
 });
+var runSaveHeaderResultSchema = object({
+  run: runDetailSchema,
+  unchanged: boolean3(),
+  sessionId: string2().nullable(),
+  batch: runChangeBatchSchema.nullable()
+});
 var createRunInputSchema = object({
   id: ulidSchema,
   gameId: ulidSchema,
@@ -28315,7 +28361,7 @@ function parseCapture2(input, now) {
 
 // src/meta.ts
 var CLI_NAME = "do";
-var VERSION = "1.281.0";
+var VERSION = "1.283.0";
 var API_PREFIX = "/api/v1";
 var DEFAULT_API_URL = "http://localhost:3001";
 
@@ -33305,6 +33351,34 @@ var COMMAND_SPECS = [
     returns: "RunChangesResult",
     notes: "POST /api/v1/runs/{id}/changes. Ops: set|merge on a one-value section (character, arc, nextSteps, achievements, install, \u2026), upsert|remove on a list section matched by name (quests, choices, homes, people, mounts, uniques, orderOfPlay, team, checklists, links), tick on a checklist. The batch joins the last session if it was active in the last 6 hours, else opens a new one. A change that leaves the run invalid writes nothing."
   },
+  {
+    path: ["runs", "save-header"],
+    summary: "Read a Skyrim save (read-only) and send its header and screenshot to a run.",
+    args: [
+      { name: "id", required: true, description: "Run ULID." },
+      {
+        name: "save",
+        required: true,
+        description: "A .ess save, or the Saves folder (its newest save)."
+      }
+    ],
+    flags: [
+      {
+        name: "watch",
+        type: "boolean",
+        description: "Keep watching the Saves folder; send each new save once the game has written it."
+      },
+      {
+        name: "interval",
+        type: "string",
+        description: "With --watch: seconds between looks (default 10)."
+      },
+      { name: "dry-run", type: "boolean", description: "Print what the save says; send nothing." }
+    ],
+    scopes: ["collections:write"],
+    returns: "RunSaveHeaderResult",
+    notes: "POST /api/v1/runs/{id}/save-header. The save sync (run tracker phase 4): name, level, location, race, play time, the in-game date, plugins and General Stats become the run's `save` section and its character's level, as one update with a receipt and Undo; the screenshot is a file on the run (the last one is dropped). The same save twice changes nothing. Needs a member's key (the screenshot is stored as theirs). The save itself is only read. See docs/agents/skyrim-save-sync.md."
+  },
   {
     path: ["runs", "undo"],
     summary: "Undo a run's latest chat update (or the one given).",
@@ -35288,6 +35362,534 @@ function renderEvents(data, mode) {
 `);
 }
 
+// src/save-sync.ts
+import { readFile, stat as stat2 } from "fs/promises";
+import { basename } from "path";
+
+// ../../packages/skyrim-save/src/body.ts
+import { inflateSync } from "zlib";
+
+// ../../packages/skyrim-save/src/reader.ts
+class SaveFormatError extends Error {
+  name = "SaveFormatError";
+}
+
+class Reader {
+  bytes;
+  view;
+  offset;
+  constructor(bytes, offset = 0) {
+    this.bytes = bytes;
+    this.view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    this.offset = offset;
+  }
+  get remaining() {
+    return this.bytes.byteLength - this.offset;
+  }
+  need(n, what) {
+    if (n < 0 || this.offset + n > this.bytes.byteLength) {
+      throw new SaveFormatError(`the save ends before its ${what} (at byte ${this.offset})`);
+    }
+    const at = this.offset;
+    this.offset += n;
+    return at;
+  }
+  u8(what) {
+    return this.view.getUint8(this.need(1, what));
+  }
+  u16(what) {
+    return this.view.getUint16(this.need(2, what), true);
+  }
+  u32(what) {
+    return this.view.getUint32(this.need(4, what), true);
+  }
+  f32(what) {
+    return this.view.getFloat32(this.need(4, what), true);
+  }
+  u64(what) {
+    return this.view.getBigUint64(this.need(8, what), true);
+  }
+  take(n, what) {
+    const at = this.need(n, what);
+    return this.bytes.subarray(at, at + n);
+  }
+  wstring(what) {
+    const len = this.u16(what);
+    return decodeLatin1(this.take(len, what));
+  }
+}
+function decodeLatin1(bytes) {
+  let out = "";
+  for (const b of bytes)
+    out += String.fromCharCode(b);
+  return out;
+}
+
+// ../../packages/skyrim-save/src/lz4.ts
+function lz4DecompressBlock(src, size) {
+  const out = new Uint8Array(size);
+  let i = 0;
+  let o = 0;
+  while (i < src.length) {
+    const token = src[i++];
+    let literals = token >> 4;
+    if (literals === 15) {
+      let b;
+      do {
+        b = byteAt(src, i++);
+        literals += b;
+      } while (b === 255);
+    }
+    if (i + literals > src.length || o + literals > size) {
+      throw new SaveFormatError("the save's body is cut short (LZ4 literals)");
+    }
+    out.set(src.subarray(i, i + literals), o);
+    i += literals;
+    o += literals;
+    if (i >= src.length)
+      break;
+    const offset = byteAt(src, i) | byteAt(src, i + 1) << 8;
+    i += 2;
+    if (offset === 0 || offset > o)
+      throw new SaveFormatError("a bad LZ4 match in the save's body");
+    let length = (token & 15) + 4;
+    if ((token & 15) === 15) {
+      let b;
+      do {
+        b = byteAt(src, i++);
+        length += b;
+      } while (b === 255);
+    }
+    if (o + length > size)
+      throw new SaveFormatError("the save's body is longer than it says");
+    for (let k = 0;k < length; k++, o++)
+      out[o] = out[o - offset];
+  }
+  if (o !== size)
+    throw new SaveFormatError("the save's body is shorter than it says");
+  return out;
+}
+function byteAt(src, i) {
+  const b = src[i];
+  if (b === undefined)
+    throw new SaveFormatError("the save's body is cut short (LZ4)");
+  return b;
+}
+
+// ../../packages/skyrim-save/src/body.ts
+var SAVE_STAT_CATEGORIES = [
+  "general",
+  "quest",
+  "combat",
+  "magic",
+  "crafting",
+  "crime",
+  "dlc"
+];
+var TAMRIEL_MONTHS = [
+  "Morning Star",
+  "Sun's Dawn",
+  "First Seed",
+  "Rain's Hand",
+  "Second Seed",
+  "Midyear",
+  "Sun's Height",
+  "Last Seed",
+  "Hearthfire",
+  "Frostfall",
+  "Sun's Dusk",
+  "Evening Star"
+];
+var CLOCK_GLOBALS = {
+  year: 53,
+  month: 54,
+  day: 55,
+  hour: 56,
+  daysPassed: 57
+};
+var MISC_STATS = 0;
+var GLOBAL_VARIABLES = 3;
+var LIGHT_PLUGINS_FROM = 78;
+function decompressBody(bytes, header) {
+  if (header.compression === "none")
+    return bytes.subarray(header.bodyOffset);
+  const r = new Reader(bytes, header.bodyOffset);
+  const uncompressed = r.u32("uncompressed size");
+  const compressed = r.u32("compressed size");
+  if (uncompressed > 512 * 1024 * 1024)
+    throw new SaveFormatError("the save's body is too big");
+  const block = r.take(compressed, "compressed body");
+  if (header.compression === "lz4")
+    return lz4DecompressBlock(block, uncompressed);
+  const out = new Uint8Array(inflateSync(block));
+  if (out.byteLength !== uncompressed) {
+    throw new SaveFormatError("the save's body is not the size it says");
+  }
+  return out;
+}
+function parseSaveBody(bytes, header) {
+  const body = decompressBody(bytes, header);
+  const r = new Reader(body);
+  const formVersion = r.u8("form version");
+  const pluginInfoSize = r.u32("plugin info size");
+  const pluginsEnd = r.offset + pluginInfoSize;
+  const plugins = [];
+  const pluginCount = r.u8("plugin count");
+  for (let i = 0;i < pluginCount; i++)
+    plugins.push(r.wstring("plugin name"));
+  const lightPlugins = [];
+  if (header.version >= 12 && formVersion >= LIGHT_PLUGINS_FROM) {
+    const lightCount = r.u16("light plugin count");
+    for (let i = 0;i < lightCount; i++)
+      lightPlugins.push(r.wstring("light plugin name"));
+  }
+  if (r.offset !== pluginsEnd) {
+    throw new SaveFormatError("the save's plugin list is not the size it says");
+  }
+  const formIdArrayAt = r.u32("form id array offset");
+  r.u32("unknown table offset");
+  const globals1At = r.u32("global data table 1 offset");
+  r.u32("global data table 2 offset");
+  r.u32("change forms offset");
+  r.u32("global data table 3 offset");
+  const globals1Count = r.u32("global data table 1 count");
+  const base = header.bodyOffset;
+  const formIds = readFormIdArray(body, formIdArrayAt - base);
+  const { globals, stats } = readGlobalData(body, globals1At - base, globals1Count, formIds);
+  return { formVersion, plugins, lightPlugins, gameTime: clockFrom(globals), stats };
+}
+function readFormIdArray(body, at) {
+  const r = new Reader(body, at);
+  const count = r.u32("form id count");
+  if (count * 4 > r.remaining)
+    throw new SaveFormatError("the save's form id array is cut short");
+  const out = new Uint32Array(count);
+  for (let i = 0;i < count; i++)
+    out[i] = r.u32("form id");
+  return out;
+}
+function readGlobalData(body, at, count, formIds) {
+  const r = new Reader(body, at);
+  const globals = new Map;
+  const stats = [];
+  for (let i = 0;i < count; i++) {
+    const type = r.u32("global data type");
+    const length = r.u32("global data length");
+    const g = new Reader(r.take(length, "global data"));
+    if (type === MISC_STATS) {
+      const n = g.u32("stat count");
+      for (let k = 0;k < n; k++) {
+        const name = g.wstring("stat name");
+        const category = SAVE_STAT_CATEGORIES[g.u8("stat category")] ?? "general";
+        const value = g.u32("stat value") | 0;
+        if (value !== 0)
+          stats.push({ name, category, value });
+      }
+    } else if (type === GLOBAL_VARIABLES) {
+      const n = vsval(g);
+      for (let k = 0;k < n; k++) {
+        const id = refId(g, formIds);
+        globals.set(id, g.f32("global value"));
+      }
+    }
+  }
+  return { globals, stats };
+}
+function clockFrom(globals) {
+  const get = (id) => globals.get(id);
+  const year = get(CLOCK_GLOBALS.year);
+  const month = get(CLOCK_GLOBALS.month);
+  const day = get(CLOCK_GLOBALS.day);
+  const hour = get(CLOCK_GLOBALS.hour);
+  const daysPassed = get(CLOCK_GLOBALS.daysPassed);
+  if (year === undefined || month === undefined || day === undefined || hour === undefined) {
+    return null;
+  }
+  return {
+    year: Math.round(year),
+    month: Math.round(month),
+    day: Math.round(day),
+    hour,
+    daysPassed: daysPassed ?? 0
+  };
+}
+function vsval(r) {
+  const first = r.u8("vsval");
+  const size = first & 3;
+  if (size === 0)
+    return first >> 2;
+  if (size === 1)
+    return (first | r.u8("vsval") << 8) >> 2;
+  const rest = r.u16("vsval");
+  return (first | rest << 8) >>> 2;
+}
+function refId(r, formIds) {
+  const b0 = r.u8("ref id");
+  const b1 = r.u8("ref id");
+  const b2 = r.u8("ref id");
+  const value = (b0 & 63) << 16 | b1 << 8 | b2;
+  const type = b0 >> 6;
+  if (type === 1)
+    return value;
+  if (type === 2)
+    return (4278190080 | value) >>> 0;
+  if (type === 0)
+    return value === 0 ? 0 : formIds[value - 1] ?? 0;
+  return 0;
+}
+function formatGameDate(time) {
+  const month = TAMRIEL_MONTHS[time.month] ?? `month ${time.month + 1}`;
+  return `${ordinal(time.day)} of ${month}, 4E ${time.year}`;
+}
+function ordinal(n) {
+  const tens = n % 100;
+  if (tens >= 11 && tens <= 13)
+    return `${n}th`;
+  const suffix = n % 10 === 1 ? "st" : n % 10 === 2 ? "nd" : n % 10 === 3 ? "rd" : "th";
+  return `${n}${suffix}`;
+}
+// ../../packages/skyrim-save/src/header.ts
+var SAVE_MAGIC = "TESV_SAVEGAME";
+var SE_VERSION = 12;
+var FILETIME_UNIX_EPOCH = 116444736000000000n;
+function parseSaveHeader(bytes) {
+  const r = new Reader(bytes);
+  const magic = String.fromCharCode(...r.take(SAVE_MAGIC.length, "magic"));
+  if (magic !== SAVE_MAGIC)
+    throw new SaveFormatError("not a Skyrim save (no TESV_SAVEGAME magic)");
+  const headerSize = r.u32("header size");
+  const headerStart = r.offset;
+  const version = r.u32("version");
+  if (version < 7 || version > 64)
+    throw new SaveFormatError(`unknown save version ${version}`);
+  const saveNumber = r.u32("save number");
+  const playerName = r.wstring("player name");
+  const level = r.u32("level");
+  const location = r.wstring("location");
+  const gameDate = r.wstring("game date");
+  const raceEditorId = r.wstring("race");
+  const sexCode = r.u16("sex");
+  const current = r.f32("experience");
+  const toNextLevel = r.f32("experience to next level");
+  const filetime = r.u64("save time");
+  const width = r.u32("screenshot width");
+  const height = r.u32("screenshot height");
+  let compression = "none";
+  if (version >= SE_VERSION) {
+    const code = r.u16("compression");
+    compression = code === 1 ? "zlib" : code === 2 ? "lz4" : "none";
+  }
+  if (r.offset - headerStart !== headerSize) {
+    throw new SaveFormatError(`the header says ${headerSize} bytes but its fields take ${r.offset - headerStart}`);
+  }
+  if (width > 4096 || height > 4096) {
+    throw new SaveFormatError(`a ${width}\xD7${height} screenshot is not a save's`);
+  }
+  const bytesPerPixel = version >= SE_VERSION ? 4 : 3;
+  const pixels = r.take(width * height * bytesPerPixel, "screenshot");
+  return {
+    version,
+    saveNumber,
+    playerName,
+    level,
+    location,
+    gameDate,
+    playTimeMinutes: playTimeMinutes(gameDate),
+    raceEditorId,
+    race: raceName(raceEditorId),
+    sex: sexCode === 1 ? "female" : "male",
+    experience: { current, toNextLevel },
+    savedAt: filetimeToIso(filetime),
+    screenshot: { width, height, bytesPerPixel, pixels },
+    compression,
+    bodyOffset: r.offset
+  };
+}
+function playTimeMinutes(gameDate) {
+  const m = /^(\d+)\.(\d{1,2})\.(\d{1,2})$/.exec(gameDate.trim());
+  if (!m)
+    return null;
+  return Number(m[1]) * 60 + Number(m[2]);
+}
+function raceName(editorId) {
+  const base = editorId.replace(/Vampire$/, "").replace(/Race$/, "");
+  return base.replace(/([a-z])([A-Z])/g, "$1 $2") || editorId;
+}
+function filetimeToIso(filetime) {
+  if (filetime <= FILETIME_UNIX_EPOCH)
+    return null;
+  const ms = Number((filetime - FILETIME_UNIX_EPOCH) / 10000n);
+  const date = new Date(ms);
+  return Number.isNaN(date.getTime()) ? null : date.toISOString();
+}
+// ../../packages/skyrim-save/src/png.ts
+import { deflateSync } from "zlib";
+var SIGNATURE = Uint8Array.of(137, 80, 78, 71, 13, 10, 26, 10);
+function screenshotToPng(shot) {
+  const { width, height, bytesPerPixel, pixels } = shot;
+  if (width === 0 || height === 0)
+    throw new RangeError("the save has no screenshot");
+  const stride = width * bytesPerPixel;
+  const raw = new Uint8Array((stride + 1) * height);
+  for (let y = 0;y < height; y++) {
+    raw.set(pixels.subarray(y * stride, (y + 1) * stride), y * (stride + 1) + 1);
+  }
+  const ihdr = new Uint8Array(13);
+  const v = new DataView(ihdr.buffer);
+  v.setUint32(0, width);
+  v.setUint32(4, height);
+  ihdr[8] = 8;
+  ihdr[9] = bytesPerPixel === 4 ? 6 : 2;
+  return concat([
+    SIGNATURE,
+    chunk("IHDR", ihdr),
+    chunk("IDAT", new Uint8Array(deflateSync(raw))),
+    chunk("IEND", new Uint8Array(0))
+  ]);
+}
+function chunk(type, data) {
+  const out = new Uint8Array(12 + data.byteLength);
+  const v = new DataView(out.buffer);
+  v.setUint32(0, data.byteLength);
+  for (let i = 0;i < 4; i++)
+    out[4 + i] = type.charCodeAt(i);
+  out.set(data, 8);
+  v.setUint32(8 + data.byteLength, crc32(out.subarray(4, 8 + data.byteLength)));
+  return out;
+}
+var table = null;
+function crc32(bytes) {
+  if (!table) {
+    table = new Uint32Array(256);
+    for (let n = 0;n < 256; n++) {
+      let c = n;
+      for (let k = 0;k < 8; k++)
+        c = c & 1 ? 3988292384 ^ c >>> 1 : c >>> 1;
+      table[n] = c >>> 0;
+    }
+  }
+  let crc = 4294967295;
+  for (const b of bytes)
+    crc = table[(crc ^ b) & 255] ^ crc >>> 8;
+  return (crc ^ 4294967295) >>> 0;
+}
+function concat(parts) {
+  const out = new Uint8Array(parts.reduce((n, p) => n + p.byteLength, 0));
+  let at = 0;
+  for (const p of parts) {
+    out.set(p, at);
+    at += p.byteLength;
+  }
+  return out;
+}
+// ../../packages/skyrim-save/src/save.ts
+function readSave(bytes) {
+  const header = parseSaveHeader(bytes);
+  let body = null;
+  let bodyError = null;
+  try {
+    body = parseSaveBody(bytes, header);
+  } catch (err) {
+    if (!(err instanceof SaveFormatError))
+      throw err;
+    bodyError = err.message;
+  }
+  const shot = header.screenshot;
+  return {
+    header,
+    body,
+    bodyError,
+    summary: summarize(header, body),
+    screenshotPng: shot.width > 0 && shot.height > 0 ? screenshotToPng(shot) : null
+  };
+}
+function summarize(header, body) {
+  const time = body?.gameTime ?? null;
+  return {
+    version: header.version,
+    saveNumber: header.saveNumber,
+    playerName: header.playerName,
+    level: header.level,
+    location: header.location,
+    race: header.race,
+    sex: header.sex,
+    playTimeMinutes: header.playTimeMinutes,
+    savedAt: header.savedAt,
+    gameDate: time ? {
+      text: formatGameDate(time),
+      hour: Math.round(time.hour * 100) / 100,
+      daysPassed: Math.round(time.daysPassed * 100) / 100
+    } : null,
+    plugins: body?.plugins ?? [],
+    lightPlugins: body?.lightPlugins ?? [],
+    stats: Object.fromEntries((body?.stats ?? []).map((s) => [s.name, s.value]))
+  };
+}
+// ../../packages/skyrim-save/src/newest.ts
+import { readdir, stat } from "fs/promises";
+import { join as join3 } from "path";
+async function newestSave(dir) {
+  let best = null;
+  for (const name of await readdir(dir)) {
+    if (!name.toLowerCase().endsWith(".ess"))
+      continue;
+    const path = join3(dir, name);
+    const info = await stat(path);
+    if (!info.isFile())
+      continue;
+    if (!best || info.mtimeMs > best.at)
+      best = { path, at: info.mtimeMs };
+  }
+  return best?.path ?? null;
+}
+// src/save-sync.ts
+async function resolveSave(path) {
+  const info = await stat2(path).catch(() => null);
+  if (!info)
+    throw usageError(`no such file or folder: ${path}`);
+  if (!info.isDirectory())
+    return path;
+  const newest = await newestSave(path);
+  if (!newest)
+    throw usageError(`no .ess save in ${path}`);
+  return newest;
+}
+async function saveUpload(path) {
+  const save = readSave(new Uint8Array(await readFile(path)));
+  const { version: _version, lightPlugins, plugins, ...summary } = save.summary;
+  return uploadRunSaveHeaderInputSchema.parse({
+    ...summary,
+    fileName: basename(path),
+    plugins: [...plugins, ...lightPlugins].slice(0, 600),
+    screenshot: save.screenshotPng ? Buffer.from(save.screenshotPng).toString("base64") : null
+  });
+}
+async function watchSaves(opts) {
+  const interval = opts.intervalMs ?? 1e4;
+  const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  let seen = null;
+  let sent = null;
+  while (!opts.signal?.aborted) {
+    try {
+      const path = await newestSave(opts.dir);
+      if (path) {
+        const info = await stat2(path);
+        const mark = `${path}|${info.mtimeMs}|${info.size}`;
+        if (mark === seen && mark !== sent) {
+          await opts.onSave(path);
+          sent = mark;
+        }
+        seen = mark;
+      }
+    } catch (err) {
+      opts.onError?.(err);
+    }
+    if (opts.signal?.aborted)
+      break;
+    await sleep(interval);
+  }
+}
+
 // src/today.ts
 var OPEN_STATUSES = new Set(["todo", "in_progress"]);
 function isTaskLike(value) {
@@ -35864,7 +36466,7 @@ var HANDLERS = {
     });
     if (out !== undefined) {
       for (const file of data.files) {
-        const target = join3(out, file.path);
+        const target = join4(out, file.path);
         mkdirSync2(dirname2(target), { recursive: true });
         writeFileSync2(target, file.markdown);
       }
@@ -36050,7 +36652,7 @@ var HANDLERS = {
     } catch (cause) {
       throw usageError(`can't read ${path}: ${cause instanceof Error ? cause.message : cause}`);
     }
-    const name = flagString(flags, "title") ?? flagString(flags, "name") ?? basename(path);
+    const name = flagString(flags, "title") ?? flagString(flags, "name") ?? basename2(path);
     const form = new FormData;
     form.append("nodeId", node);
     const fields = {
@@ -36077,7 +36679,7 @@ var HANDLERS = {
   "files download": async ({ args, flags, requireClient }) => {
     const id = requireArg(args, 0, "file id");
     const file = await requireClient().getBytes(`/files/${id}/download`);
-    const out = flagString(flags, "out") ?? basename(file.name ?? id);
+    const out = flagString(flags, "out") ?? basename2(file.name ?? id);
     writeFileSync2(out, file.bytes);
     return {
       data: { id, saved: out, size: file.bytes.byteLength, type: file.contentType },
@@ -36144,7 +36746,7 @@ var HANDLERS = {
         if (value !== undefined)
           form.append(key, value);
       }
-      const name = basename(path);
+      const name = basename2(path);
       const type = flagString(flags, "type") ?? Bun.file(name).type;
       form.append("file", new File([Uint8Array.from(bytes)], name, { type }), name);
     }
@@ -37501,7 +38103,7 @@ var HANDLERS = {
     const since = flagString(flags, "since");
     if (since !== undefined)
       form.append("since", since);
-    const name = basename(path);
+    const name = basename2(path);
     form.append("file", new File([Uint8Array.from(bytes)], name, { type: "text/csv" }), name);
     const route = flagBool(flags, "commit") ? "/money/imports" : "/money/imports/preview";
     return { data: await requireClient().upload(route, form), render: renderRecord };
@@ -37705,6 +38307,37 @@ var HANDLERS = {
     const input = parseInput(applyRunChangesInputSchema, body);
     return { data: await requireClient().post(`/runs/${id}/changes`, input), render: renderRecord };
   },
+  "runs save-header": async ({ args, flags, io, requireClient }) => {
+    const id = requireArg(args, 0, "run id");
+    const target = requireArg(args, 1, "save file or Saves folder");
+    const dryRun = flagBool(flags, "dry-run");
+    const send = async (path) => {
+      const input = await saveUpload(path);
+      if (dryRun)
+        return { ...input, screenshot: input.screenshot ? "(png)" : null };
+      return requireClient().post(`/runs/${id}/save-header`, input);
+    };
+    if (!flagBool(flags, "watch")) {
+      return { data: await send(await resolveSave(target)), render: renderRecord };
+    }
+    const seconds = Number(flagString(flags, "interval") ?? "10");
+    if (!Number.isFinite(seconds) || seconds < 1)
+      throw usageError("--interval is seconds, 1 or more");
+    io.stderr(`watching ${target} for new saves (every ${seconds}s); Ctrl-C stops
+`);
+    await watchSaves({
+      dir: target,
+      intervalMs: seconds * 1000,
+      onSave: async (path) => {
+        const result = await send(path);
+        io.stderr(`${result.unchanged ? "already had" : dryRun ? "read" : "sent"} ${basename2(path)}
+`);
+      },
+      onError: (err) => io.stderr(`save sync: ${err.message}
+`)
+    });
+    return { data: null, render: () => "" };
+  },
   "runs undo": async ({ args, flags, requireClient }) => {
     const id = requireArg(args, 0, "run id");
     const batch = flagString(flags, "batch");
@@ -37894,7 +38527,7 @@ var HANDLERS = {
     } catch (cause) {
       throw usageError(`can't read ${path}: ${cause instanceof Error ? cause.message : cause}`);
     }
-    const name = basename(path);
+    const name = basename2(path);
     const form = new FormData;
     const textFile = flagString(flags, "text-file");
     if (textFile)
@@ -38101,7 +38734,7 @@ var HANDLERS = {
       form.append("sourceName", fields.sourceName);
     if (fields.sourceEmail)
       form.append("sourceEmail", fields.sourceEmail);
-    const name = basename(path);
+    const name = basename2(path);
     form.append("file", new File([Uint8Array.from(bytes)], name, { type: "text/plain" }), name);
     return { data: await requireClient().upload("/family-tree", form), render: renderRecord };
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robbeverhelst/do",
-  "version": "1.281.0",
+  "version": "1.283.0",
   "private": false,
   "description": "do — the agent-drivable CLI over the public /api/v1 surface",
   "homepage": "https://github.com/robbeverhelst/do/tree/main/apps/cli",
@@ -33,6 +33,7 @@
   },
   "devDependencies": {
     "@do/schema": "workspace:*",
+    "@do/skyrim-save": "workspace:*",
     "@types/bun": "^1.4.3",
     "@types/node": "^25.9.3",
     "ulidx": "^2.4.1",