session-steward 0.1.0

package/lib/settings.mjs

@@ -0,0 +1,229 @@
+import { randomBytes } from "node:crypto";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const CONFIG_VERSION = 1;
+const PROVIDERS = {
+  codex: {
+    defaultHome: () => path.join(os.homedir(), ".codex"),
+  },
+};
+
+function expandHome(value) {
+  if (value === "~") {
+    return os.homedir();
+  }
+
+  if (value.startsWith("~/")) {
+    return path.join(os.homedir(), value.slice(2));
+  }
+
+  return value;
+}
+
+function normalizeHome(value) {
+  if (typeof value !== "string" || value.includes("\0")) {
+    throw new Error("Enter a valid folder path.");
+  }
+
+  const expanded = expandHome(value.trim());
+
+  if (!expanded || !path.isAbsolute(expanded)) {
+    throw new Error("Enter a full folder path, such as ~/.codex.");
+  }
+
+  return path.resolve(expanded);
+}
+
+function getProviderDefinition(providerId) {
+  const definition = PROVIDERS[providerId];
+
+  if (!definition) {
+    throw new Error("That session provider is not available.");
+  }
+
+  return definition;
+}
+
+export function getDefaultConfigDirectory() {
+  const xdgConfigHome = process.env.XDG_CONFIG_HOME;
+
+  if (xdgConfigHome && path.isAbsolute(xdgConfigHome)) {
+    return path.join(xdgConfigHome, "session-steward");
+  }
+
+  if (process.platform === "darwin") {
+    return path.join(os.homedir(), "Library", "Application Support", "session-steward");
+  }
+
+  return path.join(os.homedir(), ".config", "session-steward");
+}
+
+async function readConfig(configPath) {
+  try {
+    const parsed = JSON.parse(await fs.readFile(configPath, "utf8"));
+
+    if (parsed?.version !== CONFIG_VERSION || typeof parsed.providers !== "object" || !parsed.providers) {
+      return { providers: {}, version: CONFIG_VERSION };
+    }
+
+    return parsed;
+  } catch (error) {
+    if (error?.code === "ENOENT" || error instanceof SyntaxError) {
+      return { providers: {}, version: CONFIG_VERSION };
+    }
+
+    throw new Error("Session Steward could not read its saved settings.", { cause: error });
+  }
+}
+
+async function writeConfig(configPath, config) {
+  const configDirectory = path.dirname(configPath);
+  const temporaryPath = path.join(
+    configDirectory,
+    `.config-${process.pid}-${randomBytes(8).toString("hex")}.tmp`,
+  );
+  await fs.mkdir(configDirectory, { mode: 0o700, recursive: true });
+
+  let handle;
+
+  try {
+    handle = await fs.open(temporaryPath, "wx", 0o600);
+    await handle.writeFile(`${JSON.stringify(config, null, 2)}\n`, "utf8");
+    await handle.sync();
+    await handle.close();
+    handle = null;
+    await fs.rename(temporaryPath, configPath);
+  } catch (error) {
+    await handle?.close().catch(() => {});
+    await fs.rm(temporaryPath, { force: true }).catch(() => {});
+    throw error;
+  }
+}
+
+async function requireExistingDirectory(value) {
+  const home = normalizeHome(value);
+  let stats;
+
+  try {
+    stats = await fs.stat(home);
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      throw new Error("Choose an existing folder.");
+    }
+
+    if (error?.code === "EACCES" || error?.code === "EPERM") {
+      throw new Error("Session Steward cannot open this folder.");
+    }
+
+    throw new Error("Session Steward could not check this folder.", { cause: error });
+  }
+
+  if (!stats.isDirectory()) {
+    throw new Error("Choose a folder, not a file.");
+  }
+
+  return home;
+}
+
+export async function createProviderSettings({ configDirectory, providerHomeOverrides = {} } = {}) {
+  const resolvedConfigDirectory = configDirectory === undefined
+    ? getDefaultConfigDirectory()
+    : normalizeHome(configDirectory);
+  const configPath = path.join(resolvedConfigDirectory, "config.json");
+  let config = await readConfig(configPath);
+  const startupHomes = {};
+  const savedHomes = {};
+  const activeHomes = {};
+
+  for (const [providerId, definition] of Object.entries(PROVIDERS)) {
+    const override = providerHomeOverrides[providerId];
+    const savedValue = config.providers?.[providerId]?.home;
+    let savedHome = null;
+
+    try {
+      savedHome = savedValue === undefined ? null : normalizeHome(savedValue);
+    } catch {
+      savedHome = null;
+    }
+    savedHomes[providerId] = savedHome;
+
+    if (override !== undefined) {
+      startupHomes[providerId] = await requireExistingDirectory(override);
+    }
+
+    activeHomes[providerId] = startupHomes[providerId]
+      || savedHome
+      || definition.defaultHome();
+  }
+
+  function getProvider(providerId) {
+    const definition = getProviderDefinition(providerId);
+    const defaultHome = definition.defaultHome();
+    const home = activeHomes[providerId];
+
+    return {
+      defaultHome,
+      home,
+      isDefault: home === defaultHome,
+      source: startupHomes[providerId] && home === startupHomes[providerId]
+        ? "startup"
+        : savedHomes[providerId] && home === savedHomes[providerId]
+          ? "saved"
+          : "default",
+    };
+  }
+
+  async function setProviderHome(providerId, value) {
+    const definition = getProviderDefinition(providerId);
+    const home = await requireExistingDirectory(value);
+
+    if (home === definition.defaultHome()) {
+      return resetProviderHome(providerId);
+    }
+
+    const nextConfig = {
+      ...config,
+      providers: {
+        ...config.providers,
+        [providerId]: { home },
+      },
+      version: CONFIG_VERSION,
+    };
+    try {
+      await writeConfig(configPath, nextConfig);
+    } catch (error) {
+      throw new Error("Session Steward could not save this folder.", { cause: error });
+    }
+    config = nextConfig;
+    activeHomes[providerId] = home;
+    savedHomes[providerId] = home;
+    delete startupHomes[providerId];
+    return getProvider(providerId);
+  }
+
+  async function resetProviderHome(providerId) {
+    const definition = getProviderDefinition(providerId);
+    const providers = { ...config.providers };
+    delete providers[providerId];
+    const nextConfig = { ...config, providers, version: CONFIG_VERSION };
+    try {
+      await writeConfig(configPath, nextConfig);
+    } catch (error) {
+      throw new Error("Session Steward could not restore the default folder.", { cause: error });
+    }
+    config = nextConfig;
+    activeHomes[providerId] = definition.defaultHome();
+    savedHomes[providerId] = null;
+    delete startupHomes[providerId];
+    return getProvider(providerId);
+  }
+
+  return {
+    getAll: () => Object.fromEntries(Object.keys(PROVIDERS).map((providerId) => [providerId, getProvider(providerId)])),
+    getHome: (providerId) => getProvider(providerId).home,
+    resetProviderHome,
+    setProviderHome,
+  };
+}

package/lib/storage/jsonl.mjs

@@ -0,0 +1,86 @@
+import { once } from "node:events";
+import { createReadStream, createWriteStream } from "node:fs";
+import { promises as fs } from "node:fs";
+import readline from "node:readline";
+import { finished } from "node:stream/promises";
+
+function parseLine(raw, index) {
+  try {
+    return { index, parsed: JSON.parse(raw), raw };
+  } catch {
+    return { index, parsed: null, raw };
+  }
+}
+
+export async function* readJsonlEntries(filePath) {
+  const input = createReadStream(filePath, { encoding: "utf8" });
+  const lines = readline.createInterface({ crlfDelay: Infinity, input });
+  let index = 0;
+
+  try {
+    for await (const line of lines) {
+      if (line.length === 0) continue;
+      yield parseLine(line, index);
+      index += 1;
+    }
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      return;
+    }
+
+    throw error;
+  } finally {
+    lines.close();
+    input.destroy();
+  }
+}
+
+export async function inspectJsonlMatches(filePath, matches, { sampleLimit = 100 } = {}) {
+  let count = 0;
+  const samples = [];
+
+  for await (const entry of readJsonlEntries(filePath)) {
+    if (!matches(entry)) continue;
+    count += 1;
+
+    if (samples.length < sampleLimit) {
+      samples.push(entry);
+    }
+  }
+
+  return { count, samples };
+}
+
+export async function rewriteJsonlFile(filePath, keep) {
+  const fileStats = await fs.stat(filePath);
+  const temporaryPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+  const output = createWriteStream(temporaryPath, {
+    encoding: "utf8",
+    mode: fileStats.mode,
+  });
+  let retainedCount = 0;
+  let removedCount = 0;
+
+  try {
+    for await (const entry of readJsonlEntries(filePath)) {
+      if (!keep(entry)) {
+        removedCount += 1;
+        continue;
+      }
+
+      retainedCount += 1;
+      if (!output.write(`${entry.raw}\n`)) {
+        await once(output, "drain");
+      }
+    }
+
+    output.end();
+    await finished(output);
+    await fs.rename(temporaryPath, filePath);
+    return { removedCount, retainedCount };
+  } catch (error) {
+    output.destroy();
+    await fs.rm(temporaryPath, { force: true });
+    throw error;
+  }
+}

package/lib/storage/sqlite.mjs

@@ -0,0 +1,66 @@
+import { DatabaseSync, backup } from "node:sqlite";
+
+const SQLITE_BATCH_SIZE = 400;
+
+function openDatabase(databasePath, { readOnly }) {
+  return new DatabaseSync(databasePath, {
+    readOnly,
+    timeout: 5_000,
+  });
+}
+
+export function queryRows(databasePath, sql, parameters = []) {
+  const database = openDatabase(databasePath, { readOnly: true });
+
+  try {
+    return database.prepare(sql).all(...parameters);
+  } finally {
+    database.close();
+  }
+}
+
+export function executeTransaction(databasePath, statements) {
+  const database = openDatabase(databasePath, { readOnly: false });
+
+  try {
+    database.exec("begin immediate");
+
+    for (const { parameters = [], sql } of statements) {
+      database.prepare(sql).run(...parameters);
+    }
+
+    database.exec("commit");
+  } catch (error) {
+    if (database.isTransaction) {
+      database.exec("rollback");
+    }
+
+    throw error;
+  } finally {
+    database.close();
+  }
+}
+
+export async function backupDatabase(databasePath, destinationPath) {
+  const database = openDatabase(databasePath, { readOnly: true });
+
+  try {
+    await backup(database, destinationPath);
+  } finally {
+    database.close();
+  }
+}
+
+export function placeholders(values) {
+  if (values.length === 0) {
+    throw new Error("At least one SQLite value is required.");
+  }
+
+  return values.map(() => "?").join(", ");
+}
+
+export function* batches(values, size = SQLITE_BATCH_SIZE) {
+  for (let index = 0; index < values.length; index += size) {
+    yield values.slice(index, index + size);
+  }
+}

package/lib/update-check.mjs

@@ -0,0 +1,85 @@
+const DEFAULT_TIMEOUT_MS = 1_200;
+const STABLE_VERSION_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/u;
+
+function parseStableVersion(value) {
+  if (typeof value !== "string") return null;
+
+  const match = STABLE_VERSION_PATTERN.exec(value);
+  return match ? match.slice(1, 4).map(BigInt) : null;
+}
+
+export function compareStableVersions(left, right) {
+  const leftParts = parseStableVersion(left);
+  const rightParts = parseStableVersion(right);
+
+  if (!leftParts || !rightParts) return null;
+
+  for (let index = 0; index < leftParts.length; index += 1) {
+    if (leftParts[index] > rightParts[index]) return 1;
+    if (leftParts[index] < rightParts[index]) return -1;
+  }
+
+  return 0;
+}
+
+export async function findAvailableUpdate({
+  fetchImpl = globalThis.fetch,
+  packageMetadata,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+} = {}) {
+  const packageName = packageMetadata?.name;
+  const currentVersion = packageMetadata?.version;
+
+  if (
+    typeof fetchImpl !== "function"
+    || typeof packageName !== "string"
+    || packageName.length === 0
+    || !parseStableVersion(currentVersion)
+  ) {
+    return null;
+  }
+
+  const requestTimeoutMs = Number.isFinite(timeoutMs) && timeoutMs > 0
+    ? timeoutMs
+    : DEFAULT_TIMEOUT_MS;
+  const controller = new AbortController();
+  let timeout;
+  const timedOut = new Promise((resolve) => {
+    timeout = setTimeout(() => {
+      controller.abort();
+      resolve(null);
+    }, requestTimeoutMs);
+  });
+  const request = (async () => {
+    try {
+      const response = await fetchImpl(
+        `https://registry.npmjs.org/${encodeURIComponent(packageName)}/latest`,
+        {
+          headers: { Accept: "application/json" },
+          signal: controller.signal,
+        },
+      );
+
+      if (!response?.ok) return null;
+      return await response.json();
+    } catch {
+      return null;
+    }
+  })();
+
+  try {
+    const result = await Promise.race([request, timedOut]);
+    const latestVersion = result?.version;
+    const comparison = compareStableVersions(latestVersion, currentVersion);
+
+    if (comparison !== 1) return null;
+
+    return { currentVersion, latestVersion, packageName };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export function formatUpdateNotice({ latestVersion, packageName }) {
+  return `Session Steward ${latestVersion} is available. Update with: npm install -g ${packageName}@latest`;
+}

package/lib/version-support.mjs

@@ -0,0 +1,103 @@
+export const VERSION_SUPPORT_STATUS = Object.freeze({
+  EXACT_SUPPORTED: "exact-supported",
+  NEWER: "newer",
+  OLDER: "older",
+  UNAVAILABLE: "unavailable",
+  UNRECOGNIZED: "unrecognized",
+});
+
+const DOTTED_VERSION_PATTERN = /(?<![\d.])(\d+(?:\.\d+){2,})(?![\d.+-])/gu;
+
+function extractVersion(value) {
+  if (typeof value !== "string") return null;
+
+  const matches = [...value.matchAll(DOTTED_VERSION_PATTERN)];
+  if (matches.length !== 1) return null;
+
+  return {
+    parts: matches[0][1].split(".").map(BigInt),
+    value: matches[0][1],
+  };
+}
+
+function compareParts(left, right) {
+  const length = Math.max(left.length, right.length);
+
+  for (let index = 0; index < length; index += 1) {
+    const leftPart = left[index] ?? 0n;
+    const rightPart = right[index] ?? 0n;
+
+    if (leftPart > rightPart) return 1;
+    if (leftPart < rightPart) return -1;
+  }
+
+  return 0;
+}
+
+function parseSupportedVersions(values) {
+  if (!Array.isArray(values) || values.length === 0) return null;
+
+  const parsed = values.map(extractVersion);
+  if (parsed.some((version) => version === null)) return null;
+
+  return parsed.sort((left, right) => compareParts(left.parts, right.parts));
+}
+
+function result(status, {
+  installedVersion = null,
+  latestSupportedVersion = null,
+  matchedSupportedVersion = null,
+} = {}) {
+  return {
+    installedVersion,
+    latestSupportedVersion,
+    matchedSupportedVersion,
+    status,
+  };
+}
+
+export function classifyInstalledVersion({ installedVersion, supportedVersions } = {}) {
+  const parsedSupportedVersions = parseSupportedVersions(supportedVersions);
+  const latestSupportedVersion = parsedSupportedVersions?.at(-1)?.value ?? null;
+
+  if (
+    installedVersion === null
+    || installedVersion === undefined
+    || (typeof installedVersion === "string" && installedVersion.trim() === "")
+  ) {
+    return result(VERSION_SUPPORT_STATUS.UNAVAILABLE, { latestSupportedVersion });
+  }
+
+  const installed = extractVersion(installedVersion);
+  if (!installed || !parsedSupportedVersions) {
+    return result(VERSION_SUPPORT_STATUS.UNRECOGNIZED, {
+      installedVersion: installed?.value ?? null,
+      latestSupportedVersion,
+    });
+  }
+
+  const matched = parsedSupportedVersions.find(
+    (supported) => compareParts(installed.parts, supported.parts) === 0,
+  );
+
+  if (matched) {
+    return result(VERSION_SUPPORT_STATUS.EXACT_SUPPORTED, {
+      installedVersion: installed.value,
+      latestSupportedVersion,
+      matchedSupportedVersion: matched.value,
+    });
+  }
+
+  const comparison = compareParts(
+    installed.parts,
+    parsedSupportedVersions.at(-1).parts,
+  );
+
+  return result(
+    comparison < 0 ? VERSION_SUPPORT_STATUS.OLDER : VERSION_SUPPORT_STATUS.NEWER,
+    {
+      installedVersion: installed.value,
+      latestSupportedVersion,
+    },
+  );
+}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "session-steward",
+  "version": "0.1.0",
+  "description": "Safely review, back up, and remove local Codex sessions with a browser UI or terminal CLI.",
+  "license": "MIT",
+  "author": "Mallik Cheripally",
+  "type": "module",
+  "bin": {
+    "session-steward": "bin/session-steward.mjs",
+    "session-steward-cli": "bin/session-steward-cli.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mallikcheripally/session-steward.git"
+  },
+  "homepage": "https://github.com/mallikcheripally/session-steward#readme",
+  "bugs": "https://github.com/mallikcheripally/session-steward/issues",
+  "keywords": [
+    "codex",
+    "codex-cli",
+    "codex-sessions",
+    "openai-codex",
+    "openai",
+    "chatgpt",
+    "session-manager",
+    "session-cleanup",
+    "ai-coding-agent",
+    "cli",
+    "backup",
+    "privacy",
+    "local-first"
+  ],
+  "os": ["darwin", "linux"],
+  "files": [
+    "bin",
+    "dist",
+    "docs",
+    "lib",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=24.15.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vite build",
+    "benchmark:discovery": "node --expose-gc test/benchmarks/codex-discovery.mjs",
+    "benchmark:scale": "node --expose-gc test/benchmarks/codex-list.mjs",
+    "benchmark:transcripts": "node --expose-gc test/benchmarks/codex-transcripts.mjs",
+    "prepack": "npm run build",
+    "start": "node ./bin/session-steward.mjs",
+    "serve": "node ./bin/session-steward.mjs",
+    "check": "node ./bin/session-steward-cli.mjs --json --limit 5",
+    "test": "node --test test/*.test.mjs test/providers/*.test.mjs"
+  },
+  "dependencies": {
+    "lucide-react": "^1.28.0",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.3.3",
+    "@vitejs/plugin-react": "^6.0.5",
+    "tailwindcss": "^4.3.3",
+    "vite": "^8.2.0"
+  }
+}