@visual-z/xeno 0.1.0

package/src/store/sessions.ts

@@ -0,0 +1,463 @@
+/**
+ * Many sessions under one project.
+ *
+ * A workspace used to hold a single log at `.xeno/log`. That made `/new`,
+ * `/resume`, `/name` and the rest unimplementable: there was nothing to
+ * list, name, or pick. Each session is now its own log tree under
+ * `.xeno/sessions/<id>/`, and the blob store stays at `.xeno/blobs` --
+ * content-addressed bytes are the same bytes no matter which session
+ * snapshotted them, and splitting the store would throw the dedup away
+ * without buying any isolation.
+ *
+ * There is no index file. An index is a second source of truth and will
+ * disagree with the directories; this project's whole position is that the
+ * log is the only truth, and a session list that can lie is the same class
+ * of error as a handoff that can lie. Listing is a scan. The cost is one
+ * small read per session, capped, which is the point of the cap.
+ *
+ * Why the id has a random suffix, not just a timestamp: two sessions
+ * created in the same millisecond would otherwise share a directory, and
+ * the second write would land in the first session's tree. That is the
+ * same collision shape that once had two node allocators agree on id 1
+ * and silently truncate a log.
+ */
+
+import { cp, mkdir, mkdtemp, open, readdir, rename, rm, stat } from "node:fs/promises";
+import type { Dirent } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import {
+  digestNode,
+  listNodes,
+  nodePath,
+  initNode,
+  readManifest,
+  readCursor,
+  readNode,
+  writeCursor,
+  type Manifest,
+} from "./log.ts";
+import { readNodeHistory } from "./restore.ts";
+import { replayContext } from "./replay.ts";
+import { recoverCut } from "./recovery.ts";
+
+/**
+ * A listing that reads every session ever is unbounded. Two hundred is
+ * enough to find the one you were in last week; beyond that the scan would
+ * be hiding a missing search feature, not serving one. Assumed, not
+ * measured: this is a product cap, not a performance number. The rest stay
+ * on disk -- the listing says it truncated, so they are not silent.
+ */
+export const MAX_SESSION_LIST = 200;
+
+/**
+ * Exclusive-create retries when the id is already on disk.
+ *
+ * The suffix space is 36^4 (about 1.7 million). A collision is a bug in
+ * the clock -- same millisecond AND same random -- not a thing we wait
+ * out. Four tries then refuse, rather than loop.
+ */
+const MAX_ID_ATTEMPTS = 4;
+
+const SUFFIX_SPAN = 36 ** 4;
+
+export interface SessionIdClock {
+  nowMs: () => number;
+  /** In [0, 1), same range as Math.random. */
+  random: () => number;
+}
+
+export type ListedSession =
+  | {
+      ok: true;
+      id: string;
+      name: string | null;
+      model: string | null;
+      node: number | null;
+      events: number;
+      updated_at: string | null;
+      path: string;
+    }
+  | {
+      ok: false;
+      id: string;
+      path: string;
+      error: string;
+    };
+
+export interface SessionList {
+  sessions: ListedSession[];
+  /** Session directories not read because the listing cap was hit. */
+  truncated: number;
+}
+
+const systemIdClock: SessionIdClock = {
+  nowMs: () => Date.now(),
+  random: () => Math.random(),
+};
+
+export function sessionsDir(workspace: string, override?: string): string {
+  if (override !== undefined && override.length > 0) {
+    return isAbsolute(override) ? override : join(workspace, override);
+  }
+  return join(workspace, ".xeno", "sessions");
+}
+
+export function legacyLogDir(workspace: string): string {
+  return join(workspace, ".xeno", "log");
+}
+
+/**
+ * `<base36 ms>-<4 digit base36 random>`.
+ *
+ * Time first so ids sort by creation. The suffix is what makes two calls
+ * in the same millisecond distinct; without it the second session is the
+ * first session's directory.
+ */
+export function formatSessionId(ms: number, random: number): string {
+  const n = Math.min(SUFFIX_SPAN - 1, Math.max(0, Math.floor(random * SUFFIX_SPAN)));
+  return `${ms.toString(36)}-${n.toString(36).padStart(4, "0")}`;
+}
+
+export function truncationNote(truncated: number): string | null {
+  if (truncated <= 0) return null;
+  const noun = truncated === 1 ? "session" : "sessions";
+  return `listing capped at ${MAX_SESSION_LIST}; ${truncated} older ${noun} not shown`;
+}
+
+export async function createSession(
+  workspace: string,
+  clock: SessionIdClock = systemIdClock,
+  sessionDir?: string,
+): Promise<{ id: string; path: string }> {
+  const dir = sessionsDir(workspace, sessionDir);
+  await mkdir(dir, { recursive: true });
+  for (let attempt = 0; attempt < MAX_ID_ATTEMPTS; attempt++) {
+    const id = formatSessionId(clock.nowMs(), clock.random());
+    const path = join(dir, id);
+    try {
+      // Exclusive. recursive would succeed on an existing directory and the
+      // second session would write into the first -- the collision this
+      // suffix exists to make unrepresentable.
+      await mkdir(path);
+      return { id, path };
+    } catch (err) {
+      if ((err as { code?: string }).code !== "EEXIST") throw err;
+    }
+  }
+  throw new Error(
+    `could not allocate a unique session id under ${dir} after ${MAX_ID_ATTEMPTS} attempts`,
+  );
+}
+
+export async function listSessions(workspace: string, sessionDir?: string): Promise<SessionList> {
+  const dir = sessionsDir(workspace, sessionDir);
+  let entries: Dirent[];
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch (err) {
+    if ((err as { code?: string }).code === "ENOENT") return { sessions: [], truncated: 0 };
+    throw err;
+  }
+
+  const dirs = entries.filter((e) => e.isDirectory());
+  const withMtime = await Promise.all(
+    dirs.map(async (d) => {
+      const path = join(dir, d.name);
+      const st = await stat(path);
+      return { id: d.name, path, mtime: st.mtimeMs };
+    }),
+  );
+  // The cap is "which 200 do we even open", and mtime is the cheap proxy
+  // for "likely recent". After that, the list is ordered by what each
+  // session recorded: a backup restore can make an old session the
+  // newest directory on disk, and that must not hide the one that ran last.
+  withMtime.sort((a, b) => b.mtime - a.mtime);
+  const truncated = Math.max(0, withMtime.length - MAX_SESSION_LIST);
+  const chosen = withMtime.slice(0, MAX_SESSION_LIST);
+
+  const sessions: ListedSession[] = [];
+  for (const d of chosen) {
+    sessions.push(await readListed(d.id, d.path));
+  }
+  sessions.sort(byRecordedTime);
+  return { sessions, truncated };
+}
+
+/**
+ * A leftover `.xeno/log` is not migrated. Moving someone else's data cannot
+ * be a startup side effect; the person keeps using it by pointing `--log`
+ * at it. Once `.xeno/sessions/` exists they are already in the new layout
+ * and the leftover is just leftover, so the notice stays quiet.
+ */
+export async function legacyLogNotice(workspace: string): Promise<string | null> {
+  if (!(await isDirectory(legacyLogDir(workspace)))) return null;
+  if (await isDirectory(sessionsDir(workspace))) return null;
+  return (
+    "This workspace still has a log at .xeno/log from before named sessions existed. " +
+    "It has not been moved. Continue it with --log .xeno/log"
+  );
+}
+
+export type SessionPrefixMatch =
+  | { ok: true; session: Extract<ListedSession, { ok: true }> }
+  | { ok: false; reason: string; candidates: string[] };
+
+/**
+ * Unique prefix or exact path only. Two matches is a list, never catalog
+ * order -- the same rule as findModelByPattern. Guessing here would open
+ * someone else's session because ids share a timestamp prefix.
+ */
+export async function findSessionByPrefix(
+  workspace: string,
+  prefix: string,
+  sessionDir?: string,
+): Promise<SessionPrefixMatch> {
+  const needle = prefix.trim();
+  if (needle.length === 0) {
+    return { ok: false, reason: "empty session id", candidates: [] };
+  }
+
+  const { sessions } = await listSessions(workspace, sessionDir);
+  const ok = sessions.filter((s): s is Extract<ListedSession, { ok: true }> => s.ok);
+
+  const exactId = ok.filter((s) => s.id === needle);
+  if (exactId.length === 1) return { ok: true, session: exactId[0]! };
+
+  const exactPath = ok.filter((s) => s.path === needle);
+  if (exactPath.length === 1) return { ok: true, session: exactPath[0]! };
+
+  const existing = await existingDir(workspace, needle);
+  if (existing !== null) {
+    const listed = ok.find((s) => s.path === existing);
+    if (listed !== undefined) return { ok: true, session: listed };
+    const read = await readListed(basename(existing), existing);
+    if (read.ok) return { ok: true, session: read };
+    return {
+      ok: true,
+      session: {
+        ok: true,
+        id: basename(existing),
+        path: existing,
+        name: null,
+        model: null,
+        node: null,
+        events: 0,
+        updated_at: null,
+      },
+    };
+  }
+
+  const hits = ok.filter((s) => s.id.startsWith(needle));
+  if (hits.length === 1) return { ok: true, session: hits[0]! };
+  if (hits.length === 0) {
+    return { ok: false, reason: `unknown session: ${needle}`, candidates: [] };
+  }
+  const ids = hits.map((s) => s.id);
+  return {
+    ok: false,
+    reason:
+      `ambiguous session id prefix ${JSON.stringify(needle)}: matches ${ids.join(", ")}. ` +
+      "Be more specific rather than guessing",
+    candidates: ids,
+  };
+}
+
+/**
+ * Copy the log graph and its content-addressed observations, then open a new
+ * inherit node at the chosen point. Like copying Git objects and moving a ref,
+ * this keeps immutable evidence intact (D3/D8 / M.2). Flattening just the current
+ * context loses earlier handoffs; flattening every event loses cut semantics.
+ * Publication is atomic into an empty destination, so a partial copy cannot be
+ * mistaken for a resumable session. Historical log_ref paths retain provenance;
+ * readers resolve node IDs and artifact hashes inside the new session.
+ */
+export async function copyAncestryTo(
+  sourceDir: string,
+  destDir: string,
+  createdAt: string,
+  untilEvent?: string,
+): Promise<void> {
+  const rel = relative(resolve(sourceDir), resolve(destDir));
+  if (rel === "" || (!rel.startsWith("..") && !isAbsolute(rel))) {
+    throw new Error("cannot copy a session into itself or its descendants");
+  }
+  await mkdir(destDir, { recursive: true });
+  if ((await readdir(destDir)).length > 0) throw new Error("cannot copy session into a nonempty destination");
+  const stage = await mkdtemp(join(dirname(destDir), ".xeno-copy-"));
+  try {
+    await cp(sourceDir, stage, { recursive: true, force: false, errorOnExist: true });
+    const recorded = await readCursor(stage);
+    const cursor = recorded === null ? null : await recoverCut(stage, recorded);
+    const tip = cursor?.node ?? 0;
+    const history = await readNodeHistory(stage, tip);
+    if (!history.ok) throw new Error(`cannot copy session: ${history.error}`);
+    let target = tip;
+    if (untilEvent !== undefined) {
+      const matches = history.nodes.filter((n) => n.events.some((e) => e.id === untilEvent));
+      if (matches.length !== 1) throw new Error(`cannot copy session: event ${untilEvent} is missing or ambiguous on the current path`);
+      target = matches[0]!.node;
+    }
+    const nodes = await listNodes(stage);
+    const next = Math.max(cursor?.next_node ?? 1, ...nodes.map((n) => n + 1));
+    await initNode(stage, next, {
+      node: target, log_ref: nodePath(destDir, target), sha256: await digestNode(stage, target),
+      ...(untilEvent === undefined ? {} : { at_event: untilEvent }),
+    }, createdAt, "inherit");
+    await writeCursor(stage, {
+      ...cursor, node: next, next_node: next + 1, model: cursor?.model ?? "unknown", updated_at: createdAt,
+    });
+    await replayContext(stage, next);
+    await syncCopiedTree(stage);
+    await rename(stage, destDir);
+    const parent = await open(dirname(destDir), "r");
+    try { await parent.sync(); } finally { await parent.close(); }
+  } finally { await rm(stage, { recursive: true, force: true }); }
+}
+
+async function syncCopiedTree(dir: string): Promise<void> {
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) await syncCopiedTree(path);
+    else if (entry.isFile()) {
+      const file = await open(path, "r");
+      try { await file.sync(); } finally { await file.close(); }
+    } else throw new Error(`cannot copy unsupported session entry: ${path}`);
+  }
+  const directory = await open(dir, "r");
+  try { await directory.sync(); } finally { await directory.close(); }
+}
+
+export interface ResolveLogOpts {
+  explicit?: string;
+  fresh?: boolean;
+  /**
+   * `-c` / `--continue`. Pick the newest session and refuse if there is
+   * none -- creating one would make `-c` indistinguishable from a first run.
+   */
+  continueLatest?: boolean;
+  /**
+   * `--no-session`. Log goes to a temp directory, so the workspace never
+   * grows a `.xeno/sessions/` folder. A flag that still called createSession
+   * would pass every assertion on the flag and still leave a directory.
+   */
+  noSession?: boolean;
+  session?: string;
+  sessionDir?: string;
+}
+
+/**
+ * Picks the log directory for a process that did not pass a path, or
+ * honours one that did.
+ *
+ * Newest-by-recorded-time is the default because that is the session the
+ * person was just in. `--fresh` always allocates a new one; it never
+ * deletes. A leftover `.xeno/log` is not picked -- that would make the
+ * `--log .xeno/log` the card requires for continuing it unnecessary, and
+ * it would mix the old layout into the new one without anyone asking.
+ */
+export async function resolveLogDir(
+  workspace: string,
+  opts: ResolveLogOpts = {},
+): Promise<{ logDir: string; created: boolean; legacyNotice: string | null }> {
+  // Computed first: createSession will mkdir `.xeno/sessions/`, after which
+  // the leftover-log condition is no longer true.
+  const legacyNotice = await legacyLogNotice(workspace);
+  if (opts.noSession === true) {
+    const logDir = await mkdtemp(join(tmpdir(), "xeno-nosession-"));
+    return { logDir, created: true, legacyNotice };
+  }
+  if (opts.explicit !== undefined) {
+    return { logDir: opts.explicit, created: false, legacyNotice };
+  }
+  if (opts.session !== undefined && opts.session.length > 0) {
+    const found = await findSessionByPrefix(workspace, opts.session, opts.sessionDir);
+    if (!found.ok) throw new Error(found.reason);
+    return { logDir: found.session.path, created: false, legacyNotice };
+  }
+  if (opts.continueLatest === true) {
+    const { sessions } = await listSessions(workspace, opts.sessionDir);
+    const newest = sessions.find((s) => s.ok);
+    if (newest === undefined) {
+      throw new Error("no session to continue");
+    }
+    return { logDir: newest.path, created: false, legacyNotice };
+  }
+  if (opts.fresh !== true) {
+    const { sessions } = await listSessions(workspace, opts.sessionDir);
+    const newest = sessions.find((s) => s.ok);
+    if (newest !== undefined) {
+      return { logDir: newest.path, created: false, legacyNotice };
+    }
+  }
+  const created = await createSession(workspace, systemIdClock, opts.sessionDir);
+  return { logDir: created.path, created: true, legacyNotice };
+}
+
+async function existingDir(workspace: string, prefix: string): Promise<string | null> {
+  if (await isDirectory(prefix)) return prefix;
+  const rel = join(workspace, prefix);
+  if (rel !== prefix && (await isDirectory(rel))) return rel;
+  return null;
+}
+
+async function readListed(id: string, path: string): Promise<ListedSession> {
+  let parsed: unknown;
+  try {
+    parsed = await readManifest(path);
+  } catch (err) {
+    if ((err as { code?: string }).code === "ENOENT") {
+      return {
+        ok: true, id, path,
+        name: null, model: null, node: null, events: 0, updated_at: null,
+      };
+    }
+    return { ok: false, id, path, error: `${path} could not be read: ${(err as Error).message}` };
+  }
+
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return { ok: false, id, path, error: `${path} manifest is not an object` };
+  }
+
+  const manifest = parsed as Manifest;
+  const cursor = manifest.cursor;
+  if (cursor === undefined) {
+    return {
+      ok: true, id, path,
+      name: null, model: null, node: null, events: 0, updated_at: null,
+    };
+  }
+
+  // The open node's size, not an ancestry walk. Walking can fail the whole
+  // listing (a cycle, a missing parent), and a list that throws for one
+  // bad tree is the same shape as a list that throws for one bad file.
+  const events = (await readNode(path, cursor.node)).events.length;
+  return {
+    ok: true,
+    id,
+    path,
+    name: cursor.name ?? null,
+    model: cursor.model,
+    node: cursor.node,
+    events,
+    updated_at: cursor.updated_at,
+  };
+}
+
+function byRecordedTime(a: ListedSession, b: ListedSession): number {
+  const ta = a.ok ? a.updated_at : null;
+  const tb = b.ok ? b.updated_at : null;
+  if (ta !== null && tb !== null) return tb < ta ? -1 : tb > ta ? 1 : 0;
+  if (ta !== null) return -1;
+  if (tb !== null) return 1;
+  return 0;
+}
+
+async function isDirectory(path: string): Promise<boolean> {
+  try {
+    return (await stat(path)).isDirectory();
+  } catch (err) {
+    if ((err as { code?: string }).code === "ENOENT") return false;
+    throw err;
+  }
+}

package/src/store/trust.ts

@@ -0,0 +1,69 @@
+/**
+ * Project trust: whether to load `.xeno/settings.json` for a directory.
+ *
+ * Trust does not affect tool execution. Path tools stay confined to the
+ * workspace root regardless, and bash still goes through the permission
+ * gate. This file only records which directories may contribute project
+ * settings. AGENTS.md is loaded whether the project is trusted or not.
+ */
+
+import { dirname, join, resolve } from "node:path";
+import { configDir, readJsonFile, writeJsonFile } from "./config.ts";
+
+export type TrustFile = { readonly [dir: string]: boolean };
+
+export function trustPath(): string {
+  return join(configDir(), "trust.json");
+}
+
+export function projectSettingsPath(workspace: string): string {
+  return join(workspace, ".xeno", "settings.json");
+}
+
+/**
+ * Closest saved decision on `dir` or a parent. Undefined if none.
+ *
+ * A parent applies to its children so trusting a repo root covers the
+ * packages underneath; a closer entry wins so a single untrusted nested
+ * project can opt out.
+ */
+export function lookupTrust(decisions: TrustFile, dir: string): boolean | undefined {
+  let current = resolve(dir);
+  for (;;) {
+    const value = decisions[current];
+    if (value !== undefined) return value;
+    const parent = dirname(current);
+    if (parent === current) return undefined;
+    current = parent;
+  }
+}
+
+export async function readTrust(): Promise<{ value: TrustFile; error: string | null }> {
+  const { value, error } = await readJsonFile<unknown>(trustPath());
+  if (error) return { value: {}, error };
+  if (value === null) return { value: {}, error: null };
+  if (!isTrustFile(value)) {
+    return { value: {}, error: `${trustPath()} is not a directory-to-boolean map` };
+  }
+  return { value, error: null };
+}
+
+export async function writeTrust(decisions: TrustFile): Promise<void> {
+  await writeJsonFile(trustPath(), decisions, false);
+}
+
+export async function saveTrust(dir: string, trusted: boolean): Promise<void> {
+  const { value } = await readTrust();
+  const next: { [dir: string]: boolean } = { ...value };
+  next[resolve(dir)] = trusted;
+  await writeTrust(next);
+}
+
+function isTrustFile(value: unknown): value is TrustFile {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const rec = value as { readonly [k: string]: unknown };
+  for (const key of Object.keys(rec)) {
+    if (typeof rec[key] !== "boolean") return false;
+  }
+  return true;
+}