march-cli 0.1.38 → 0.1.40

package/src/cli/workspace/tui-timeline.mjs

@@ -0,0 +1,247 @@
+import { createTuiTimelineProjection } from "./tui-timeline-projection.mjs";
+
+export const DEFAULT_MAX_TIMELINE_EVENTS = 4000;
+export const DEFAULT_TIMELINE_PERSIST_DEBOUNCE_MS = 250;
+
+export function createTuiTimelineRegistry({
+  maxEventsPerTimeline = DEFAULT_MAX_TIMELINE_EVENTS,
+  persistDebounceMs = DEFAULT_TIMELINE_PERSIST_DEBOUNCE_MS,
+  onPersistTimeline = null,
+} = {}) {
+  const timelines = new Map();
+
+  return {
+    ensure(key, { events = null } = {}) {
+      let timeline = timelines.get(key);
+      if (!timeline) {
+        timeline = createTuiTimelineInstance({
+          key,
+          maxEvents: maxEventsPerTimeline,
+          persistDebounceMs,
+          onPersist: onPersistTimeline,
+        });
+        timelines.set(key, timeline);
+      }
+      if (Array.isArray(events)) timeline.hydrateIfEmpty(events);
+      return timeline;
+    },
+    get(key) {
+      return timelines.get(key) ?? null;
+    },
+    has(key) {
+      return timelines.has(key);
+    },
+    clear(key, options) {
+      const timeline = this.ensure(key);
+      timeline.clear(options);
+      return timeline;
+    },
+    flush(key, reason = "manual") {
+      return this.get(key)?.flushPersist(reason) ?? false;
+    },
+    flushAll(reason = "manual") {
+      let flushed = 0;
+      for (const timeline of timelines.values()) {
+        if (timeline.flushPersist(reason)) flushed += 1;
+      }
+      return flushed;
+    },
+    replaceEvents(key, events) {
+      const timeline = this.ensure(key);
+      timeline.replaceEvents(events);
+      return timeline;
+    },
+    getEvents(key) {
+      return this.get(key)?.getEvents() ?? [];
+    },
+    getBlocks(key) {
+      return this.get(key)?.getBlocks() ?? [];
+    },
+    getEventCount(key) {
+      return this.get(key)?.getEventCount() ?? 0;
+    },
+    getMetadata(key) {
+      return this.get(key)?.getMetadata() ?? null;
+    },
+  };
+}
+
+export function createTuiTimelineInstance({
+  key,
+  maxEvents = DEFAULT_MAX_TIMELINE_EVENTS,
+  persistDebounceMs = DEFAULT_TIMELINE_PERSIST_DEBOUNCE_MS,
+  onPersist = null,
+} = {}) {
+  let events = [];
+  const projection = createTuiTimelineProjection();
+  let hydrated = false;
+  let dirty = false;
+  let lastAccessedAt = Date.now();
+  let lastUpdatedAt = null;
+  let lastPersistedAt = null;
+  let estimatedBytes = 0;
+  let persistTimer = null;
+
+  return {
+    key,
+    apply(method, args, { at = Date.now(), persist = true } = {}) {
+      touch();
+      const event = { method, args, at };
+      events.push(event);
+      projection.apply(event);
+      trimToBudget();
+      dirty = true;
+      lastUpdatedAt = at;
+      if (persist) schedulePersist("debounce");
+      return event;
+    },
+    hydrateIfEmpty(nextEvents) {
+      touch();
+      if (events.length > 0) return false;
+      replaceEvents(nextEvents, { markHydrated: true });
+      return true;
+    },
+    replaceEvents(nextEvents) {
+      touch();
+      replaceEvents(nextEvents, { markHydrated: false });
+    },
+    clear({ flush = true } = {}) {
+      touch();
+      events = [];
+      projection.clear();
+      dirty = true;
+      lastUpdatedAt = Date.now();
+      estimatedBytes = 0;
+      if (flush) this.flushPersist("clear");
+      else schedulePersist("debounce");
+    },
+    replayTo(ui) {
+      touch();
+      if (typeof ui.restoreTimelineBlocks === "function") {
+        const blocks = projection.getBlocks();
+        ui.restoreTimelineBlocks(blocks);
+        return blocks.length;
+      }
+      for (const event of events) applyRenderEvent(ui, event);
+      return events.length;
+    },
+    flushPersist(reason = "manual") {
+      clearPersistTimer();
+      if (!dirty || typeof onPersist !== "function") return false;
+      onPersist({ key, events: this.getEvents(), reason, timeline: this.getMetadata() });
+      dirty = false;
+      lastPersistedAt = Date.now();
+      return true;
+    },
+    getEvents() {
+      touch();
+      return cloneEvents(events);
+    },
+    getBlocks() {
+      touch();
+      return projection.getBlocks();
+    },
+    getEventCount() {
+      return events.length;
+    },
+    markPersisted() {
+      clearPersistTimer();
+      dirty = false;
+      lastPersistedAt = Date.now();
+    },
+    getMetadata() {
+      return buildMetadata();
+    },
+  };
+
+  function schedulePersist(reason) {
+    if (typeof onPersist !== "function") return;
+    clearPersistTimer();
+    persistTimer = setTimeout(() => {
+      persistTimer = null;
+      if (!dirty) return;
+      onPersist({ key, events: cloneEvents(events), reason, timeline: buildMetadata() });
+      dirty = false;
+      lastPersistedAt = Date.now();
+    }, Math.max(0, persistDebounceMs));
+    persistTimer.unref?.();
+  }
+
+  function clearPersistTimer() {
+    if (!persistTimer) return;
+    clearTimeout(persistTimer);
+    persistTimer = null;
+  }
+
+  function replaceEvents(nextEvents, { markHydrated }) {
+    clearPersistTimer();
+    events = normalizeTimelineEvents(nextEvents);
+    trimToBudget();
+    rebuildProjection();
+    hydrated = markHydrated;
+    dirty = false;
+    lastUpdatedAt = events.at(-1)?.at ?? null;
+    lastPersistedAt = null;
+    updateEstimatedBytes();
+  }
+
+  function trimToBudget() {
+    if (events.length > maxEvents) {
+      events.splice(0, events.length - maxEvents);
+      rebuildProjection();
+    }
+    updateEstimatedBytes();
+  }
+
+  function rebuildProjection() {
+    projection.rebuild(events);
+  }
+
+  function updateEstimatedBytes() {
+    estimatedBytes = estimateJsonBytes(events) + estimateJsonBytes(projection.getBlocks());
+  }
+
+  function touch() {
+    lastAccessedAt = Date.now();
+  }
+
+  function buildMetadata() {
+    return {
+      key,
+      eventCount: events.length,
+      maxEvents,
+      hydrated,
+      dirty,
+      lastAccessedAt,
+      lastUpdatedAt,
+      lastPersistedAt,
+      estimatedBytes,
+      persistScheduled: Boolean(persistTimer),
+      ...projection.getMetadata(),
+    };
+  }
+}
+
+export function normalizeTimelineEvents(events) {
+  if (!Array.isArray(events)) return [];
+  return events
+    .filter((event) => typeof event?.method === "string" && Array.isArray(event.args))
+    .map((event) => ({ method: event.method, args: event.args, at: event.at ?? null }));
+}
+
+function applyRenderEvent(ui, { method, args }) {
+  const value = ui[method];
+  if (typeof value === "function") value.apply(ui, args);
+}
+
+function cloneEvents(items) {
+  return items.map((event) => ({ method: event.method, args: event.args, at: event.at ?? null }));
+}
+
+function estimateJsonBytes(value) {
+  try {
+    return JSON.stringify(value).length;
+  } catch {
+    return 0;
+  }
+}

package/src/extensions/lifecycle-adapter.mjs

@@ -7,7 +7,7 @@ export const MARCH_LIFECYCLE_LAYERS = Object.freeze([
   {
     name: "march-agent-runtime",
     owner: "March runner",
-    effects: Object.freeze(["read-session-ref", "read-sidecar-metadata", "read-runtime-state"]),
+    effects: Object.freeze(["read-session-ref", "read-session-state", "read-runtime-state"]),
   },
   {
     name: "march-collaboration",
@@ -24,7 +24,7 @@ export const DEFAULT_MARCH_HOOK_POLICY = Object.freeze({
     "read-agent-ref",
     "read-workspace-ref",
     "read-session-ref",
-    "read-sidecar-metadata",
+    "read-session-state",
     "read-diff-metadata",
     "read-runtime-diagnostics",
     "write-diagnostics",

package/src/main.mjs

@@ -1,3 +1,4 @@
+import { createRequire } from "node:module";
 import { homedir } from "node:os";
 import { join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -13,6 +14,8 @@ import { installNetworkEnvironment } from "./network/environment.mjs";
 import { runEarlyCliCommand } from "./cli/startup/early-command.mjs";
 import { maybeRunGatewayDaemonCommand } from "./cli/startup/gateway-daemon-command.mjs";
 
+const { version: packageVersion } = createRequire(import.meta.url)("../package.json");
+
 export async function run(argv) {
   const cwd = process.cwd();
   loadDotEnv(cwd);
@@ -23,6 +26,10 @@ export async function run(argv) {
     showHelp();
     return 0;
   }
+  if (args.version) {
+    process.stdout.write(`${packageVersion}\n`);
+    return 0;
+  }
 
   const config = loadConfig(cwd);
   const stateRoot = join(homedir(), ".march");
@@ -67,7 +74,6 @@ export async function run(argv) {
   }
 
   const dumpContextPath = args.dumpContext ? relative(cwd, app.contextDumpRoot) : null;
-  if (app.startupResume.transcriptTurns?.length > 0) app.ui.restoreTranscript?.(app.startupResume.transcriptTurns);
   for (const line of formatStartupBanner({ cwd, modelId: app.runner.engine.modelId, thinkingLevel: app.runner.engine.thinkingLevel, mode: app.modeState.get(), dumpContextPath })) app.ui.writeln(line);
   try {
     await runInteractiveRepl({

package/src/session/sidecar-sync.mjs

@@ -1,19 +1,5 @@
-import { savePiSessionSidecar } from "./sidecar.mjs";
+import { syncMarchSessionState } from "./state/march-session-sync.mjs";
 
-export function syncPiSessionSidecar({ enabled = false, projectMarchDir, engine, sessionStats, metadata = {} }) {
-  if (!enabled || !projectMarchDir || !sessionStats?.persisted || !sessionStats.sessionFile) {
-    return null;
-  }
-
-  return savePiSessionSidecar({
-    projectMarchDir,
-    sessionRef: sessionStats.sessionFile,
-    engine,
-    metadata: {
-      sessionId: sessionStats.sessionId,
-      sessionFile: sessionStats.sessionFile,
-      runtimeHost: Boolean(sessionStats.runtimeHost),
-      ...metadata,
-    },
-  });
+export function syncPiSessionSidecar(options) {
+  return syncMarchSessionState(options);
 }

package/src/session/sidecar.mjs

@@ -1,69 +1,68 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { basename, join } from "node:path";
+import {
+  captureMarchSessionState,
+  getLegacyPiSidecarDir,
+  getLegacyPiSidecarPath,
+  loadMarchSessionStateForPiBackend,
+  loadLegacyPiSidecar,
+  saveMarchSessionStateValue,
+} from "./state/march-session-state.mjs";
 
 export const PI_SIDECAR_VERSION = 1;
 
 export function getPiSidecarDir(projectMarchDir) {
-  return join(projectMarchDir, "pi-sidecars");
+  return getLegacyPiSidecarDir(projectMarchDir);
 }
 
 export function getPiSidecarPath(projectMarchDir, sessionRef) {
-  return join(getPiSidecarDir(projectMarchDir), `${normalizeSessionRef(sessionRef)}.json`);
+  return getLegacyPiSidecarPath(projectMarchDir, sessionRef);
 }
 
 export function captureContextSidecar(engine, metadata = {}) {
-  return {
-    version: PI_SIDECAR_VERSION,
-    savedAt: new Date().toISOString(),
-    ...metadata,
-    cwd: engine.cwd,
-    modelId: engine.modelId,
-    provider: engine.provider,
-    sessionName: engine.sessionName ?? "",
-    thinkingLevel: engine.thinkingLevel,
-    namespace: engine.namespace,
-    pendingAssistantRecallHints: engine.pendingAssistantRecallHints ?? [],
-    turns: engine.turns,
-  };
+  return captureMarchSessionState(engine, {
+    sessionId: metadata.sessionId,
+    backend: {
+      type: "pi",
+      sessionId: metadata.sessionId ?? null,
+      sessionFile: metadata.sessionFile ?? null,
+      runtimeHost: Boolean(metadata.runtimeHost),
+    },
+    metadata,
+  });
 }
 
 export function savePiSessionSidecar({ projectMarchDir, sessionRef, engine, metadata = {} }) {
   return savePiSessionSidecarState({
     projectMarchDir,
     sessionRef,
-    state: captureContextSidecar(engine, metadata),
+    state: captureContextSidecar(engine, { sessionFile: sessionRef, ...metadata }),
   });
 }
 
 export function savePiSessionSidecarState({ projectMarchDir, sessionRef, state }) {
-  const sidecarDir = getPiSidecarDir(projectMarchDir);
-  mkdirSync(sidecarDir, { recursive: true });
-  validateSidecarState(state);
-  const path = getPiSidecarPath(projectMarchDir, sessionRef);
-  writeFileSync(path, JSON.stringify(state, null, 2), "utf8");
-  return { path, state };
+  return saveMarchSessionStateValue({
+    projectMarchDir,
+    sessionId: state.sessionId ?? state.backend?.sessionId ?? state.sessionFile ?? sessionRef,
+    state: normalizeLegacyState(state, sessionRef),
+  });
 }
 
 export function loadPiSessionSidecar({ projectMarchDir, sessionRef }) {
-  const path = getPiSidecarPath(projectMarchDir, sessionRef);
-  if (!existsSync(path)) return null;
-  const state = JSON.parse(readFileSync(path, "utf8"));
-  if (!isValidSidecarState(state)) {
-    throw new Error("Invalid pi session sidecar");
-  }
-  return { path, state };
+  return loadMarchSessionStateForPiBackend({ projectMarchDir, sessionId: null, sessionRef }) ?? loadLegacyPiSidecar({ projectMarchDir, sessionRef });
 }
 
-function validateSidecarState(state) {
-  if (!isValidSidecarState(state)) throw new Error("Invalid pi session sidecar");
+export function loadPiSessionContextState({ projectMarchDir, sessionRef, sessionId = null }) {
+  return loadMarchSessionStateForPiBackend({ projectMarchDir, sessionId, sessionRef });
 }
 
-function isValidSidecarState(state) {
-  return state?.version === PI_SIDECAR_VERSION && Boolean(state.cwd) && Array.isArray(state.turns);
-}
-
-function normalizeSessionRef(sessionRef) {
-  const ref = basename(String(sessionRef).trim()).replace(/\.jsonl$/i, "");
-  if (!ref || ref === "." || ref === "..") throw new Error("Invalid pi session reference");
-  return ref.replace(/[^a-zA-Z0-9._-]/g, "_");
+function normalizeLegacyState(state, sessionRef) {
+  return {
+    ...state,
+    sessionId: state.sessionId ?? state.backend?.sessionId ?? state.sessionFile ?? sessionRef,
+    backend: state.backend ?? {
+      type: "pi",
+      sessionId: state.sessionId ?? null,
+      sessionFile: state.sessionFile ?? sessionRef,
+      runtimeHost: Boolean(state.runtimeHost),
+    },
+  };
 }

package/src/session/state/march-session-state.mjs

@@ -0,0 +1,165 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { loadPiSessionTranscriptTurns } from "../transcript.mjs";
+
+export const MARCH_SESSION_STATE_VERSION = 1;
+
+export function getMarchSessionStateRoot(projectMarchDir) {
+  return join(projectMarchDir, "sessions");
+}
+
+export function getMarchSessionStateDir(projectMarchDir, sessionId) {
+  return join(getMarchSessionStateRoot(projectMarchDir), normalizeSessionId(sessionId));
+}
+
+export function getMarchSessionStatePath(projectMarchDir, sessionId) {
+  return join(getMarchSessionStateDir(projectMarchDir, sessionId), "state.json");
+}
+
+export function captureMarchSessionState(engine, { sessionId, backend = null, metadata = {} } = {}) {
+  return {
+    version: MARCH_SESSION_STATE_VERSION,
+    savedAt: new Date().toISOString(),
+    sessionId: sessionId ?? metadata.sessionId ?? backend?.sessionId ?? null,
+    backend,
+    ...metadata,
+    cwd: engine.cwd,
+    modelId: engine.modelId,
+    provider: engine.provider,
+    sessionName: engine.sessionName ?? "",
+    thinkingLevel: engine.thinkingLevel,
+    namespace: engine.namespace,
+    pendingAssistantRecallHints: engine.pendingAssistantRecallHints ?? [],
+    turns: engine.turns,
+  };
+}
+
+export function saveMarchSessionState({ projectMarchDir, sessionId, engine, backend = null, metadata = {} }) {
+  return saveMarchSessionStateValue({
+    projectMarchDir,
+    sessionId,
+    state: captureMarchSessionState(engine, { sessionId, backend, metadata }),
+  });
+}
+
+export function saveMarchSessionStateValue({ projectMarchDir, sessionId, state }) {
+  if (!sessionId) throw new Error("March session id is required");
+  const existing = loadMarchSessionState({ projectMarchDir, sessionId })?.state ?? null;
+  const nextState = normalizeMarchSessionStateForSave({ ...existing, ...state });
+  validateMarchSessionState(nextState);
+  const dir = getMarchSessionStateDir(projectMarchDir, sessionId);
+  mkdirSync(dir, { recursive: true });
+  const path = getMarchSessionStatePath(projectMarchDir, sessionId);
+  writeFileSync(path, JSON.stringify({ ...nextState, sessionId: nextState.sessionId ?? sessionId }, null, 2), "utf8");
+  return { path, state: { ...nextState, sessionId: nextState.sessionId ?? sessionId } };
+}
+
+export function loadMarchSessionState({ projectMarchDir, sessionId }) {
+  const path = getMarchSessionStatePath(projectMarchDir, sessionId);
+  if (!existsSync(path)) return null;
+  const state = normalizeMarchSessionStateForSave(JSON.parse(readFileSync(path, "utf8")));
+  if (!isValidMarchSessionState(state)) throw new Error("Invalid March session state");
+  return { path, state };
+}
+
+export function loadMarchSessionContextState({ projectMarchDir, sessionId, backendSessionFile = null }) {
+  const stored = loadMarchSessionState({ projectMarchDir, sessionId });
+  if (!stored) return null;
+  const sessionFile = backendSessionFile ?? stored.state.backend?.sessionFile ?? stored.state.sessionFile ?? null;
+  return { ...stored, state: withBackendTranscriptTurns(stored.state, sessionFile) };
+}
+
+export function listMarchSessionStates({ projectMarchDir }) {
+  const root = getMarchSessionStateRoot(projectMarchDir);
+  if (!existsSync(root)) return [];
+  return readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => {
+      try {
+        return loadMarchSessionState({ projectMarchDir, sessionId: entry.name });
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+export function loadMarchSessionStateForPiBackend({ projectMarchDir, sessionId, sessionRef }) {
+  const marchState = sessionId ? loadMarchSessionContextState({ projectMarchDir, sessionId, backendSessionFile: sessionRef }) : null;
+  if (marchState) return marchState;
+  const matchingState = findMarchSessionStateByPiBackend({ projectMarchDir, sessionRef });
+  if (matchingState) return { ...matchingState, state: withBackendTranscriptTurns(matchingState.state, sessionRef) };
+  return loadLegacyPiSidecarContextState({ projectMarchDir, sessionRef });
+}
+
+function findMarchSessionStateByPiBackend({ projectMarchDir, sessionRef }) {
+  const normalizedRef = normalizeSessionRef(sessionRef);
+  return listMarchSessionStates({ projectMarchDir }).find(({ state }) => {
+    const sessionFile = state.backend?.sessionFile ?? state.sessionFile ?? null;
+    return sessionFile && normalizeSessionRef(sessionFile) === normalizedRef;
+  }) ?? null;
+}
+
+export function getLegacyPiSidecarDir(projectMarchDir) {
+  return join(projectMarchDir, "pi-sidecars");
+}
+
+export function getLegacyPiSidecarPath(projectMarchDir, sessionRef) {
+  return join(getLegacyPiSidecarDir(projectMarchDir), `${normalizeSessionRef(sessionRef)}.json`);
+}
+
+export function loadLegacyPiSidecar({ projectMarchDir, sessionRef }) {
+  const path = getLegacyPiSidecarPath(projectMarchDir, sessionRef);
+  if (!existsSync(path)) return null;
+  const state = normalizeMarchSessionStateForSave(JSON.parse(readFileSync(path, "utf8")));
+  if (!isValidMarchSessionState(state)) throw new Error("Invalid March session state");
+  return { path, state };
+}
+
+export function loadLegacyPiSidecarContextState({ projectMarchDir, sessionRef }) {
+  const legacy = loadLegacyPiSidecar({ projectMarchDir, sessionRef });
+  if (!legacy) return null;
+  return { ...legacy, state: withBackendTranscriptTurns(legacy.state, sessionRef) };
+}
+
+export function normalizeSessionId(sessionId) {
+  const value = String(sessionId ?? "").trim();
+  if (!value || value === "." || value === "..") throw new Error("Invalid March session id");
+  return value.replace(/[^a-zA-Z0-9._-]/g, "_");
+}
+
+function validateMarchSessionState(state) {
+  if (!isValidMarchSessionState(state)) throw new Error("Invalid March session state");
+}
+
+function isValidMarchSessionState(state) {
+  return state?.version === MARCH_SESSION_STATE_VERSION
+    && Boolean(state.cwd)
+    && Array.isArray(state.turns);
+}
+
+function normalizeMarchSessionStateForSave(state) {
+  const { renderTimeline: _renderTimeline, renderTimelineUpdatedAt: _renderTimelineUpdatedAt, ...coreState } = state ?? {};
+  return coreState;
+}
+
+function normalizeSessionRef(sessionRef) {
+  const ref = basename(String(sessionRef).trim()).replace(/\.jsonl$/i, "");
+  if (!ref || ref === "." || ref === "..") throw new Error("Invalid pi session reference");
+  return ref.replace(/[^a-zA-Z0-9._-]/g, "_");
+}
+
+function withBackendTranscriptTurns(state, sessionFile) {
+  if (!sessionFile) return { ...state };
+  let transcriptTurns = [];
+  try {
+    transcriptTurns = loadPiSessionTranscriptTurns(sessionFile);
+  } catch {
+    return { ...state };
+  }
+  if (transcriptTurns.length <= (state.turns?.length ?? 0)) return { ...state };
+  return {
+    ...state,
+    turns: transcriptTurns,
+  };
+}

package/src/session/state/march-session-sync.mjs

@@ -0,0 +1,20 @@
+import { saveMarchSessionState } from "./march-session-state.mjs";
+
+export function syncMarchSessionState({ enabled = false, projectMarchDir, engine, sessionStats, metadata = {} }) {
+  if (!enabled || !projectMarchDir || !sessionStats?.persisted || !sessionStats.sessionId) {
+    return null;
+  }
+
+  return saveMarchSessionState({
+    projectMarchDir,
+    sessionId: sessionStats.sessionId,
+    engine,
+    backend: {
+      type: "pi",
+      sessionId: sessionStats.sessionId,
+      sessionFile: sessionStats.sessionFile ?? null,
+      runtimeHost: Boolean(sessionStats.runtimeHost),
+    },
+    metadata,
+  });
+}