@remnic/core 9.66.1 → 9.66.3

package/src/activity/timeline/week-snapshot.test.ts

@@ -0,0 +1,66 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { renderWeekSnapshot } from "./week-snapshot.js";
+
+const WEEK_START = "2026-07-13";
+
+test("empty days print heading + (empty)", () => {
+  assert.equal(
+    renderWeekSnapshot({
+      weekStart: WEEK_START,
+      timezone: "UTC",
+      days: [],
+    }),
+    [
+      "# Week snapshot",
+      "",
+      `- weekStart: ${WEEK_START}`,
+      "- timezone: UTC",
+      "",
+      "## Days",
+      "(empty)",
+      "",
+    ].join("\n"),
+  );
+});
+
+test("days are sorted by date regardless of input order", () => {
+  const markdown = renderWeekSnapshot({
+    weekStart: WEEK_START,
+    timezone: "UTC",
+    days: [{ date: "2026-07-15" }, { date: "2026-07-13" }, { date: "2026-07-14" }],
+  });
+  const headings = [...markdown.matchAll(/^## (.+)$/gm)].map((match) => match[1]);
+  assert.deepEqual(headings, ["2026-07-13", "2026-07-14", "2026-07-15"]);
+  assert.match(markdown, /## 2026-07-13\n\(empty\)/);
+});
+
+test("timezone is echoed verbatim, not normalized", () => {
+  const markdown = renderWeekSnapshot({
+    weekStart: WEEK_START,
+    timezone: "America/Chicago",
+    days: [],
+  });
+  assert.match(markdown, /^- timezone: America\/Chicago$/m);
+  assert.doesNotMatch(markdown, /America\/Chicago\/|UTC/);
+});
+
+test("input days are not mutated and reruns are stable", () => {
+  const input = [{ date: "2026-07-15" }, { date: "2026-07-13" }];
+  const first = renderWeekSnapshot({
+    weekStart: WEEK_START,
+    timezone: "UTC",
+    days: input,
+  });
+  const second = renderWeekSnapshot({
+    weekStart: WEEK_START,
+    timezone: "UTC",
+    days: input,
+  });
+  assert.deepEqual(
+    input.map((day) => day.date),
+    ["2026-07-15", "2026-07-13"],
+  );
+  assert.equal(first, second);
+});

package/src/activity/timeline/week-snapshot.ts

@@ -0,0 +1,40 @@
+/**
+ * Deterministic markdown week snapshot from daily totals (issue #2052 leftover).
+ *
+ * Pure: weekStart + timezone + days in, stable markdown out. No LLM, no I/O, no
+ * persistence. Days are sorted by date. Empty days print heading + (empty).
+ */
+
+export interface WeekSnapshotDay {
+  date: string;
+}
+
+export interface WeekSnapshotOptions {
+  weekStart: string;
+  timezone: string;
+  days: readonly WeekSnapshotDay[];
+}
+
+function compareDates(a: WeekSnapshotDay, b: WeekSnapshotDay): number {
+  if (a.date < b.date) return -1;
+  if (a.date > b.date) return 1;
+  return 0;
+}
+
+/** Render a byte-stable Markdown week snapshot. */
+export function renderWeekSnapshot(options: WeekSnapshotOptions): string {
+  const days = [...options.days].sort(compareDates);
+  const body =
+    days.length === 0
+      ? ["## Days", "(empty)"]
+      : days.flatMap((day) => [`## ${day.date}`, "(empty)", ""]);
+  return [
+    "# Week snapshot",
+    "",
+    `- weekStart: ${options.weekStart}`,
+    `- timezone: ${options.timezone}`,
+    "",
+    ...body,
+    "",
+  ].join("\n");
+}

package/src/activity/timeline/week-sunday.test.ts

@@ -0,0 +1,17 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { isSundayIso } from "./week-sunday.js";
+
+test("sunday UTC is true", () => {
+  assert.equal(isSundayIso("2026-07-12"), true);
+});
+
+test("monday UTC is false", () => {
+  assert.equal(isSundayIso("2026-07-13"), false);
+});
+
+test("invalid date throws", () => {
+  assert.throws(() => isSundayIso("2026-02-30"), /YYYY-MM-DD/);
+  assert.throws(() => isSundayIso("not-a-date"), /YYYY-MM-DD/);
+});

package/src/activity/timeline/week-sunday.ts

@@ -0,0 +1,12 @@
+/**
+ * UTC Sunday predicate for a YYYY-MM-DD date (issue #2052).
+ */
+import { isValidActivityDate } from "../digest.js";
+
+/** Parse `dateIso` as YYYY-MM-DD. Sunday UTC → true. */
+export function isSundayIso(dateIso: string): boolean {
+  if (!isValidActivityDate(dateIso)) {
+    throw new RangeError(`Invalid date "${dateIso}"; expected YYYY-MM-DD.`);
+  }
+  return new Date(`${dateIso}T00:00:00Z`).getUTCDay() === 0;
+}

package/src/activity/timeline/weekly-persist.test.ts

@@ -0,0 +1,121 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, readdirSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { RECALL_FALLBACK_DIRS } from "../../utils/category-dir.js";
+import type { TimelineCategory } from "./types.js";
+import { persistWeeklySnapshot } from "./weekly-persist.js";
+import { buildWeeklyActivitySummary } from "./weekly.js";
+
+const WEEK_START = "2026-07-13T00:00:00.000Z";
+const WEEK_END = "2026-07-20T00:00:00.000Z";
+const OTHER_WEEK_START = "2026-07-20T00:00:00.000Z";
+const OTHER_WEEK_END = "2026-07-27T00:00:00.000Z";
+
+const CATEGORIES: TimelineCategory[] = [
+  { id: "development", name: "Development", color: "#333333", description: "d", order: 1 },
+];
+
+function summary(weekStartUtc = WEEK_START, weekEndUtc = WEEK_END) {
+  return buildWeeklyActivitySummary([], {
+    timezone: "UTC",
+    weekStartUtc,
+    weekEndUtc,
+    categories: CATEGORIES,
+  });
+}
+
+function withMemoryDir(fn: (memoryDir: string) => void): void {
+  const memoryDir = mkdtempSync(path.join(tmpdir(), "remnic-weekly-persist-"));
+  try {
+    fn(memoryDir);
+  } finally {
+    rmSync(memoryDir, { recursive: true, force: true });
+  }
+}
+
+function assertOutsideRecallRoots(filePath: string, memoryDir: string): void {
+  const relative = path.relative(memoryDir, filePath);
+  assert.ok(relative.startsWith(`activity${path.sep}weekly${path.sep}`));
+  assert.ok(
+    !RECALL_FALLBACK_DIRS.some((dir) => relative === dir || relative.startsWith(`${dir}${path.sep}`)),
+  );
+}
+
+test("same inputs skip rewrite by content hash", () => {
+  withMemoryDir((memoryDir) => {
+    const input = {
+      memoryDir,
+      namespace: "team",
+      summary: summary(),
+      sourceRevision: "rev-1",
+      configHash: "cfg-1",
+    };
+    const first = persistWeeklySnapshot(input);
+    assert.equal(first.written, true);
+    assertOutsideRecallRoots(first.path, memoryDir);
+    const firstBytes = readFileSync(first.path, "utf8");
+    const firstStat = statSync(first.path);
+    const snapshot = JSON.parse(firstBytes) as { contentHash: string };
+    assert.equal(typeof snapshot.contentHash, "string");
+    assert.equal(snapshot.contentHash.length, 64);
+
+    const second = persistWeeklySnapshot(input);
+    assert.equal(second.written, false);
+    assert.equal(second.path, first.path);
+    assert.equal(readFileSync(first.path, "utf8"), firstBytes);
+    assert.equal(statSync(first.path).mtimeMs, firstStat.mtimeMs);
+  });
+});
+
+test("changed sourceRevision or configHash writes a new file and leaves other weeks", () => {
+  withMemoryDir((memoryDir) => {
+    const base = {
+      memoryDir,
+      namespace: "team",
+      summary: summary(),
+      sourceRevision: "rev-1",
+      configHash: "cfg-1",
+    };
+    const original = persistWeeklySnapshot(base);
+    const originalBytes = readFileSync(original.path, "utf8");
+
+    const revised = persistWeeklySnapshot({ ...base, sourceRevision: "rev-2" });
+    assert.notEqual(revised.path, original.path);
+    assert.equal(revised.written, true);
+    assert.equal(readFileSync(original.path, "utf8"), originalBytes);
+
+    const reconfigured = persistWeeklySnapshot({ ...base, configHash: "cfg-2" });
+    assert.notEqual(reconfigured.path, original.path);
+    assert.notEqual(reconfigured.path, revised.path);
+    assert.equal(readFileSync(original.path, "utf8"), originalBytes);
+
+    const otherWeek = persistWeeklySnapshot({
+      ...base,
+      summary: summary(OTHER_WEEK_START, OTHER_WEEK_END),
+    });
+    assert.notEqual(otherWeek.path, original.path);
+    assert.equal(readFileSync(original.path, "utf8"), originalBytes);
+    assert.equal(JSON.parse(readFileSync(otherWeek.path, "utf8")).summary.weekStartUtc, OTHER_WEEK_START);
+  });
+});
+
+test("snapshots are namespace scoped", () => {
+  withMemoryDir((memoryDir) => {
+    const shared = {
+      memoryDir,
+      summary: summary(),
+      sourceRevision: "rev-1",
+      configHash: "cfg-1",
+    };
+    const alpha = persistWeeklySnapshot({ ...shared, namespace: "alpha" });
+    const beta = persistWeeklySnapshot({ ...shared, namespace: "beta" });
+    assert.notEqual(alpha.path, beta.path);
+    assert.equal(JSON.parse(readFileSync(alpha.path, "utf8")).namespace, "alpha");
+    assert.equal(JSON.parse(readFileSync(beta.path, "utf8")).namespace, "beta");
+    assert.equal(readdirSync(path.dirname(alpha.path)).length, 1);
+    assert.equal(readdirSync(path.dirname(beta.path)).length, 1);
+  });
+});

package/src/activity/timeline/weekly-persist.ts

@@ -0,0 +1,103 @@
+/**
+ * Versioned weekly time/activity snapshot store (issue #2052).
+ *
+ * Files live at `<memoryDir>/activity/weekly/<ns>/<week>--<identity>.json`,
+ * outside recall fallback dirs. Same inputs skip rewrite by content hash.
+ * A new sourceRevision or configHash is a new file.
+ */
+import { randomBytes } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+import { namespaceIdentityToken } from "../../namespaces/identity.js";
+import { hashActivityBody, isValidActivityDate } from "../digest.js";
+import type { WeeklyActivitySummary } from "./weekly.js";
+
+export const WEEKLY_SNAPSHOT_FORMAT_VERSION = 1;
+export const WEEKLY_SNAPSHOT_DIR = path.join("activity", "weekly");
+
+export interface PersistWeeklySnapshotInput {
+  memoryDir: string;
+  namespace: string;
+  summary: WeeklyActivitySummary;
+  sourceRevision: string;
+  configHash: string;
+}
+
+export interface PersistWeeklySnapshotResult {
+  path: string;
+  written: boolean;
+}
+
+function requireToken(value: string, name: string): string {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new TypeError(`${name} must be a non-empty string`);
+  }
+  return value.trim();
+}
+
+export function weeklySnapshotPath(input: PersistWeeklySnapshotInput): string {
+  const memoryDir = requireToken(input.memoryDir, "memoryDir");
+  const namespace = requireToken(input.namespace, "namespace");
+  const sourceRevision = requireToken(input.sourceRevision, "sourceRevision");
+  const configHash = requireToken(input.configHash, "configHash");
+  const weekStartUtc = input.summary?.weekStartUtc;
+  if (typeof weekStartUtc !== "string") {
+    throw new TypeError("summary.weekStartUtc must be an ISO timestamp");
+  }
+  const weekDate = weekStartUtc.slice(0, 10);
+  if (!isValidActivityDate(weekDate)) {
+    throw new RangeError("summary.weekStartUtc must be an ISO timestamp");
+  }
+  const identity = hashActivityBody(
+    `${input.summary.weekStartUtc}\0${input.summary.weekEndUtc}\0${sourceRevision}\0${configHash}`,
+  );
+  return path.join(
+    path.resolve(memoryDir),
+    WEEKLY_SNAPSHOT_DIR,
+    namespaceIdentityToken(namespace),
+    `${weekDate}--${identity}.json`,
+  );
+}
+
+/** Persist one weekly snapshot. Same bytes are a no-op. */
+export function persistWeeklySnapshot(input: PersistWeeklySnapshotInput): PersistWeeklySnapshotResult {
+  const namespace = requireToken(input.namespace, "namespace");
+  const sourceRevision = requireToken(input.sourceRevision, "sourceRevision");
+  const configHash = requireToken(input.configHash, "configHash");
+  const filePath = weeklySnapshotPath(input);
+  const payload = {
+    formatVersion: WEEKLY_SNAPSHOT_FORMAT_VERSION,
+    namespace,
+    sourceRevision,
+    configHash,
+    summary: input.summary,
+  };
+  const contentHash = hashActivityBody(JSON.stringify(payload));
+  const text = `${JSON.stringify({ ...payload, contentHash })}\n`;
+
+  try {
+    if (readFileSync(filePath, "utf8") === text) {
+      return { path: filePath, written: false };
+    }
+  } catch (error) {
+    if (!(typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT")) {
+      throw error;
+    }
+  }
+
+  mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+  const tmpPath = `${filePath}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`;
+  writeFileSync(tmpPath, text, { encoding: "utf8", mode: 0o600 });
+  try {
+    renameSync(tmpPath, filePath);
+  } catch (error) {
+    try {
+      unlinkSync(tmpPath);
+    } catch {
+      // Best-effort cleanup of the temp file.
+    }
+    throw error;
+  }
+  return { path: filePath, written: true };
+}

package/src/activity/to-ms.test.ts

@@ -0,0 +1,25 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parseToMs } from "./to-ms.js";
+
+test("toMs 0 is accepted", () => {
+  assert.equal(parseToMs(0), 0);
+});
+
+test("epoch toMs is accepted", () => {
+  const epoch = 1_700_000_000_000;
+  assert.equal(parseToMs(epoch), epoch);
+});
+
+test("negative toMs throws", () => {
+  assert.throws(() => parseToMs(-1), /non-negative/);
+});
+
+test("NaN toMs throws", () => {
+  assert.throws(() => parseToMs(Number.NaN), /finite/);
+});
+
+test("non-number toMs throws", () => {
+  assert.throws(() => parseToMs("0"), /finite/);
+});

package/src/activity/to-ms.ts

@@ -0,0 +1,13 @@
+/**
+ * Parse activity window toMs (issue #2053 leftover).
+ *
+ * Finite number ≥ 0 is returned. Negative, NaN, and non-number values throw.
+ */
+export function parseToMs(value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    throw new RangeError(
+      `activity.toMs must be a finite non-negative number; got ${JSON.stringify(value)}`,
+    );
+  }
+  return value;
+}

package/src/activity/vault-begin.test.ts

@@ -0,0 +1,20 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { isRegionBeginLine } from "./vault-begin.js";
+
+test("isRegionBeginLine matches a trimmed begin comment", () => {
+  assert.equal(isRegionBeginLine("<!-- remnic:begin timeline -->", "timeline"), true);
+  assert.equal(isRegionBeginLine("  <!-- remnic:begin timeline -->\t", "timeline"), true);
+});
+
+test("isRegionBeginLine rejects a mismatch", () => {
+  assert.equal(isRegionBeginLine("<!-- remnic:end timeline -->", "timeline"), false);
+  assert.equal(isRegionBeginLine("<!-- remnic:begin weekly -->", "timeline"), false);
+  assert.equal(isRegionBeginLine("<!-- remnic:timeline:start -->", "timeline"), false);
+  assert.equal(isRegionBeginLine("<!-- remnic:begin timeline --> extra", "timeline"), false);
+});
+
+test("isRegionBeginLine throws on an empty name", () => {
+  assert.throws(() => isRegionBeginLine("<!-- remnic:begin  -->", ""), /empty/i);
+});

package/src/activity/vault-begin.ts

@@ -0,0 +1,13 @@
+/**
+ * Match a managed-region begin marker line (issue #1985).
+ *
+ * True iff the trimmed line equals `<!-- remnic:begin NAME -->`.
+ * Empty name throws.
+ */
+
+export function isRegionBeginLine(line: string, name: string): boolean {
+  if (typeof name !== "string" || name.length === 0) {
+    throw new RangeError("Region name must be non-empty.");
+  }
+  return line.trim() === `<!-- remnic:begin ${name} -->`;
+}

package/src/activity/vault-end.test.ts

@@ -0,0 +1,20 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { isRegionEndLine } from "./vault-end.js";
+
+test("isRegionEndLine matches a trimmed end comment", () => {
+  assert.equal(isRegionEndLine("<!-- remnic:end timeline -->", "timeline"), true);
+  assert.equal(isRegionEndLine("  <!-- remnic:end timeline -->\t", "timeline"), true);
+});
+
+test("isRegionEndLine rejects a mismatch", () => {
+  assert.equal(isRegionEndLine("<!-- remnic:begin timeline -->", "timeline"), false);
+  assert.equal(isRegionEndLine("<!-- remnic:end weekly -->", "timeline"), false);
+  assert.equal(isRegionEndLine("<!-- remnic:timeline:end -->", "timeline"), false);
+  assert.equal(isRegionEndLine("<!-- remnic:end timeline --> extra", "timeline"), false);
+});
+
+test("isRegionEndLine throws on an empty name", () => {
+  assert.throws(() => isRegionEndLine("<!-- remnic:end  -->", ""), /empty/i);
+});

package/src/activity/vault-end.ts

@@ -0,0 +1,13 @@
+/**
+ * Match a managed-region end marker line (issue #1985).
+ *
+ * True iff the trimmed line equals `<!-- remnic:end NAME -->`.
+ * Empty name throws.
+ */
+
+export function isRegionEndLine(line: string, name: string): boolean {
+  if (typeof name !== "string" || name.length === 0) {
+    throw new RangeError("Region name must be non-empty.");
+  }
+  return line.trim() === `<!-- remnic:end ${name} -->`;
+}

package/src/activity/vault-frontmatter.test.ts

@@ -0,0 +1,28 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { applyVaultFrontmatter } from "./vault-frontmatter.js";
+
+test("applyVaultFrontmatter merges listed keys and sorts", () => {
+  const merged = applyVaultFrontmatter("zeta: old\nalpha: keep\n", {
+    zeta: "new",
+    remnic_cards: "3",
+  });
+  assert.equal(merged, "alpha: keep\nremnic_cards: 3\nzeta: new");
+});
+
+test("applyVaultFrontmatter rejects keys with newlines", () => {
+  assert.throws(
+    () => applyVaultFrontmatter("alpha: keep", { "bad\nkey": "1" }),
+    /newline/i,
+  );
+  assert.throws(
+    () => applyVaultFrontmatter("alpha: keep", { "bad\rkey": "1" }),
+    /newline/i,
+  );
+});
+
+test("applyVaultFrontmatter leaves the original body unchanged when updates are empty", () => {
+  const existing = "zeta: 1\n# comment stays\nalpha: 2\n";
+  assert.equal(applyVaultFrontmatter(existing, {}), existing);
+});

package/src/activity/vault-frontmatter.ts

@@ -0,0 +1,39 @@
+/**
+ * Merge vault note frontmatter keys (issue #1985).
+ *
+ * Pure string helper. Empty updates leave the original YAML unchanged.
+ * Listed keys stay. Output keys are sorted. Keys with newlines are rejected.
+ */
+
+function assertNoNewlineKey(key: string): void {
+  if (key.includes("\n") || key.includes("\r")) {
+    throw new RangeError("Vault frontmatter keys must not contain newlines.");
+  }
+}
+
+export function applyVaultFrontmatter(
+  existingYaml: string,
+  updates: Readonly<Record<string, string>>,
+): string {
+  const entries = Object.entries(updates);
+  if (entries.length === 0) return existingYaml;
+
+  const merged = new Map<string, string>();
+  for (const line of existingYaml.split("\n")) {
+    const idx = line.indexOf(":");
+    if (idx === -1) continue;
+    const key = line.slice(0, idx).trim();
+    if (key.length === 0) continue;
+    assertNoNewlineKey(key);
+    merged.set(key, line.slice(idx + 1).trim());
+  }
+  for (const [key, value] of entries) {
+    assertNoNewlineKey(key);
+    merged.set(key, value);
+  }
+
+  return [...merged.keys()]
+    .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))
+    .map((key) => `${key}: ${merged.get(key)}`)
+    .join("\n");
+}

package/src/activity/vault-join.test.ts

@@ -0,0 +1,21 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { joinVaultSegments } from "./vault-join.js";
+
+test("joinVaultSegments joins relative parts with /", () => {
+  assert.equal(
+    joinVaultSegments(["Daily Notes", "2026", "08", "2026-08-18.md"]),
+    "Daily Notes/2026/08/2026-08-18.md",
+  );
+});
+
+test("joinVaultSegments rejects ..", () => {
+  assert.throws(() => joinVaultSegments(["Daily Notes", "..", "secret"]), /\.\./);
+  assert.throws(() => joinVaultSegments(["foo/../bar"]), /\.\./);
+});
+
+test("joinVaultSegments rejects empty", () => {
+  assert.throws(() => joinVaultSegments([]), /empty/i);
+  assert.throws(() => joinVaultSegments(["Daily Notes", ""]), /empty/i);
+});

package/src/activity/vault-join.ts

@@ -0,0 +1,31 @@
+/**
+ * Join vault-relative path segments (issue #1985).
+ *
+ * Joins with `/`. Rejects an empty list, empty parts, `..`, absolute
+ * parts, backslash, and newline.
+ */
+import path from "node:path";
+
+export function joinVaultSegments(parts: readonly string[]): string {
+  if (parts.length === 0) {
+    throw new RangeError("Vault path parts must be a non-empty list.");
+  }
+  for (const part of parts) {
+    if (typeof part !== "string" || part.length === 0) {
+      throw new RangeError("Vault path part must be non-empty.");
+    }
+    if (part.includes("\\")) {
+      throw new RangeError("Vault path part must not contain a backslash.");
+    }
+    if (part.includes("\n") || part.includes("\r")) {
+      throw new RangeError("Vault path part must not contain a newline.");
+    }
+    if (path.posix.isAbsolute(part) || path.win32.isAbsolute(part)) {
+      throw new RangeError("Vault path part must be relative.");
+    }
+    if (part.split("/").includes("..")) {
+      throw new RangeError("Vault path part must not contain `..`.");
+    }
+  }
+  return parts.join("/");
+}

package/src/activity/vault-marker.test.ts

@@ -0,0 +1,23 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { formatRegionMarkers } from "./vault-marker.js";
+
+test("formatRegionMarkers returns begin and end HTML comments", () => {
+  assert.deepEqual(formatRegionMarkers("timeline"), {
+    begin: "<!-- remnic:begin timeline -->",
+    end: "<!-- remnic:end timeline -->",
+  });
+});
+
+test("formatRegionMarkers rejects an empty name", () => {
+  assert.throws(() => formatRegionMarkers(""), /empty/i);
+});
+
+test("formatRegionMarkers rejects a newline in the name", () => {
+  assert.throws(() => formatRegionMarkers("time\nline"), /newline/i);
+});
+
+test("formatRegionMarkers rejects marker text in the name", () => {
+  assert.throws(() => formatRegionMarkers("foo-->bar"), /-->/);
+});

package/src/activity/vault-marker.ts

@@ -0,0 +1,27 @@
+/**
+ * Format managed-region HTML comment markers (issue #1985).
+ *
+ * Rejects empty names, newlines, and `-->` so the closer cannot leak
+ * out of `<!-- remnic:begin NAME -->`.
+ */
+
+export type RegionMarkers = {
+  begin: string;
+  end: string;
+};
+
+export function formatRegionMarkers(name: string): RegionMarkers {
+  if (typeof name !== "string" || name.length === 0) {
+    throw new RangeError("Region name must be non-empty.");
+  }
+  if (name.includes("\n") || name.includes("\r")) {
+    throw new RangeError("Region name must not contain a newline.");
+  }
+  if (name.includes("-->")) {
+    throw new RangeError("Region name must not contain -->.");
+  }
+  return {
+    begin: `<!-- remnic:begin ${name} -->`,
+    end: `<!-- remnic:end ${name} -->`,
+  };
+}

package/src/activity/vault-name-trim.test.ts

@@ -0,0 +1,22 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { trimRegionName } from "./vault-name-trim.js";
+
+test("trimRegionName accepts a name", () => {
+  assert.equal(trimRegionName("timeline"), "timeline");
+});
+
+test("trimRegionName rejects an empty name", () => {
+  assert.throws(() => trimRegionName(""), /empty/i);
+  assert.throws(() => trimRegionName("   "), /empty/i);
+});
+
+test("trimRegionName rejects a newline in the name", () => {
+  assert.throws(() => trimRegionName("time\nline"), /newline/i);
+  assert.throws(() => trimRegionName("time\rline"), /newline/i);
+});
+
+test("trimRegionName trims surrounding whitespace", () => {
+  assert.equal(trimRegionName("  timeline  "), "timeline");
+});