mirror-mind 0.0.1 → 0.33.0

package/ts/src/init/init.ts

@@ -0,0 +1,111 @@
+// `init` — bootstrap a user home from repository identity templates. The port
+// of memory.cli.init. Filesystem-only: no database is opened or touched.
+//
+// Deliberate, verified divergence: Python's `main()` never catches
+// FileExistsError/FileNotFoundError from init_user_home, so those paths exit
+// via an uncaught exception — a raw Python traceback with this machine's
+// absolute file paths on stderr, exit 1. That traceback is an implementation
+// leak, not a designed CLI contract (unlike, say, `identity get`'s deliberate
+// one-line not-found message) — it is not meaningful or possible to replicate
+// byte-for-byte (it depends on Python's own call stack and module paths, which
+// drift on every refactor and reveal nothing product-relevant). This port
+// preserves the observable CONTRACT instead: exit 1, and a stderr message that
+// names the failure. See the CLI wiring in ../frontDoor/cli.ts.
+
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { runningTreeRoot } from "#runtime/treeRoot.ts";
+
+/** Port of Python's uncaught `FileNotFoundError` for a missing templates root. */
+export class TemplatesNotFoundError extends Error {}
+
+/** Port of Python's uncaught `FileExistsError` for a non-empty identity root. */
+export class IdentityRootExistsError extends Error {
+  readonly path: string;
+  constructor(path: string) {
+    super(`Identity root already exists and is not empty: ${path}`);
+    this.path = path;
+  }
+}
+
+/**
+ * `<tree root>/templates/identity`. Python's `find_templates_identity_root`
+ * walked up from its own file for the directory; since CV22.DS10.US3 the tree
+ * root is one resolver shared with release notes and the welcome card, and
+ * the templates ship in the package at the same path as in the checkout.
+ */
+export function templatesIdentityRoot(treeRoot: string = runningTreeRoot()): string {
+  const candidate = join(treeRoot, "templates", "identity");
+  if (existsSync(candidate)) return candidate;
+  throw new TemplatesNotFoundError(`Could not find templates/identity under ${treeRoot}.`);
+}
+
+/**
+ * Where `init` creates a user's home: `<home>/.mirror-minds/<user>`, the path
+ * `MIRROR_USER=<user>` resolves to.
+ *
+ * Python's `default_user_home` hardcoded the legacy `~/.mirror/<user>` and told
+ * the person to set MIRROR_HOME by hand. CV22.DS10.US3 (D3) has `init` write
+ * `MIRROR_USER` into the config file instead, and a legacy home would then
+ * make every later command print the legacy-path warning (D14).
+ */
+export function defaultUserHome(user: string, home: string = homedir()): string {
+  return join(home, ".mirror-minds", user);
+}
+
+/** Every `.yaml` file under `root`, recursively (mirrors `Path.rglob("*.yaml")`). */
+function yamlFilesRecursive(root: string): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    const full = join(root, entry.name);
+    if (entry.isDirectory()) out.push(...yamlFilesRecursive(full));
+    else if (entry.isFile() && full.endsWith(".yaml")) out.push(full);
+  }
+  return out;
+}
+
+/**
+ * Port of `_substitute_user_name`: replace every `{{user_name}}` token in every
+ * `.yaml` file under `identityRoot` with `user`, writing back only files that
+ * actually contained the token. Non-`.yaml` files (e.g. `README.md`) are
+ * intentionally left untouched, matching the Python glob scope exactly.
+ */
+function substituteUserName(identityRoot: string, user: string): void {
+  for (const file of yamlFilesRecursive(identityRoot)) {
+    const content = readFileSync(file, "utf8");
+    if (content.includes("{{user_name}}")) {
+      writeFileSync(file, content.replaceAll("{{user_name}}", user), "utf8");
+    }
+  }
+}
+
+export interface InitUserHomeOptions {
+  /** Overrides the located templates root (tests only; production auto-locates it). */
+  templatesIdentityRoot?: string;
+  /** Overrides the destination home (tests only; production uses defaultUserHome). */
+  userHome?: string;
+}
+
+/**
+ * Port of `init_user_home`: locate the identity templates, refuse a non-empty
+ * existing destination, copy the template tree, substitute `{{user_name}}` in
+ * every `.yaml` file, and return the destination identity root.
+ */
+export function initUserHome(user: string, options: InitUserHomeOptions = {}): string {
+  const templatesRoot = options.templatesIdentityRoot ?? templatesIdentityRoot();
+  if (!existsSync(templatesRoot)) {
+    throw new TemplatesNotFoundError(`Identity templates not found: ${templatesRoot}`);
+  }
+
+  const destinationHome = options.userHome ?? defaultUserHome(user);
+  const identityRoot = join(destinationHome, "identity");
+  if (existsSync(identityRoot) && readdirSync(identityRoot).length > 0) {
+    throw new IdentityRootExistsError(identityRoot);
+  }
+
+  mkdirSync(destinationHome, { recursive: true });
+  cpSync(templatesRoot, identityRoot, { recursive: true });
+  substituteUserName(identityRoot, user);
+  return identityRoot;
+}

package/ts/src/journey/journeyOptions.ts

@@ -0,0 +1,131 @@
+// Journey listing parity port (CV22.DS2.US3).
+//
+// A faithful TypeScript port of Python `JourneyService.list_journey_options` +
+// `_sort_journey_options` (`src/memory/services/journey.py`). The logic is pure
+// over the `journey` identity rows: it derives each journey's display name,
+// status, and parent from row content/metadata, then orders every descendant in
+// bounded depth-first order. Reading the rows out of the SQLite
+// seam belongs to the caller, keeping this the pure decision core.
+
+import { resolveParentJourney } from "./parentJourney.ts";
+
+/** One `journey`-layer identity row, as read from the DB. */
+export interface JourneyIdentityRow {
+  key: string;
+  content: string;
+  metadata?: string | null;
+  /** Migration 017's derived parent projection. Metadata remains semantic
+   * authority while Python and TS can both write parentage (CR050). */
+  parent_journey?: string | null;
+}
+
+/** A journey option DTO with hierarchy metadata, mirroring the Python output. */
+export interface JourneyOption {
+  id: string;
+  name: string;
+  status: string;
+  parent_journey: string;
+  depth: number;
+  lineage: string[];
+}
+
+type UnorderedJourneyOption = Omit<JourneyOption, "depth" | "lineage">;
+
+/** Build the unordered option fields for a single journey row. */
+function toOption(row: JourneyIdentityRow): UnorderedJourneyOption {
+  const content = row.content || "";
+  // Python: content.split("\n")[0].strip().lstrip("# ").strip()
+  const firstLine = (content.split("\n")[0] ?? "")
+    .trim()
+    .replace(/^[# ]+/, "")
+    .trim();
+  const statusMatch = content.match(/\*\*Status:\*\*\s*([^\n]+)/);
+  const status = statusMatch ? statusMatch[1].trim() : "unknown";
+  return {
+    id: row.key,
+    name: firstLine || row.key,
+    status,
+    parent_journey: resolveParentJourney(row),
+  };
+}
+
+/** A roots-then-children split of journey-like items keyed by `parent_journey`. */
+export interface JourneyHierarchy<T> {
+  roots: T[];
+  childrenByParent: Map<string, T[]>;
+}
+
+/**
+ * Split items into roots and children by `parent_journey`, preserving input
+ * order within each group. An item whose parent is empty or absent from the set
+ * is a root. The depth-first sorter consumes this index; renderers consume the
+ * resulting ordered projection and must not reconstruct a shallower hierarchy.
+ */
+export function groupJourneysByParent<T extends { id: string; parent_journey: string }>(
+  items: readonly T[],
+): JourneyHierarchy<T> {
+  const knownIds = new Set(items.map((item) => item.id));
+  const roots: T[] = [];
+  const childrenByParent = new Map<string, T[]>();
+  for (const item of items) {
+    const parent = item.parent_journey || "";
+    if (parent && knownIds.has(parent)) {
+      const bucket = childrenByParent.get(parent);
+      if (bucket) bucket.push(item);
+      else childrenByParent.set(parent, [item]);
+    } else {
+      roots.push(item);
+    }
+  }
+  return { roots, childrenByParent };
+}
+
+/**
+ * Order every option in bounded depth-first hierarchy order, mirroring the
+ * released Python `_sort_journey_options` oracle.
+ *
+ * Roots (no parent, or a parent absent from the set) and every sibling set are
+ * sorted by `(status !== "active", name.toLowerCase())`. A visited set makes
+ * malformed legacy cycles bounded; a final sorted pass starts each rootless
+ * component so corrupt rows remain visible exactly once.
+ */
+function sortJourneyOptions(options: UnorderedJourneyOption[]): JourneyOption[] {
+  const { roots, childrenByParent } = groupJourneysByParent(options);
+
+  const compare = (a: UnorderedJourneyOption, b: UnorderedJourneyOption): number => {
+    const aInactive = a.status !== "active" ? 1 : 0;
+    const bInactive = b.status !== "active" ? 1 : 0;
+    if (aInactive !== bInactive) return aInactive - bInactive;
+    const aName = a.name.toLowerCase();
+    const bName = b.name.toLowerCase();
+    return aName < bName ? -1 : aName > bName ? 1 : 0;
+  };
+
+  const ordered: JourneyOption[] = [];
+  const visited = new Set<string>();
+
+  const appendBranch = (item: UnorderedJourneyOption, lineage: string[]): void => {
+    if (visited.has(item.id)) return;
+    visited.add(item.id);
+    const currentLineage = [...lineage, item.id];
+    ordered.push({ ...item, depth: lineage.length, lineage: currentLineage });
+    for (const child of [...(childrenByParent.get(item.id) ?? [])].sort(compare)) {
+      appendBranch(child, currentLineage);
+    }
+  };
+
+  for (const root of [...roots].sort(compare)) appendBranch(root, []);
+  for (const unvisited of [...options].sort(compare)) {
+    if (!visited.has(unvisited.id)) appendBranch(unvisited, []);
+  }
+  return ordered;
+}
+
+/**
+ * Return all journeys as option DTOs with hierarchy metadata, reproducing the
+ * Python oracle. `rows` must arrive in the DB's `ORDER BY key` order (as
+ * `get_identity_by_layer` returns them) so stable-sort tie-breaks match Python.
+ */
+export function listJourneyOptions(rows: readonly JourneyIdentityRow[]): JourneyOption[] {
+  return sortJourneyOptions(rows.map(toOption));
+}

package/ts/src/journey/journeyRemoval.ts

@@ -0,0 +1,158 @@
+// Conservative journey removal ported from the v0.31.9 Python domain operation.
+//
+// A journey is deletable only when it exists, has no metadata-authoritative
+// children, and has no durable association in the closed inventory below. The
+// complete check and the single identity DELETE share BEGIN IMMEDIATE so a
+// competing writer that commits first is visible before the decision.
+
+import { type WritableDatabase, withTransaction } from "#db/database.ts";
+
+export interface JourneyAssociationCounts {
+  child_journeys: number;
+  journey_paths: number;
+  identity_integrations: number;
+  conversations: number;
+  memories: number;
+  tasks: number;
+  attachments: number;
+  runtime_sessions: number;
+  explorer_stories: number;
+  refinement_stories: number;
+  change_requests: number;
+  refinement_cursors: number;
+}
+
+export class JourneyRemovalError extends Error {
+  readonly slug: string;
+  readonly associations?: JourneyAssociationCounts;
+
+  constructor(slug: string, message: string, associations?: JourneyAssociationCounts) {
+    super(message);
+    this.slug = slug;
+    this.associations = associations;
+  }
+}
+
+function count(db: WritableDatabase, sql: string, journey: string): number {
+  const value = db.prepare(sql).get(journey)?.count;
+  if (typeof value === "number") return value;
+  if (typeof value === "bigint") return Number(value);
+  throw new Error("journey association count did not return a number");
+}
+
+/**
+ * Count the released closed inventory of records that removal would orphan.
+ * Every query is a fixed literal. Child parentage comes only from valid JSON
+ * metadata (CR050 semantic authority), never migration 017's projection.
+ */
+export function countJourneyAssociations(
+  db: WritableDatabase,
+  journey: string,
+): JourneyAssociationCounts {
+  return {
+    child_journeys: count(
+      db,
+      `SELECT COUNT(*) AS count FROM identity
+       WHERE layer = 'journey'
+         AND CASE WHEN json_valid(metadata)
+                  THEN json_extract(metadata, '$.parent_journey') END = ?`,
+      journey,
+    ),
+    journey_paths: count(
+      db,
+      "SELECT COUNT(*) AS count FROM identity WHERE layer = 'journey_path' AND key = ?",
+      journey,
+    ),
+    identity_integrations: count(
+      db,
+      "SELECT COUNT(*) AS count FROM identity_integrations WHERE layer = 'journey' AND key = ?",
+      journey,
+    ),
+    conversations: count(
+      db,
+      "SELECT COUNT(*) AS count FROM conversations WHERE journey = ?",
+      journey,
+    ),
+    memories: count(db, "SELECT COUNT(*) AS count FROM memories WHERE journey = ?", journey),
+    tasks: count(db, "SELECT COUNT(*) AS count FROM tasks WHERE journey = ?", journey),
+    attachments: count(
+      db,
+      "SELECT COUNT(*) AS count FROM attachments WHERE journey_id = ?",
+      journey,
+    ),
+    runtime_sessions: count(
+      db,
+      "SELECT COUNT(*) AS count FROM runtime_sessions WHERE journey = ?",
+      journey,
+    ),
+    explorer_stories: count(
+      db,
+      "SELECT COUNT(*) AS count FROM exploratory_stories WHERE journey = ?",
+      journey,
+    ),
+    refinement_stories: count(
+      db,
+      "SELECT COUNT(*) AS count FROM builder_refinement_stories WHERE journey = ?",
+      journey,
+    ),
+    change_requests: count(
+      db,
+      "SELECT COUNT(*) AS count FROM builder_change_requests WHERE journey = ?",
+      journey,
+    ),
+    refinement_cursors: count(
+      db,
+      "SELECT COUNT(*) AS count FROM builder_refinement_cursors WHERE journey = ?",
+      journey,
+    ),
+  };
+}
+
+const ASSOCIATED_RECORD_KEYS = [
+  "journey_paths",
+  "identity_integrations",
+  "conversations",
+  "memories",
+  "tasks",
+  "attachments",
+  "runtime_sessions",
+  "explorer_stories",
+  "refinement_stories",
+  "change_requests",
+  "refinement_cursors",
+] as const satisfies readonly (keyof JourneyAssociationCounts)[];
+
+/** Remove exactly one empty leaf journey, or throw without mutating state. */
+export function removeJourney(db: WritableDatabase, journey: string): true {
+  return withTransaction(db, () => {
+    const exists = db
+      .prepare("SELECT 1 AS present FROM identity WHERE layer = 'journey' AND key = ?")
+      .get(journey);
+    if (exists === undefined) {
+      throw new JourneyRemovalError(journey, `Journey '${journey}' not found`);
+    }
+
+    const associations = countJourneyAssociations(db, journey);
+    if (associations.child_journeys > 0) {
+      throw new JourneyRemovalError(
+        journey,
+        `Journey '${journey}' has child journeys; move or remove them first`,
+        associations,
+      );
+    }
+
+    const details = ASSOCIATED_RECORD_KEYS.filter((key) => associations[key] > 0).map(
+      (key) => `${key}=${associations[key]}`,
+    );
+    if (details.length > 0) {
+      throw new JourneyRemovalError(
+        journey,
+        `Journey '${journey}' has associated records: ${details.join(", ")}`,
+        associations,
+      );
+    }
+
+    db.prepare("DELETE FROM identity WHERE layer = 'journey' AND key = ?").run(journey);
+    return true;
+  });
+}

package/ts/src/journey/journeyStatus.ts

@@ -0,0 +1,149 @@
+// `journey status` read primitives — the port of JourneyService.get_journey_status,
+// get_journey_path, get_sync_file, and the store reads it composes
+// (get_memories_by_journey, get_recent_conversations_by_journey).
+
+import { readFileSync } from "node:fs";
+import type { Database } from "#db/database.ts";
+import { optionalString, requireString } from "#db/rowDecode.ts";
+import { getIdentityContent, getIdentityMetadata } from "#identity/identityRead.ts";
+import { expandHome } from "#util/paths.ts";
+
+const JOURNEY_LAYER = "journey";
+/** The `journey_path` identity layer, also the write target of `journey update`. */
+export const JOURNEY_PATH_LAYER = "journey_path";
+
+export interface JourneyStatusMemoryRow {
+  created_at: string;
+  title: string;
+}
+
+export interface JourneyStatusConversationRow {
+  started_at: string;
+  title: string | null;
+}
+
+export interface JourneyStatusEntry {
+  journeyId: string;
+  identity: string | null;
+  journeyPath: string | null;
+  recentMemories: JourneyStatusMemoryRow[];
+  recentConversations: JourneyStatusConversationRow[];
+}
+
+/** Reads a file as utf8 text; injectable so tests never touch the real filesystem. */
+export type ReadTextFile = (path: string) => string;
+
+const defaultReadTextFile: ReadTextFile = (path) => readFileSync(path, "utf8");
+
+/** Port of `get_sync_file`: the journey's own metadata `sync_file`, or null. */
+export function getSyncFile(db: Database, journeyKey: string): string | null {
+  const metadata = getIdentityMetadata(db, JOURNEY_LAYER, journeyKey);
+  if (!metadata) return null;
+  try {
+    const parsed = JSON.parse(metadata) as unknown;
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    const value = (parsed as Record<string, unknown>).sync_file;
+    return typeof value === "string" ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Port of `get_project_path`: the journey's metadata `project_path`, expanded.
+ *
+ * Python expands `~` defensively on read, because values written before
+ * write-side normalization can still be stored in tilde form. A no-op for
+ * canonical paths, and load-bearing for the ones it is not.
+ */
+export function getProjectPath(db: Database, journeyKey: string): string | null {
+  const metadata = getIdentityMetadata(db, JOURNEY_LAYER, journeyKey);
+  if (!metadata) return null;
+  try {
+    const parsed = JSON.parse(metadata) as unknown;
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    const value = (parsed as Record<string, unknown>).project_path;
+    return typeof value === "string" ? expandHome(value) : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Port of `get_journey_path`: prefer the external sync file (expanduser'd) when
+ * configured and readable; on ANY read failure (missing, permission, or other
+ * I/O error — matching Python's broad `OSError` catch), fall back to the
+ * database's `journey_path` identity content.
+ */
+export function getJourneyPathContent(
+  db: Database,
+  journeyKey: string,
+  readTextFile: ReadTextFile = defaultReadTextFile,
+): string | null {
+  const syncFile = getSyncFile(db, journeyKey);
+  if (syncFile) {
+    try {
+      return readTextFile(expandHome(syncFile));
+    } catch {
+      // Fall through to the database.
+    }
+  }
+  return getIdentityContent(db, JOURNEY_PATH_LAYER, journeyKey);
+}
+
+/** Port of `store.get_memories_by_journey(journey)[:10]`, LIMIT pushed down to SQL. */
+export function getMemoriesByJourney(
+  db: Database,
+  journeyKey: string,
+  limit = 10,
+): JourneyStatusMemoryRow[] {
+  return db
+    .prepare(
+      "SELECT created_at, title FROM memories WHERE journey = ? ORDER BY created_at DESC LIMIT ?",
+    )
+    .all(journeyKey, limit)
+    .map((row) => ({
+      created_at: requireString(row, "created_at"),
+      title: requireString(row, "title"),
+    }));
+}
+
+/** Port of `store.get_recent_conversations_by_journey(journey, limit=5)`. */
+export function getRecentConversationsByJourney(
+  db: Database,
+  journeyKey: string,
+  limit = 5,
+): JourneyStatusConversationRow[] {
+  return db
+    .prepare(
+      "SELECT started_at, title FROM conversations WHERE journey = ? ORDER BY started_at DESC LIMIT ?",
+    )
+    .all(journeyKey, limit)
+    .map((row) => ({
+      started_at: requireString(row, "started_at"),
+      title: optionalString(row, "title"),
+    }));
+}
+
+/** Port of `_get_journey_identities()` keys only: every journey key, ordered. */
+export function allJourneyKeys(db: Database): string[] {
+  return db
+    .prepare("SELECT key FROM identity WHERE layer = 'journey' ORDER BY key")
+    .all()
+    .map((row) => requireString(row, "key"));
+}
+
+/** Port of `get_journey_status` for an explicit, pre-resolved list of journey keys. */
+export function getJourneyStatusEntries(
+  db: Database,
+  journeyKeys: readonly string[],
+  readTextFile: ReadTextFile = defaultReadTextFile,
+): JourneyStatusEntry[] {
+  return journeyKeys.map((journeyId) => ({
+    journeyId,
+    identity: getIdentityContent(db, JOURNEY_LAYER, journeyId),
+    journeyPath: getJourneyPathContent(db, journeyId, readTextFile),
+    recentMemories: getMemoriesByJourney(db, journeyId, 10),
+    recentConversations: getRecentConversationsByJourney(db, journeyId, 5),
+  }));
+}

package/ts/src/journey/journeySyncFile.ts

@@ -0,0 +1,87 @@
+// Journey sync-file metadata parity port (CV22.DS7.US2 slice 3c).
+//
+// A faithful port of `JourneyService.get_sync_file` / `set_sync_file` /
+// `get_journey_path` (`src/memory/services/journey.py`). `sync_file` is a
+// field inside the "journey" layer identity row's `metadata` JSON — the same
+// metadata object `journeyWrite.ts`'s `journeyMetadata` composes for
+// `project_path`/`icon`/`color`/`parent_journey` — read and written here with
+// its own narrow read-modify-write (Python's `set_sync_file` reads the whole
+// metadata object, sets one key, and writes it back; it does NOT go through
+// the ordered `journeyMetadata` composer).
+
+import { readFileSync } from "node:fs";
+import type { Database, WritableDatabase } from "#db/database.ts";
+import { getIdentityContent, getIdentityMetadata } from "#identity/identityRead.ts";
+import { updateIdentityMetadata } from "#identity/identityStore.ts";
+import { expandHome } from "#util/paths.ts";
+import { JOURNEY_PATH_LAYER } from "./journeyStatus.ts";
+import { JourneyNotFoundError } from "./journeyWrite.ts";
+
+export const JOURNEY_LAYER = "journey";
+
+/**
+ * Port of `get_sync_file`: the configured sync file path for a journey, or
+ * `null` when the journey has no identity row, no metadata, no `sync_file`
+ * key, or the metadata fails to parse (matching Python's
+ * `except (JSONDecodeError, TypeError): return None`).
+ */
+export function getSyncFile(db: Database, journey: string): string | null {
+  const metadataJson = getIdentityMetadata(db, JOURNEY_LAYER, journey);
+  if (!metadataJson) return null;
+  try {
+    const meta = JSON.parse(metadataJson) as Record<string, unknown>;
+    return typeof meta.sync_file === "string" ? meta.sync_file : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Port of `set_sync_file`: read-modify-write the journey's metadata, setting
+ * `sync_file`, preserving every other existing key. Throws `JourneyNotFoundError`
+ * when the journey has no "journey"-layer identity row -- Python's own
+ * `cmd_sync_config` does not catch this ValueError either (an uncaught
+ * exception, exit 1); the front-door route maps it to a clear stderr message
+ * instead of fabricating a fake traceback, the same DS7.US1 `init` precedent.
+ */
+export function setSyncFile(
+  db: WritableDatabase,
+  journey: string,
+  filePath: string,
+  nowIso: string,
+): void {
+  const existingMetadata = getIdentityMetadata(db, JOURNEY_LAYER, journey);
+  const exists =
+    db
+      .prepare("SELECT 1 FROM identity WHERE layer = ? AND key = ? LIMIT 1")
+      .get(JOURNEY_LAYER, journey) !== undefined;
+  if (!exists) {
+    throw new JourneyNotFoundError(journey);
+  }
+  let meta: Record<string, unknown>;
+  try {
+    meta = existingMetadata ? (JSON.parse(existingMetadata) as Record<string, unknown>) : {};
+  } catch {
+    meta = {};
+  }
+  meta.sync_file = filePath;
+  updateIdentityMetadata(db, JOURNEY_LAYER, journey, JSON.stringify(meta), nowIso);
+}
+
+/**
+ * Port of `get_journey_path`: if a sync file is configured, read its EXTERNAL
+ * file content, falling back to the database's `journey_path`-layer content
+ * when the file is absent/unreadable (matching Python's
+ * `except (FileNotFoundError, PermissionError, OSError): pass`).
+ */
+export function getJourneyPath(db: Database, journey: string): string | null {
+  const syncFile = getSyncFile(db, journey);
+  if (syncFile) {
+    try {
+      return readFileSync(expandHome(syncFile), "utf8");
+    } catch {
+      // Fall back to the database.
+    }
+  }
+  return getIdentityContent(db, JOURNEY_PATH_LAYER, journey);
+}