@remnic/core 9.69.11 → 9.69.13

package/src/activity/timeline/publish-cli.test.ts

@@ -0,0 +1,169 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { parseConfig } from "../../config.js";
+import type { PluginConfig } from "../../types.js";
+import { runTimelineCliCommand } from "./query.js";
+
+const DATE = "2026-08-21";
+const RECAP = "- 09:00-10:00 code review (60m)";
+
+interface Capture {
+  out: string;
+  err: string;
+  io: { stdout: { write(chunk: string): unknown }; stderr: { write(chunk: string): unknown } };
+}
+
+function capture(): Capture {
+  const sink: Capture = {
+    out: "",
+    err: "",
+    io: {
+      stdout: {
+        write(chunk: string) {
+          sink.out += chunk;
+          return true;
+        },
+      },
+      stderr: {
+        write(chunk: string) {
+          sink.err += chunk;
+          return true;
+        },
+      },
+    },
+  };
+  return sink;
+}
+
+function makeFixture(): { config: PluginConfig; notePath: string; note: string } {
+  const root = mkdtempSync(path.join(tmpdir(), "remnic-publish-cli-"));
+  const memoryDir = path.join(root, "memory");
+  const vaultPath = path.join(root, "vault");
+  mkdirSync(path.join(memoryDir, "journal"), { recursive: true });
+  mkdirSync(vaultPath, { recursive: true });
+  writeFileSync(path.join(memoryDir, "journal", `${DATE}.md`), `${RECAP}\n`, "utf8");
+
+  const note = [
+    "# Daily",
+    "",
+    "human text that must survive",
+    "",
+    "<!-- remnic:Timeline:start -->",
+    "stale",
+    "<!-- remnic:Timeline:end -->",
+    "",
+  ].join("\n");
+  const notePath = path.join(vaultPath, `${DATE}.md`);
+  writeFileSync(notePath, note, "utf8");
+
+  const config = parseConfig({
+    memoryDir,
+    activity: {
+      timezone: "UTC",
+      timeline: { vault: { enabled: true, vaultPath, dailyNotePath: "{yyyy}-{MM}-{dd}.md" } },
+    },
+  });
+  return { config, notePath, note };
+}
+
+test("the shared timeline runner dispatches publish and writes the managed region", async () => {
+  const { config, notePath } = makeFixture();
+  const sink = capture();
+
+  const code = await runTimelineCliCommand(
+    // qa stays disabled: publish is not a qa surface and must not be gated by it.
+    { cards: null, qa: { enabled: false, maxRangeDays: 31 }, timelineEnabled: true, config },
+    ["publish", "--date", DATE],
+    sink.io,
+  );
+
+  assert.equal(code, 0, sink.err);
+  assert.doesNotMatch(sink.err, /unknown command publish/);
+  assert.match(sink.out, /updated=1/);
+  const after = readFileSync(notePath, "utf8");
+  assert.ok(after.includes(RECAP), "the recap is published into the managed region");
+  assert.ok(after.includes("human text that must survive"));
+});
+
+test("the shared timeline runner reports publish as a valid command", async () => {
+  const sink = capture();
+  const code = await runTimelineCliCommand(
+    { cards: null, qa: { enabled: true, maxRangeDays: 31 }, timelineEnabled: true },
+    ["bogus"],
+    sink.io,
+  );
+  assert.equal(code, 1);
+  assert.match(sink.err, /valid: range, search, publish/);
+});
+
+test("publish without a config refuses instead of throwing", async () => {
+  const sink = capture();
+  const code = await runTimelineCliCommand(
+    { cards: null, qa: { enabled: true, maxRangeDays: 31 }, timelineEnabled: true },
+    ["publish"],
+    sink.io,
+  );
+  assert.equal(code, 1);
+  assert.match(sink.err, /requires the Remnic config/);
+});
+
+test("--what with only separators is rejected with a validation error", async () => {
+  const { config, notePath, note } = makeFixture();
+  const sink = capture();
+
+  const code = await runTimelineCliCommand(
+    { cards: null, qa: { enabled: false, maxRangeDays: 31 }, timelineEnabled: true, config },
+    ["publish", "--date", DATE, "--what", ",,"],
+    sink.io,
+  );
+
+  assert.equal(code, 1);
+  assert.match(sink.err, /--what must name at least one artifact/);
+  assert.equal(readFileSync(notePath, "utf8"), note, "nothing is published");
+});
+
+test("publish rejects query-only flags instead of silently publishing today's note", async () => {
+  const { config, notePath, note } = makeFixture();
+  const sink = capture();
+
+  const code = await runTimelineCliCommand(
+    { cards: null, qa: { enabled: false, maxRangeDays: 31 }, timelineEnabled: true, config },
+    ["publish", "--from", "2026-08-01"],
+    sink.io,
+  );
+
+  assert.equal(code, 1);
+  assert.match(sink.err, /unknown flag --from \(valid: --date, --dry-run, --week, --what\)/);
+  assert.equal(readFileSync(notePath, "utf8"), note, "no note is touched by unsupported syntax");
+});
+
+test("range and search reject publish-only flags instead of ignoring them", async () => {
+  const { config } = makeFixture();
+  const deps = {
+    cards: null,
+    qa: { enabled: true, maxRangeDays: 31 },
+    timelineEnabled: true,
+    config,
+  } as const;
+
+  const rangeSink = capture();
+  const rangeCode = await runTimelineCliCommand(
+    deps,
+    ["range", "--date", DATE, "--from", `${DATE}T00:00:00.000Z`, "--to", `${DATE}T00:00:00.000Z`],
+    rangeSink.io,
+  );
+  assert.equal(rangeCode, 1);
+  assert.match(
+    rangeSink.err,
+    /unknown flag --date \(valid: --categories, --format, --from, --include-distractions, --to\)/,
+  );
+
+  const searchSink = capture();
+  const searchCode = await runTimelineCliCommand(deps, ["search", "--query", "x", "--dry-run"], searchSink.io);
+  assert.equal(searchCode, 1);
+  assert.match(searchSink.err, /unknown flag --dry-run \(valid: --from, --limit, --query, --to\)/);
+});

package/src/activity/timeline/publish-cli.ts

@@ -0,0 +1,144 @@
+/**
+ * Shared `timeline publish` implementation (issue #1985).
+ *
+ * Both CLI trees dispatch this one function: the host command group in
+ * `cli/timeline-publish-commands.ts` and the standalone binary's shared
+ * runner in `timeline/query.ts`. A documented command that exists on only
+ * one tree is a defect — the shipped `@remnic/cli` binary must publish too.
+ */
+import { existsSync, readFileSync } from "node:fs";
+
+import type { PluginConfig } from "../../types.js";
+import { activityDateInTimezone, isValidActivityDate } from "../digest.js";
+import { journalPath } from "../journal.js";
+import { publishVaultNote, type VaultSectionPublish } from "../vault-publisher.js";
+
+export interface TimelinePublishIo {
+  stdout: { write(chunk: string): unknown };
+  stderr: { write(chunk: string): unknown };
+}
+
+export interface TimelinePublishOptions {
+  date?: unknown;
+  week?: unknown;
+  what?: unknown;
+  dryRun?: unknown;
+}
+
+const AVAILABLE_KINDS = ["timeline"] as const;
+const KNOWN_KINDS = ["timeline", "standup", "weekly", "locations"] as const;
+const UNLANDED_REASONS: Record<string, string> = {
+  standup: "the standup renderer lands with timeline phase 3",
+  weekly: "the weekly review renderer lands with timeline phase 4",
+  locations: "the location day renderer is not wired to publishing yet",
+};
+
+export function runTimelinePublishCli(
+  config: PluginConfig,
+  options: TimelinePublishOptions,
+  io: TimelinePublishIo,
+): number {
+  const vault = config.activity?.timeline?.vault;
+
+  if (options.week !== undefined) {
+    io.stderr.write("--week is not available yet: the weekly review renderer lands with timeline phase 4.\n");
+    return 1;
+  }
+  if (!vault || vault.enabled !== true) {
+    io.stderr.write(
+      "Vault publishing is disabled: set activity.timeline.vault.enabled=true and configure vaultPath first.\n",
+    );
+    return 1;
+  }
+
+  // Timeline artifacts are grouped on the configured activity timezone's
+  // calendar day, so "today" must be derived there — the host-local day
+  // drifts by one near either timezone's midnight.
+  const date =
+    typeof options.date === "string" && options.date.length > 0
+      ? options.date
+      : activityDateInTimezone(new Date(), config.activity?.timezone ?? "UTC");
+  if (!isValidActivityDate(date)) {
+    io.stderr.write(`Invalid --date "${date}"; expected YYYY-MM-DD.\n`);
+    return 1;
+  }
+
+  const requested = parseKinds(typeof options.what === "string" && options.what.length > 0 ? options.what : "timeline");
+  if (typeof requested !== "string") {
+    io.stderr.write(requested.error);
+    return 1;
+  }
+  const kinds = requested.split(",");
+  const sections: VaultSectionPublish[] = [];
+  let notePathTemplate = vault.dailyNotePath;
+
+  for (const kind of kinds) {
+    if ((AVAILABLE_KINDS as readonly string[]).indexOf(kind) === -1) {
+      io.stderr.write(`--what ${kind} is not available yet: ${UNLANDED_REASONS[kind] ?? "unknown kind"}.\n`);
+      return 1;
+    }
+    const target = vault.publish[kind as "timeline"];
+    if (target.enabled !== true) {
+      io.stderr.write(`--what ${kind} is disabled: enable activity.timeline.vault.publish.${kind}.enabled.\n`);
+      return 1;
+    }
+    // Honor the target's configured note file; config parsing already
+    // rejects target="weekly" with an empty weeklyNotePath.
+    notePathTemplate = target.target === "weekly" ? vault.weeklyNotePath : vault.dailyNotePath;
+    const source = journalPath(config.memoryDir, date);
+    if (!existsSync(source)) {
+      io.stderr.write(
+        `No timeline artifact for ${date}: run the journal recap generation first (${kind} target reads the persisted day recap).\n`,
+      );
+      return 1;
+    }
+    sections.push({ name: target.section, content: readFileSync(source, "utf8").trimEnd() });
+  }
+
+  const status = publishVaultNote({
+    vaultPath: vault.vaultPath,
+    notePathTemplate,
+    date,
+    sections,
+    strategy: vault.sectionStrategy,
+    insertUnderHeading: vault.insertUnderHeading.length > 0 ? vault.insertUnderHeading : undefined,
+    createMissingNotes: vault.createMissingNotes,
+    noteTemplate: vault.noteTemplate.length > 0 ? vault.noteTemplate : undefined,
+    propertiesMode: vault.properties.mode,
+    propertiesPrefix: vault.properties.prefix,
+    dryRun: options.dryRun === true,
+  });
+
+  for (const row of status.results) {
+    const label = row.outcome === "updated" && options.dryRun === true ? "would update" : row.outcome;
+    io.stdout.write(`${label}  ${row.path}${row.reason ? `  (${row.reason})` : ""}\n`);
+  }
+  io.stdout.write(
+    `updated=${status.counts.updated} unchanged=${status.counts.unchanged} skipped=${status.counts.skipped} error=${status.counts.error}\n`,
+  );
+  return status.hasError ? 1 : 0;
+}
+
+/**
+ * `--what` is normalized to a comma-joined kind list. An empty normalized
+ * list (`--what ','`) is rejected here rather than reaching the publisher,
+ * which throws a RangeError on a zero-length section list.
+ */
+function parseKinds(raw: string): string | { error: string } {
+  const kinds = raw
+    .split(",")
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0);
+  for (const kind of kinds) {
+    if ((KNOWN_KINDS as readonly string[]).indexOf(kind) === -1) {
+      return { error: `Unknown --what kind "${kind}"; valid kinds are ${KNOWN_KINDS.join(", ")}.\n` };
+    }
+  }
+  if (new Set(kinds).size !== kinds.length) {
+    return { error: "--what must not repeat a kind.\n" };
+  }
+  if (kinds.length === 0) {
+    return { error: `--what must name at least one artifact; valid kinds are ${KNOWN_KINDS.join(", ")}.\n` };
+  }
+  return kinds.join(",");
+}

package/src/activity/timeline/query.ts

@@ -9,7 +9,9 @@
  * MCP/HTTP and recall injection are later PRs.
  */
 import { parseFlexibleIsoTimestamp } from "../../utils/iso-timestamp.js";
+import type { PluginConfig } from "../../types.js";
 import type { ActivityTimelineQaConfig } from "../types.js";
+import { runTimelinePublishCli } from "./publish-cli.js";
 import type { TimelineCard } from "./types.js";
 
 const RANGE_FORMATS = ["cards", "compact"] as const;
@@ -70,6 +72,8 @@ export interface TimelineCliDeps {
   cards: readonly TimelineQueryCard[] | null;
   qa: ActivityTimelineQaConfig;
   timelineEnabled?: boolean;
+  /** Required for `publish`; range/search never read it. */
+  config?: PluginConfig;
 }
 
 const USAGE = `Usage: timeline <command> [options]
@@ -77,17 +81,25 @@ const USAGE = `Usage: timeline <command> [options]
 Commands:
   range --from <ISO> --to <ISO> [--format cards|compact] [--categories id,id] [--include-distractions]
   search --query <text> [--from <ISO>] [--to <ISO>] [--limit N]
+  publish [--date YYYY-MM-DD] [--what timeline] [--dry-run]
 `;
 
-const VALUE_FLAGS: Record<string, true> = {
-  "--from": true,
-  "--to": true,
-  "--format": true,
-  "--categories": true,
-  "--query": true,
-  "--limit": true,
+// Per-subcommand flag allow-lists (issue #1985 review): a shared union table
+// let `timeline publish --from …` parse and then silently discard `--from`,
+// publishing today's note on a query-only flag — and `range --date` likewise.
+// Every subcommand validates its own syntax before dispatch.
+const PUBLISH_FLAGS = {
+  value: { "--date": true, "--week": true, "--what": true } as Record<string, true>,
+  boolean: { "--dry-run": true } as Record<string, true>,
+};
+const RANGE_FLAGS = {
+  value: { "--from": true, "--to": true, "--format": true, "--categories": true } as Record<string, true>,
+  boolean: { "--include-distractions": true } as Record<string, true>,
+};
+const SEARCH_FLAGS = {
+  value: { "--query": true, "--from": true, "--to": true, "--limit": true } as Record<string, true>,
+  boolean: {} as Record<string, true>,
 };
-const BOOLEAN_FLAGS: Record<string, true> = { "--include-distractions": true };
 
 function parseInstant(value: string, label: string): number {
   const ms = parseFlexibleIsoTimestamp(value);
@@ -214,16 +226,19 @@ export function queryTimelineSearch(
   return { ok: true, results: ranked };
 }
 
-function parseFlags(args: string[]): { flags: Map<string, string | true>; positional: string[] } {
+function parseFlags(
+  args: string[],
+  spec: { value: Record<string, true>; boolean: Record<string, true> },
+): { flags: Map<string, string | true>; positional: string[] } {
   const flags = new Map<string, string | true>();
   const positional: string[] = [];
-  for (let i = 0; i < args.length; i++) {
+  for (let i = 0; i < args.length; i += 1) {
     const arg = args[i]!;
     if (!arg.startsWith("--")) {
       positional.push(arg);
       continue;
     }
-    if (VALUE_FLAGS[arg] === true) {
+    if (spec.value[arg] === true) {
       const value = args[i + 1];
       if (value === undefined || value.startsWith("--")) {
         throw new TypeError(`flag ${arg} requires a value`);
@@ -232,11 +247,11 @@ function parseFlags(args: string[]): { flags: Map<string, string | true>; positi
       i += 1;
       continue;
     }
-    if (BOOLEAN_FLAGS[arg] === true) {
+    if (spec.boolean[arg] === true) {
       flags.set(arg, true);
       continue;
     }
-    const known = [...Object.keys(VALUE_FLAGS), ...Object.keys(BOOLEAN_FLAGS)].sort().join(", ");
+    const known = [...Object.keys(spec.value), ...Object.keys(spec.boolean)].sort().join(", ");
     throw new TypeError(`unknown flag ${arg} (valid: ${known})`);
   }
   return { flags, positional };
@@ -259,11 +274,32 @@ export async function runTimelineCliCommand(
       io.stdout.write(USAGE);
       return command === undefined ? 1 : 0;
     }
+    // `publish` writes into the user's vault and is not a qa/query surface,
+    // so it dispatches before the qa gate. Flags are validated against the
+    // publish-only set: `--from`/`--format` are query syntax and must be
+    // rejected here, not silently dropped while today's note is published.
+    if (command === "publish") {
+      if (deps.config === undefined) {
+        io.stderr.write("timeline publish requires the Remnic config — run `remnic doctor`\n");
+        return 1;
+      }
+      const publishFlags = parseFlags(rest, PUBLISH_FLAGS).flags;
+      return runTimelinePublishCli(
+        deps.config,
+        {
+          date: flagString(publishFlags, "--date"),
+          week: flagString(publishFlags, "--week"),
+          what: flagString(publishFlags, "--what"),
+          dryRun: publishFlags.get("--dry-run") === true,
+        },
+        io,
+      );
+    }
     if (deps.timelineEnabled === false || !deps.qa.enabled) {
       io.stderr.write("timeline qa disabled — set activity.timeline.qa.enabled=true\n");
       return 1;
     }
-    const { flags } = parseFlags(rest);
+    const { flags } = parseFlags(rest, command === "range" ? RANGE_FLAGS : SEARCH_FLAGS);
     if (command === "range") {
       const from = flagString(flags, "--from");
       const to = flagString(flags, "--to");
@@ -305,7 +341,7 @@ export async function runTimelineCliCommand(
       io.stdout.write(`${JSON.stringify(result)}\n`);
       return result.ok ? 0 : 1;
     }
-    throw new TypeError(`unknown command ${command} (valid: range, search)`);
+    throw new TypeError(`unknown command ${command} (valid: range, search, publish)`);
   } catch (err) {
     io.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
     return 1;

package/src/activity/types.ts

@@ -105,6 +105,50 @@ export interface ActivityTimelineJournalConfig {
   heading?: string;
 }
 
+/** Section ownership strategy for vault publishing (issue #1985). */
+export type VaultSectionStrategy = "markers" | "heading";
+
+/** Where section stats are written (issue #1985). `off` writes none. */
+export type VaultPropertiesMode = "off" | "frontmatter" | "dataview-inline";
+
+export interface ActivityTimelineVaultTargetConfig {
+  enabled: boolean;
+  target: "daily" | "weekly";
+  section: string;
+}
+
+/**
+ * Opt-in markdown-vault publisher settings (issue #1985). Default off:
+ * `enabled: false` means no vault reads or writes ever occur.
+ */
+export interface ActivityTimelineVaultConfig {
+  enabled: boolean;
+  /** Vault root; absolute or `~` path. Required and non-empty when enabled. */
+  vaultPath: string;
+  /** Vault-relative daily-note path template; date tokens. */
+  dailyNotePath: string;
+  /** Empty means weekly-note publishing is disabled. */
+  weeklyNotePath: string;
+  createMissingNotes: boolean;
+  /** Vault-relative template file, used only when creating a missing note. */
+  noteTemplate: string;
+  sectionStrategy: VaultSectionStrategy;
+  publish: {
+    timeline: ActivityTimelineVaultTargetConfig;
+    /** Standup target lights up when phase 3 lands. */
+    standup: ActivityTimelineVaultTargetConfig;
+    /** Weekly target lights up when phase 4 lands. */
+    weekly: ActivityTimelineVaultTargetConfig;
+    /** Locations target lights up with the location day renderer. */
+    locations: ActivityTimelineVaultTargetConfig;
+  };
+  /** Markers strategy: heading under which missing marker pairs are inserted; empty = never insert. */
+  insertUnderHeading: string;
+  wikilinks: { places: boolean; placesFolder: string };
+  properties: { mode: VaultPropertiesMode; prefix: string };
+  autoPublish: boolean;
+}
+
 /** Opt-in timeline Q&A range/search settings (issue #1983 PR1). Default off. */
 export interface ActivityTimelineQaConfig {
   enabled: boolean;
@@ -117,6 +161,7 @@ export interface ActivityTimelineConfig {
   enabled: boolean;
   journal: ActivityTimelineJournalConfig;
   qa: ActivityTimelineQaConfig;
+  vault: ActivityTimelineVaultConfig;
 }
 
 /** Opt-in activity synchronization + trust-gated extraction settings. */

package/src/activity/vault-insert.ts

@@ -2,10 +2,13 @@
  * Managed-region marker insertion (issue #1985).
  *
  * Inserts a `<!-- remnic:<name>:start/end -->` pair under a unique ATX
- * heading when the region is absent. This helper never replaces (see
- * `vault-publish.ts`), never creates files, and never invents a heading.
- * Pure string-in/string-out.
+ * heading when the region is absent. Code blocks — fenced or indented —
+ * are invisible to
+ * the heading scan, so a live region is never inserted into a `## …`
+ * example. This helper never replaces (see `vault-publish.ts`), never
+ * creates files, and never invents a heading. Pure string-in/string-out.
  */
+import { fileLines, parseAtxHeading } from "./vault-publish.js";
 
 export type InsertVaultRegionResult =
   | { ok: true; text: string; inserted: true }
@@ -26,13 +29,17 @@ export function insertMarkersUnderHeading(
 
   const startMarker = `<!-- remnic:${opts.name}:start -->`;
   const endMarker = `<!-- remnic:${opts.name}:end -->`;
-  if (fileText.includes(startMarker) && fileText.includes(endMarker)) {
-    return { ok: true, text: fileText, inserted: false };
-  }
-
   const rows = fileLines(fileText);
+  // A fenced example pair is sample text, not a live region (issue #1985):
+  // only markers outside a code block count as "already present".
+  const present =
+    rows.some((row) => !row.fenced && row.line.includes(startMarker)) &&
+    rows.some((row) => !row.fenced && row.line.includes(endMarker));
+  if (present) return { ok: true, text: fileText, inserted: false };
+
   const hits: Array<{ row: (typeof rows)[number]; level: number }> = [];
   for (const row of rows) {
+    if (row.fenced) continue;
     const heading = parseAtxHeading(row.line);
     if (heading && heading.text === opts.heading) {
       hits.push({ row, level: heading.level });
@@ -58,29 +65,3 @@ export function insertMarkersUnderHeading(
   return { ok: true, text, inserted: true };
 }
 
-type FileLine = { line: string; start: number; next: number; number: number };
-
-function fileLines(fileText: string): FileLine[] {
-  const rows: FileLine[] = [];
-  let start = 0;
-  let number = 1;
-  while (start < fileText.length) {
-    let i = start;
-    while (i < fileText.length && fileText[i] !== "\n" && fileText[i] !== "\r") i++;
-    let next = i;
-    if (fileText[i] === "\r" && fileText[i + 1] === "\n") next = i + 2;
-    else if (fileText[i] === "\n" || fileText[i] === "\r") next = i + 1;
-    else next = fileText.length;
-    rows.push({ line: fileText.slice(start, i), start, next, number });
-    number += 1;
-    start = next;
-  }
-  return rows;
-}
-
-function parseAtxHeading(line: string): { level: number; text: string } | null {
-  let level = 0;
-  while (level < line.length && level < 6 && line[level] === "#") level++;
-  if (level === 0 || line[level] !== " ") return null;
-  return { level, text: line.slice(level + 1) };
-}