mirror-mind 0.0.1 → 0.32.1

package/ts/src/soul/state.ts

@@ -0,0 +1,212 @@
+// CV22.DS7.US6 plateau 2 — Soul Mode provisional session state, ported from
+// `src/memory/services/soul.py`.
+//
+// The ritual's fruit lives in `runtime_sessions.metadata`, a JSON TEXT column
+// both cores read and write while the strangler runs, so the contract graded by
+// `soul-state.golden.json` is the column's exact BYTES:
+//
+//   * Python serializes with `json.dumps(..., ensure_ascii=False)`, whose
+//     separators are `", "` and `": "`. `JSON.stringify` writes neither, so
+//     every write here goes through `pythonJsonDumps`.
+//   * Clearing the last soul key writes SQL NULL, not `"{}"`.
+//   * Clearing against a MISSING session row writes nothing at all -- it must
+//     not create the row on the way past.
+//   * `harvestFruit` with no argument promotes the maturation fruit and deletes
+//     it in the same write; both keys are never present afterwards.
+//
+// Known limit, inherited and not introduced here: JavaScript objects reorder
+// integer-like keys ahead of string keys, while Python dicts preserve insertion
+// order for all of them. Mirror's own metadata keys (`soul`, `operating_mode`)
+// are unaffected; a column carrying a numeric top-level key -- only reachable
+// through corruption or a foreign writer -- would round-trip in a different
+// order than Python's. Reproducing that would require an order-preserving JSON
+// model across the whole port, which is not this story's scope.
+
+import type { Database, WritableDatabase } from "#db/database.ts";
+import {
+  decodeMetadata,
+  getRuntimeSession,
+  resolveRuntimeSessionId,
+  upsertRuntimeSession,
+} from "#mirror/runtimeSession.ts";
+import { pythonJsonDumps } from "#util/pyGenerators.ts";
+import { pyStrip } from "#util/pythonText.ts";
+
+export const SOUL_STATE_SESSION_ID = "__global_soul_mode__";
+export const SOUL_METADATA_KEY = "soul";
+export const FRUIT_METADATA_KEY = "fruit_in_maturation";
+export const HARVEST_METADATA_KEY = "harvested_fruit";
+
+export interface SoulFruitState {
+  sessionId: string;
+  fruit: string | null;
+}
+
+/**
+ * Port of `resolve_soul_session_id`: explicit (stripped) → `MIRROR_SESSION_ID`
+ * (stripped) → the global Soul constant. Always returns an id.
+ */
+export function resolveSoulSessionId(
+  explicitSessionId: string | null = null,
+  environmentSessionId: string | null = null,
+): string {
+  const explicit = pyStrip(explicitSessionId ?? "");
+  if (explicit) return explicit;
+  return pyStrip(environmentSessionId ?? "") || SOUL_STATE_SESSION_ID;
+}
+
+/**
+ * Port of `_resolve_cli_soul_session_id`: the operating-mode resolver first,
+ * the Soul resolver as the fallback.
+ *
+ * The two disagree on purpose and the golden pins it. The operating-mode
+ * resolver returns an explicit id VERBATIM, so `--session-id "  "` resolves to
+ * `"  "`, while the Soul resolver would have stripped it to the global
+ * constant. Composing them the other way round would silently retarget a
+ * session.
+ */
+export function resolveCliSoulSessionId(
+  db: Database,
+  explicitSessionId: string | null = null,
+  environmentSessionId: string | null = null,
+): string {
+  return (
+    resolveRuntimeSessionId(db, explicitSessionId, environmentSessionId) ??
+    resolveSoulSessionId(explicitSessionId, environmentSessionId)
+  );
+}
+
+export function getFruitInMaturation(
+  db: Database,
+  sessionId: string | null = null,
+): SoulFruitState {
+  return readSoulKey(db, FRUIT_METADATA_KEY, sessionId);
+}
+
+export function getHarvestedFruit(db: Database, sessionId: string | null = null): SoulFruitState {
+  return readSoulKey(db, HARVEST_METADATA_KEY, sessionId);
+}
+
+function readSoulKey(db: Database, key: string, sessionId: string | null): SoulFruitState {
+  const resolvedSessionId = resolveSoulSessionId(sessionId);
+  const session = getRuntimeSession(db, resolvedSessionId);
+  const soul = decodeMetadata(session?.metadata ?? null)[SOUL_METADATA_KEY];
+  const value = isRecord(soul) ? soul[key] : undefined;
+  const fruit = typeof value === "string" && pyStrip(value) ? pyStrip(value) : null;
+  return { sessionId: resolvedSessionId, fruit };
+}
+
+export function setFruitInMaturation(
+  db: WritableDatabase,
+  fruit: string,
+  sessionId: string | null,
+  nowIso: string,
+): SoulFruitState {
+  const normalizedFruit = pyStrip(fruit);
+  if (!normalizedFruit) throw new SoulStateError("fruit must not be empty");
+
+  const resolvedSessionId = resolveSoulSessionId(sessionId);
+  const metadata = readMetadata(db, resolvedSessionId);
+  const soul = soulObject(metadata);
+  soul[FRUIT_METADATA_KEY] = normalizedFruit;
+  metadata[SOUL_METADATA_KEY] = soul;
+  upsertRuntimeSession(
+    db,
+    resolvedSessionId,
+    { metadata: pythonJsonDumps(metadata), active: true },
+    nowIso,
+  );
+  return { sessionId: resolvedSessionId, fruit: normalizedFruit };
+}
+
+export function harvestFruit(
+  db: WritableDatabase,
+  input: { fruit?: string | null; sessionId?: string | null },
+  nowIso: string,
+): SoulFruitState {
+  const resolvedSessionId = resolveSoulSessionId(input.sessionId ?? null);
+  let finalFruit =
+    typeof input.fruit === "string" && pyStrip(input.fruit) ? pyStrip(input.fruit) : null;
+  if (finalFruit === null) {
+    finalFruit = getFruitInMaturation(db, resolvedSessionId).fruit;
+  }
+  if (!finalFruit) throw new SoulStateError("harvested fruit must not be empty");
+
+  const metadata = readMetadata(db, resolvedSessionId);
+  const soul = soulObject(metadata);
+  soul[HARVEST_METADATA_KEY] = finalFruit;
+  delete soul[FRUIT_METADATA_KEY];
+  metadata[SOUL_METADATA_KEY] = soul;
+  upsertRuntimeSession(
+    db,
+    resolvedSessionId,
+    { metadata: pythonJsonDumps(metadata), active: true },
+    nowIso,
+  );
+  return { sessionId: resolvedSessionId, fruit: finalFruit };
+}
+
+export function clearFruitInMaturation(
+  db: WritableDatabase,
+  sessionId: string | null,
+  nowIso: string,
+): void {
+  clearSoulKey(db, FRUIT_METADATA_KEY, sessionId, nowIso);
+}
+
+export function clearHarvestedFruit(
+  db: WritableDatabase,
+  sessionId: string | null,
+  nowIso: string,
+): void {
+  clearSoulKey(db, HARVEST_METADATA_KEY, sessionId, nowIso);
+}
+
+/** Port of `_clear_soul_key`, including its two silences. */
+function clearSoulKey(
+  db: WritableDatabase,
+  key: string,
+  sessionId: string | null,
+  nowIso: string,
+): void {
+  const resolvedSessionId = resolveSoulSessionId(sessionId);
+  const session = getRuntimeSession(db, resolvedSessionId);
+  // No row: Python returns before touching the database, so clearing a fruit
+  // that was never set must not conjure a session row.
+  if (!session) return;
+
+  const metadata = decodeMetadata(session.metadata);
+  const soul = metadata[SOUL_METADATA_KEY];
+  if (isRecord(soul)) {
+    delete soul[key];
+    if (Object.keys(soul).length > 0) {
+      metadata[SOUL_METADATA_KEY] = soul;
+    } else {
+      delete metadata[SOUL_METADATA_KEY];
+    }
+  }
+  upsertRuntimeSession(
+    db,
+    resolvedSessionId,
+    { metadata: Object.keys(metadata).length > 0 ? pythonJsonDumps(metadata) : null },
+    nowIso,
+  );
+}
+
+function readMetadata(db: Database, sessionId: string): Record<string, unknown> {
+  const session = getRuntimeSession(db, sessionId);
+  return decodeMetadata(session?.metadata ?? null);
+}
+
+/** Python replaces a non-dict `soul` value with a fresh dict rather than raising. */
+function soulObject(metadata: Record<string, unknown>): Record<string, unknown> {
+  const existing = metadata[SOUL_METADATA_KEY];
+  return isRecord(existing) ? existing : {};
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Python raises `ValueError`; the CLI renders it as `Error: <message>`. */
+export class SoulStateError extends Error {}

package/ts/src/soul/transition.ts

@@ -0,0 +1,37 @@
+// CV22.DS7.US6 plateau 6 — the Soul Mode entry card, ported from
+// `render_soul_mode_transition` (`src/memory/surfaces/mode_transition.py`).
+//
+// A different module and a different WIDTH (56, against the 40 of the ritual
+// cards in `render.ts`), but the same transport=verbatim contract.
+//
+// The card is CONSTANT: the oracle accepts `journey` and immediately discards
+// it — "Soul Mode entry keeps journey context in state, not in the ritual card"
+// — so the journey reaches the operating-mode row and the sticky defaults, and
+// never the rendered surface. The golden records both call shapes so that
+// property is pinned rather than assumed.
+
+const WIDTH = 56;
+
+function line(text: string): string {
+  return `│${text.padEnd(WIDTH)}│`;
+}
+
+const CARD = [
+  "Mirror",
+  `╭${"─".repeat(WIDTH)}╮`,
+  line("        ☾  SOUL MODE ACTIVE"),
+  line(""),
+  line("  Soul Mode turns the day toward the inner life."),
+  line(""),
+  line("  ✦  IN ORDER TO"),
+  line("  remember who you are"),
+  line(""),
+  line("  ▹  START BY ANSWERING"),
+  line("  how is your day going today?"),
+  `╰${"─".repeat(WIDTH)}╯`,
+].join("\n");
+
+/** Port of `render_soul_mode_transition`. The journey never reaches the card. */
+export function renderSoulModeTransition(_journey?: string | null): string {
+  return CARD;
+}

package/ts/src/tasks/journeyPathParse.ts

@@ -0,0 +1,113 @@
+// Journey-path task parser parity port (CV22.DS7.US2).
+//
+// A faithful TypeScript port of Python `parse_journey_path_tasks` /
+// `parse_done_tasks` (`src/memory/cli/tasks.py`). Both functions are pure over
+// a markdown string — no database involved — and are used by both `tasks
+// import` and `tasks sync`, so this is the **one shared** parser both callers
+// use (the `kebab_slug` writer/locator lesson: do not let two callers grow two
+// slightly-different copies of the same regex logic).
+//
+// Kept as one module with two exported functions, mirroring the Python file,
+// because the two parsers share the same stage-tracking state machine and are
+// always read together.
+
+/** One parsed task payload, matching the Python dict shape exactly. */
+export interface ParsedTask {
+  title: string;
+  stage: string | null;
+  status: "todo" | "done";
+  journey: string;
+}
+
+const STAGE_HEADER_RE = /^###\s+(?:Etapa\s+\d+:\s*)?(.+?)(?:\s*[✅🚧⏸])?$/u;
+const CYCLE_HEADER_RE = /^\*\*(.+?)(?:\s*[✅🚧⏸])?\s*:?\*\*/u;
+const UNCHECKED_BOX_RE = /^\s*-\s*\[\s*\]\s+(.+)/;
+const CHECKED_BOX_RE = /^\s*-\s*\[x\]\s+(.+)/i;
+const BOLD_RE = /\*\*(.+?)\*\*/g;
+
+/** Strip Markdown bold markers and a single trailing period from a title. */
+function cleanTitle(raw: string): string {
+  const unbolded = raw.trim().replace(BOLD_RE, "$1");
+  return unbolded.replace(/\.+$/, "");
+}
+
+/**
+ * Extract pending tasks from unchecked journey-path checkboxes.
+ *
+ * Reproduces Python `parse_journey_path_tasks`, including the legacy
+ * bold-cycle-header branch: a `**...✅**` line resets the current stage to
+ * `null` (skipping tasks under it) while a `**...**` line without `✅` is a
+ * no-op when a stage is already active. A `###` header carrying `✅` also
+ * resets the stage to `null` so a completed stage's checkboxes are skipped.
+ */
+export function parseJourneyPathTasks(journeyPath: string, journey: string): ParsedTask[] {
+  const tasks: ParsedTask[] = [];
+  let currentStage: string | null = null;
+
+  for (const rawLine of journeyPath.split("\n")) {
+    const line = rawLine.trim();
+
+    const stageMatch = STAGE_HEADER_RE.exec(line);
+    if (stageMatch) {
+      if (rawLine.includes("✅")) {
+        currentStage = null;
+        continue;
+      }
+      currentStage = stageMatch[1].trim();
+    }
+
+    const cycleMatch = CYCLE_HEADER_RE.exec(line);
+    if (cycleMatch && rawLine.includes("✅")) {
+      currentStage = null;
+      continue;
+    }
+    // else if cycleMatch && currentStage === null: no-op in Python (`pass`) —
+    // nothing to do here either.
+
+    const checkboxMatch = UNCHECKED_BOX_RE.exec(rawLine);
+    if (checkboxMatch && currentStage !== null) {
+      tasks.push({
+        title: cleanTitle(checkboxMatch[1]),
+        stage: currentStage,
+        status: "todo",
+        journey,
+      });
+    }
+  }
+
+  return tasks;
+}
+
+/**
+ * Extract completed tasks from checked journey-path checkboxes.
+ *
+ * Reproduces Python `parse_done_tasks`: unlike the pending parser, a stage
+ * header never resets `currentStage` to `null` on `✅` (there is no
+ * "completed stage" skip for already-done tasks), and every checked box is
+ * appended regardless of whether a stage has been seen yet.
+ */
+export function parseDoneTasks(journeyPath: string, journey: string): ParsedTask[] {
+  const tasks: ParsedTask[] = [];
+  let currentStage: string | null = null;
+
+  for (const rawLine of journeyPath.split("\n")) {
+    const line = rawLine.trim();
+
+    const stageMatch = STAGE_HEADER_RE.exec(line);
+    if (stageMatch) {
+      currentStage = stageMatch[1].trim();
+    }
+
+    const checkboxMatch = CHECKED_BOX_RE.exec(rawLine);
+    if (checkboxMatch) {
+      tasks.push({
+        title: cleanTitle(checkboxMatch[1]),
+        stage: currentStage,
+        status: "done",
+        journey,
+      });
+    }
+  }
+
+  return tasks;
+}

package/ts/src/tasks/taskImportSync.ts

@@ -0,0 +1,142 @@
+// `tasks import` / `tasks sync` orchestration parity port (CV22.DS7.US2 slice
+// 3c). A faithful port of `TaskService.import_tasks_from_journey_path` /
+// `sync_tasks_from_file` (`src/memory/services/tasks.py`), which read a
+// journey's path/reference file, parse it with the shared
+// `journeyPathParse.ts` parser, and create/complete tasks accordingly.
+//
+// Both functions generate a fresh id/now PER created row (not one injected
+// value for the whole call) -- matching `runSeed`'s established pattern for
+// multi-row writes, since either function can create zero, one, or many
+// tasks in a single invocation.
+
+import { readFileSync } from "node:fs";
+import type { WritableDatabase } from "#db/database.ts";
+import { getJourneyPath, getSyncFile } from "#journey/journeySyncFile.ts";
+import { expandHome } from "#util/paths.ts";
+import { newId, nowIso } from "#util/pyGenerators.ts";
+import { parseDoneTasks, parseJourneyPathTasks } from "./journeyPathParse.ts";
+import {
+  completeTask,
+  createTask,
+  findTasksByTitle,
+  getTasksByJourney,
+  type Task,
+} from "./taskStore.ts";
+
+/**
+ * Port of `import_tasks_from_journey_path`: read the journey's path (external
+ * sync file if configured, else the DB `journey_path` layer), parse pending
+ * checkboxes, and create a task for each title not already present for this
+ * journey. Dedup uses the SAME `LIKE %title%` fragment match `findTasksByTitle`
+ * already ports -- a deliberate, pre-existing Python characteristic (a
+ * substring match, not an exact one), not something to tighten here.
+ */
+export function importTasksFromJourneyPath(db: WritableDatabase, journey: string): Task[] {
+  const journeyPath = getJourneyPath(db, journey);
+  if (!journeyPath) return [];
+
+  const parsed = parseJourneyPathTasks(journeyPath, journey);
+  const created: Task[] = [];
+  for (const item of parsed) {
+    const existing = findTasksByTitle(db, item.title, journey);
+    if (existing.length > 0) continue;
+    const task = createTask(
+      db,
+      { title: item.title, journey, stage: item.stage, source: "journey_path" },
+      newId(),
+      nowIso(),
+    );
+    created.push(task);
+  }
+  return created;
+}
+
+/** Raised when a journey has no sync file configured (`sync_tasks_from_file`'s `ValueError`). */
+export class NoSyncFileConfiguredError extends Error {
+  readonly journey: string;
+  constructor(journey: string) {
+    super(
+      `No sync file configured for '${journey}'. Use: mm:tasks sync-config ${journey} /path/to/file`,
+    );
+    this.journey = journey;
+  }
+}
+
+/** Raised when the configured sync file does not exist on disk. */
+export class SyncFileNotFoundError extends Error {
+  readonly syncFile: string;
+  constructor(syncFile: string) {
+    super(`File not found: ${syncFile}`);
+    this.syncFile = syncFile;
+  }
+}
+
+export interface SyncResult {
+  created: number;
+  completed: number;
+  unchanged: number;
+}
+
+/**
+ * Port of `sync_tasks_from_file`: read the configured external file, parse
+ * BOTH pending and done checkboxes, and reconcile against a SNAPSHOT of the
+ * journey's existing tasks (by title) taken ONCE before either loop runs --
+ * matching Python's single dict comprehension exactly. A task created by the
+ * pending loop is deliberately invisible to the done loop in the SAME call
+ * (this is Python's real behavior, not a bug to fix): if a title later marked
+ * done wasn't already a known task before this sync ran, it is silently
+ * skipped, never created from the done list alone.
+ */
+export function syncTasksFromFile(db: WritableDatabase, journey: string): SyncResult {
+  const syncFile = getSyncFile(db, journey);
+  if (!syncFile) {
+    throw new NoSyncFileConfiguredError(journey);
+  }
+
+  const expandedPath = expandHome(syncFile);
+  let content: string;
+  try {
+    content = readFileSync(expandedPath, "utf8");
+  } catch {
+    throw new SyncFileNotFoundError(syncFile);
+  }
+
+  const filePending = parseJourneyPathTasks(content, journey);
+  const fileDone = parseDoneTasks(content, journey);
+
+  // Last-title-wins, in get_tasks_by_journey's own order -- matches Python's
+  // `{t.title: t for t in existing_tasks}` dict-comprehension semantics.
+  const existingByTitle = new Map<string, Task>();
+  for (const t of getTasksByJourney(db, journey)) {
+    existingByTitle.set(t.title, t);
+  }
+
+  const result: SyncResult = { created: 0, completed: 0, unchanged: 0 };
+
+  for (const item of filePending) {
+    if (!existingByTitle.has(item.title)) {
+      createTask(
+        db,
+        { title: item.title, journey, stage: item.stage, source: "sync" },
+        newId(),
+        nowIso(),
+      );
+      result.created += 1;
+    } else {
+      result.unchanged += 1;
+    }
+  }
+
+  for (const item of fileDone) {
+    const existing = existingByTitle.get(item.title);
+    if (!existing) continue; // done items never create a task on their own.
+    if (existing.status !== "done") {
+      completeTask(db, existing.id, nowIso());
+      result.completed += 1;
+    } else {
+      result.unchanged += 1;
+    }
+  }
+
+  return result;
+}