session-steward 0.2.0 → 0.3.0

package/lib/server.mjs

@@ -5,27 +5,10 @@ import { promises as fs } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { getProvider } from "./providers/index.mjs";
+import { getProvider, listProviders } from "./providers/index.mjs";
 import { createProviderSettings } from "./settings.mjs";
 import { classifyInstalledVersion } from "./version-support.mjs";
 
-const {
-  assertDeepCleanupSupported,
-  deleteSessionDeletionBackup,
-  formatSessionForJson,
-  executeSessionDeletion,
-  fingerprintSessionDeletion,
-  diagnoseStorageCompatibility,
-  getSessionOverview,
-  getSessionRecord,
-  listSessions,
-  loadDeletionStore,
-  planSessionDeletion,
-  preflightSessionDeletion,
-  restoreSessionDeletionBackup,
-  verifySessionDeletion,
-} = getProvider("codex");
-
 const MAX_BODY_BYTES = 64 * 1024;
 const ALLOWED_SCOPES = new Set(["core", "deep"]);
 const PLAN_TTL_MS = 10 * 60 * 1000;
@@ -37,6 +20,7 @@ const PLAN_REVIEW_REQUIRED = "DELETION_PLAN_REVIEW_REQUIRED";
 const SESSION_OVERVIEW_TTL_MS = 45 * 1000;
 const ALLOWED_INACTIVE_DAYS = new Set([30, 60, 90]);
 const ALLOWED_ARCHIVE_STATUSES = new Set(["all", "active", "archived"]);
+const ALLOWED_SORTS = new Set(["created", "cwd", "name", "size", "updated"]);
 const publicDirectory = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "dist");
 const staticAssets = new Map([
   ["/", { fileName: "index.html", contentType: "text/html; charset=utf-8" }],
@@ -51,22 +35,43 @@ function readCommandVersion(command, args) {
 }
 
 async function getInstalledProductVersions() {
-  const versions = { chatgptDesktop: null, codexCli: readCommandVersion("codex", ["--version"]) };
+  const versions = {
+    chatgptDesktop: null,
+    claudeCli: readCommandVersion("claude", ["--version"]),
+    claudeDesktop: null,
+    codexCli: readCommandVersion("codex", ["--version"]),
+  };
 
   if (process.platform !== "darwin") {
     return versions;
   }
 
   const chatGptInfoPath = "/Applications/ChatGPT.app/Contents/Info.plist";
+  const claudeInfoPath = "/Applications/Claude.app/Contents/Info.plist";
   try {
     await fs.access(chatGptInfoPath);
     versions.chatgptDesktop = readCommandVersion("/usr/libexec/PlistBuddy", ["-c", "Print :CFBundleShortVersionString", chatGptInfoPath]);
   } catch {
   }
+  try {
+    await fs.access(claudeInfoPath);
+    versions.claudeDesktop = readCommandVersion("/usr/libexec/PlistBuddy", ["-c", "Print :CFBundleShortVersionString", claudeInfoPath]);
+  } catch {
+  }
 
   return versions;
 }
 
+function providerOptions(providerId, home) {
+  return providerId === "codex" ? { codexHome: home } : { claudeHome: home };
+}
+
+function resolveProviderId(value) {
+  const providerId = value || "codex";
+  getProvider(providerId);
+  return providerId;
+}
+
 function getStaticAsset(requestPath) {
   const knownAsset = staticAssets.get(requestPath);
 
@@ -193,6 +198,16 @@ function getArchiveStatus(value) {
   return status;
 }
 
+function getSort(value) {
+  const sort = value || "updated";
+
+  if (!ALLOWED_SORTS.has(sort)) {
+    throw new Error("Session order is not available.");
+  }
+
+  return sort;
+}
+
 function getLocalRequestOrigin({ hostHeader, server }) {
   if (typeof hostHeader !== "string") {
     return null;
@@ -254,8 +269,8 @@ function summarizePlan(plan, preflight, scope) {
     sessionCount: plan.ids.length,
     spawnEdgeCount: plan.spawnEdgeCount,
     relatedRecordCount,
-    transcriptBytes: plan.transcriptBytes,
-    transcriptCount: plan.transcriptFileCount,
+    transcriptBytes: preflight.transcriptBytes ?? plan.transcriptBytes,
+    transcriptCount: preflight.transcriptFileCount ?? plan.transcriptFileCount,
   };
 }
 
@@ -318,14 +333,17 @@ function removeExpiredEntries(entries, ttlMs, maximum) {
   }
 }
 
-export async function startLocalServer({ codexHome, configDirectory, port = 0 }) {
+export async function startLocalServer({ claudeHome, codexHome, configDirectory, port = 0 }) {
   if (!Number.isInteger(port) || port < 0 || port > 65535) {
     throw new Error("port must be an integer between 0 and 65535.");
   }
 
   const settings = await createProviderSettings({
     configDirectory,
-    providerHomeOverrides: codexHome === undefined ? {} : { codex: codexHome },
+    providerHomeOverrides: {
+      ...(codexHome === undefined ? {} : { codex: codexHome }),
+      ...(claudeHome === undefined ? {} : { "claude-code": claudeHome }),
+    },
   });
   const mutationToken = randomBytes(32).toString("base64url");
   let mutationInProgress = false;
@@ -339,20 +357,25 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
     overviewCache = null;
   }
 
-  async function readSessionOverview({ refresh = false } = {}) {
-    const activeCodexHome = settings.getHome("codex");
+  async function readSessionOverview({ providerId, refresh = false } = {}) {
+    const home = settings.getHome(providerId);
 
     if (
       !refresh
-      && overviewCache?.codexHome === activeCodexHome
+      && overviewCache?.providerId === providerId
+      && overviewCache?.home === home
       && overviewCache.expiresAtMs > Date.now()
     ) {
       return overviewCache.overview;
     }
 
-    const overview = await getSessionOverview({ codexHome: activeCodexHome });
+    const overview = await getProvider(providerId).getSessionOverview({
+      ...providerOptions(providerId, home),
+      refresh,
+    });
     overviewCache = {
-      codexHome: activeCodexHome,
+      home,
+      providerId,
       expiresAtMs: Date.now() + SESSION_OVERVIEW_TTL_MS,
       overview,
     };
@@ -360,6 +383,7 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
   }
 
   async function removeOperationBackups(operation, additionalDirectories = []) {
+    const provider = getProvider(operation.providerId);
     const candidates = [...new Set([
       ...(operation.backupDirectories ?? []),
       operation.backupDirectory,
@@ -370,9 +394,9 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
 
     for (const backupDirectory of candidates) {
       try {
-        await deleteSessionDeletionBackup({
+        await provider.deleteSessionDeletionBackup({
           backupDirectory,
-          codexHome: operation.codexHome,
+          ...providerOptions(operation.providerId, operation.home),
         });
       } catch {
         remaining.push(backupDirectory);
@@ -403,10 +427,10 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
       );
     }
 
-    if (savedPlan.codexHome !== settings.getHome("codex")) {
+    if (savedPlan.home !== settings.getHome(savedPlan.providerId)) {
       deletionPlans.delete(planId);
       throw codedError(
-        "The Codex session folder changed. Review the selection again.",
+        `The ${getProvider(savedPlan.providerId).displayName} session folder changed. Review the selection again.`,
         PLAN_REVIEW_REQUIRED,
       );
     }
@@ -427,11 +451,13 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
     operation.progress = 2;
 
     try {
+      const provider = getProvider(savedPlan.providerId);
+      const options = providerOptions(savedPlan.providerId, savedPlan.home);
       let currentStore;
 
       try {
-        currentStore = await loadDeletionStore({
-          codexHome: savedPlan.codexHome,
+        currentStore = await provider.loadDeletionStore({
+          ...options,
           recordIds: savedPlan.requestedIds,
         });
       } catch (error) {
@@ -444,11 +470,11 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
         throw error;
       }
 
-      const currentPlan = await planSessionDeletion({
+      const currentPlan = await provider.planSessionDeletion({
         recordIds: savedPlan.requestedIds,
         store: currentStore,
       });
-      const currentFingerprint = await fingerprintSessionDeletion({
+      const currentFingerprint = await provider.fingerprintSessionDeletion({
         plan: currentPlan,
         scope: savedPlan.scope,
         store: currentStore,
@@ -461,11 +487,17 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
         );
       }
 
+      await provider.preflightSessionDeletion({
+        plan: currentPlan,
+        scope: savedPlan.scope,
+        store: currentStore,
+      });
+
       if (savedPlan.scope === "deep") {
-        await assertDeepCleanupSupported({ codexHome: savedPlan.codexHome });
+        await provider.assertDeepCleanupSupported(options);
       }
 
-      const result = await executeSessionDeletion({
+      const result = await provider.executeSessionDeletion({
         onProgress: (update) => Object.assign(operation, update),
         plan: currentPlan,
         scope: savedPlan.scope,
@@ -479,7 +511,7 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
       operation.message = "Checking that cleanup completed";
       operation.phase = "verification";
       operation.progress = 94;
-      const verification = await verifySessionDeletion({
+      const verification = await provider.verifySessionDeletion({
         plan: currentPlan,
         scope: savedPlan.scope,
         store: currentStore,
@@ -524,6 +556,9 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
         operation.status = "failed";
       }
     } finally {
+      getProvider(savedPlan.providerId).invalidateSessionCache?.(
+        providerOptions(savedPlan.providerId, savedPlan.home),
+      );
       invalidateSessionOverview();
       savedPlan.consumed = true;
       deletionPlans.delete(savedPlan.id);
@@ -543,7 +578,8 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
       canDeleteBackup: false,
       canRestore: false,
       cancelRequested: false,
-      codexHome: savedPlan.codexHome,
+      home: savedPlan.home,
+      providerId: savedPlan.providerId,
       createdAtMs: Date.now(),
       error: null,
       errorCode: null,
@@ -578,9 +614,9 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
     activeOperationId = operation.id;
     const task = (async () => {
       try {
-        const restoreResult = await restoreSessionDeletionBackup({
+        const restoreResult = await getProvider(operation.providerId).restoreSessionDeletionBackup({
           backupDirectory: operation.backupDirectory,
-          codexHome: operation.codexHome,
+          ...providerOptions(operation.providerId, operation.home),
           onProgress: (update) => Object.assign(operation, update),
         });
         operation.restoreResult = restoreResult;
@@ -609,6 +645,9 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
         operation.message = "Restore could not be completed";
         operation.status = "restore-failed";
       } finally {
+        getProvider(operation.providerId).invalidateSessionCache?.(
+          providerOptions(operation.providerId, operation.home),
+        );
         invalidateSessionOverview();
         operation.finishedAtMs = Date.now();
         if (activeOperationId === operation.id) activeOperationId = null;
@@ -656,7 +695,34 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
       }
 
       if (request.method === "GET" && requestUrl.pathname === "/api/config") {
-        sendJson(response, 200, { mutationToken, providers: settings.getAll() });
+        sendJson(response, 200, {
+          activeProviderId: settings.getActiveProviderId(),
+          mutationToken,
+          providerOrder: listProviders().map(({ id }) => id),
+          providers: settings.getAll(),
+        });
+        return;
+      }
+
+      if (request.method === "PUT" && requestUrl.pathname === "/api/settings/active-provider") {
+        requireMutationAuthorization({ request, requestUrl, token: mutationToken });
+
+        if (mutationInProgress || activeOperationId) {
+          sendJson(response, 409, { error: "Wait for the current change to finish before switching providers." });
+          return;
+        }
+
+        mutationInProgress = true;
+
+        try {
+          const activeProviderId = await settings.setActiveProviderId(
+            (await readJsonBody(request)).providerId,
+          );
+          sendJson(response, 200, { activeProviderId });
+        } finally {
+          mutationInProgress = false;
+        }
+
         return;
       }
 
@@ -691,7 +757,10 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
       }
 
       if (request.method === "GET" && requestUrl.pathname === "/api/compatibility") {
-        const diagnostic = await diagnoseStorageCompatibility({ codexHome: settings.getHome("codex") });
+        const providerId = resolveProviderId(requestUrl.searchParams.get("provider"));
+        const provider = getProvider(providerId);
+        const home = settings.getHome(providerId);
+        const diagnostic = await provider.diagnoseStorageCompatibility(providerOptions(providerId, home));
         const currentVersions = await getInstalledProductVersions();
         const versionSupport = Object.fromEntries(
           Object.entries(diagnostic.builtFor).map(([product, supportedVersions]) => [
@@ -702,12 +771,14 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
             }),
           ]),
         );
-        sendJson(response, 200, { ...diagnostic, currentVersions, versionSupport });
+        sendJson(response, 200, { ...diagnostic, currentVersions, providerId, versionSupport });
         return;
       }
 
       if (request.method === "GET" && requestUrl.pathname === "/api/session-overview") {
+        const providerId = resolveProviderId(requestUrl.searchParams.get("provider"));
         const overview = await readSessionOverview({
+          providerId,
           refresh: requestUrl.searchParams.get("refresh") === "true",
         });
         sendJson(response, 200, { overview });
@@ -715,64 +786,76 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
       }
 
       if (request.method === "GET" && requestUrl.pathname === "/api/sessions") {
-        const result = await listSessions({
+        const providerId = resolveProviderId(requestUrl.searchParams.get("provider"));
+        const provider = getProvider(providerId);
+        const result = await provider.listSessions({
           archiveStatus: getArchiveStatus(requestUrl.searchParams.get("archiveStatus")),
-          codexHome: settings.getHome("codex"),
+          ...providerOptions(providerId, settings.getHome(providerId)),
           inactiveBeforeMs: getInactiveBeforeMs(requestUrl.searchParams.get("inactiveDays")),
           includeInternals: requestUrl.searchParams.get("includeInternals") === "true",
           includeSupporting: requestUrl.searchParams.get("includeSupporting") === "true",
           page: getPositiveInteger(requestUrl.searchParams.get("page"), 1),
           pageSize: getPositiveInteger(requestUrl.searchParams.get("pageSize"), 25, 100),
+          refresh: requestUrl.searchParams.get("refresh") === "true",
           search: requestUrl.searchParams.get("search"),
-          sort: requestUrl.searchParams.get("sort"),
+          sort: getSort(requestUrl.searchParams.get("sort")),
           workspace: requestUrl.searchParams.has("workspace")
             ? requestUrl.searchParams.get("workspace")
             : undefined,
         });
         sendJson(response, 200, {
           ...result,
-          records: result.records.map(formatSessionForJson),
+          records: result.records.map(provider.formatSessionForJson),
         });
         return;
       }
 
       if (request.method === "GET" && requestUrl.pathname.startsWith("/api/sessions/")) {
+        const providerId = resolveProviderId(requestUrl.searchParams.get("provider"));
+        const provider = getProvider(providerId);
         const id = decodeURIComponent(requestUrl.pathname.slice("/api/sessions/".length));
-        const record = await getSessionRecord({ codexHome: settings.getHome("codex"), id });
+        const record = await provider.getSessionRecord({
+          ...providerOptions(providerId, settings.getHome(providerId)),
+          id,
+        });
 
         if (!record) {
           sendJson(response, 404, { error: "Session not found." });
           return;
         }
 
-        sendJson(response, 200, { record: formatSessionForJson(record) });
+        sendJson(response, 200, { record: provider.formatSessionForJson(record) });
         return;
       }
 
       if (request.method === "POST" && requestUrl.pathname === "/api/deletion-plans") {
         const body = await readJsonBody(request);
+        const providerId = resolveProviderId(body.providerId);
+        const provider = getProvider(providerId);
         const ids = normalizeIds(body.ids);
         const scope = getScope(body.scope);
-        const activeCodexHome = settings.getHome("codex");
+        const home = settings.getHome(providerId);
+        const options = providerOptions(providerId, home);
 
         if (scope === "deep") {
-          await assertDeepCleanupSupported({ codexHome: activeCodexHome });
+          await provider.assertDeepCleanupSupported(options);
         }
 
-        const store = await loadDeletionStore({
-          codexHome: activeCodexHome,
+        const store = await provider.loadDeletionStore({
+          ...options,
           recordIds: ids,
         });
-        const plan = await planSessionDeletion({ recordIds: ids, store });
-        const preflight = await preflightSessionDeletion({ plan, store });
+        const plan = await provider.planSessionDeletion({ recordIds: ids, store });
+        const preflight = await provider.preflightSessionDeletion({ plan, scope, store });
         const id = randomBytes(18).toString("base64url");
         const expiresAtMs = Date.now() + PLAN_TTL_MS;
         const savedPlan = {
-          codexHome: activeCodexHome,
+          home,
           consumed: false,
           expiresAtMs,
-          fingerprint: await fingerprintSessionDeletion({ plan, scope, store }),
+          fingerprint: await provider.fingerprintSessionDeletion({ plan, scope, store }),
           id,
+          providerId,
           requestedIds: ids,
           scope,
         };
@@ -781,16 +864,18 @@ export async function startLocalServer({ codexHome, configDirectory, port = 0 })
           deletionPlans.delete(deletionPlans.keys().next().value);
         }
         deletionPlans.set(id, savedPlan);
+        const warnings = preflight.activeThreadDetection === "unavailable"
+          ? [`The current ${provider.displayName} runtime cannot identify an active session. Confirm it is safe to delete the selected sessions.`]
+          : [];
         sendJson(response, 200, {
           plan: {
             ...summarizePlan(plan, preflight, scope),
             expiresAtMs,
             id,
+            warnings,
           },
           scope,
-          warnings: preflight.activeThreadDetection === "unavailable"
-            ? ["The current Codex runtime cannot identify an active session. Confirm it is safe to delete the selected sessions."]
-            : [],
+          warnings,
         });
         return;
       }

package/lib/settings.mjs

@@ -7,6 +7,17 @@ const CONFIG_VERSION = 1;
 const PROVIDERS = {
   codex: {
     defaultHome: () => path.join(os.homedir(), ".codex"),
+    displayName: "Codex",
+    homeLabel: "Codex home folder",
+    homePlaceholder: "~/.codex",
+  },
+  "claude-code": {
+    defaultHome: () => process.env.CLAUDE_CONFIG_DIR && path.isAbsolute(process.env.CLAUDE_CONFIG_DIR)
+      ? path.resolve(process.env.CLAUDE_CONFIG_DIR)
+      : path.join(os.homedir(), ".claude"),
+    displayName: "Claude Code",
+    homeLabel: "Claude home folder",
+    homePlaceholder: "~/.claude",
   },
 };
 
@@ -165,7 +176,10 @@ export async function createProviderSettings({ configDirectory, providerHomeOver
 
     return {
       defaultHome,
+      displayName: definition.displayName,
       home,
+      homeLabel: definition.homeLabel,
+      homePlaceholder: definition.homePlaceholder,
       isDefault: home === defaultHome,
       source: startupHomes[providerId] && home === startupHomes[providerId]
         ? "startup"
@@ -175,6 +189,29 @@ export async function createProviderSettings({ configDirectory, providerHomeOver
     };
   }
 
+  function getActiveProviderId() {
+    return typeof config.activeProviderId === "string" && PROVIDERS[config.activeProviderId]
+      ? config.activeProviderId
+      : "codex";
+  }
+
+  async function setActiveProviderId(providerId) {
+    getProviderDefinition(providerId);
+    const nextConfig = {
+      ...config,
+      activeProviderId: providerId,
+      providers: config.providers,
+      version: CONFIG_VERSION,
+    };
+    try {
+      await writeConfig(configPath, nextConfig);
+    } catch (error) {
+      throw new Error("Session Steward could not remember this provider.", { cause: error });
+    }
+    config = nextConfig;
+    return providerId;
+  }
+
   async function setProviderHome(providerId, value) {
     const definition = getProviderDefinition(providerId);
     const home = await requireExistingDirectory(value);
@@ -221,9 +258,11 @@ export async function createProviderSettings({ configDirectory, providerHomeOver
   }
 
   return {
+    getActiveProviderId,
     getAll: () => Object.fromEntries(Object.keys(PROVIDERS).map((providerId) => [providerId, getProvider(providerId)])),
     getHome: (providerId) => getProvider(providerId).home,
     resetProviderHome,
+    setActiveProviderId,
     setProviderHome,
   };
 }

package/lib/storage/files.mjs

@@ -0,0 +1,39 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+
+export async function measurePath(targetPath) {
+  let bytes = 0;
+  let fileCount = 0;
+  const pending = [path.resolve(targetPath)];
+
+  while (pending.length > 0) {
+    const currentPath = pending.pop();
+    let stats;
+
+    try {
+      stats = await fs.lstat(currentPath);
+    } catch (error) {
+      if (error?.code === "ENOENT") continue;
+      throw error;
+    }
+
+    if (stats.isSymbolicLink()) continue;
+
+    if (stats.isDirectory()) {
+      const entries = await fs.readdir(currentPath);
+
+      for (const entry of entries) {
+        pending.push(path.join(currentPath, entry));
+      }
+
+      continue;
+    }
+
+    if (stats.isFile()) {
+      bytes += stats.size;
+      fileCount += 1;
+    }
+  }
+
+  return { bytes, fileCount };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "session-steward",
-  "version": "0.2.0",
-  "description": "A local Codex session manager for safely reviewing and deleting old sessions with a browser UI or terminal CLI.",
+  "version": "0.3.0",
+  "description": "A local Codex and Claude Code session manager for safely reviewing and deleting old sessions.",
   "license": "MIT",
   "author": "Mallik Cheripally",
   "type": "module",
@@ -17,6 +17,9 @@
   "bugs": "https://github.com/mallikcheripally/session-steward/issues",
   "keywords": [
     "codex",
+    "claude-code",
+    "claude-code-sessions",
+    "claude-desktop",
     "codex-cli",
     "openai-codex",
     "codex-sessions",
@@ -27,6 +30,7 @@
     "delete-codex-sessions",
     "session-manager",
     "session-cleanup",
+    "ai-session-manager",
     "chatgpt-desktop",
     "chatgpt-history",
     "ai-coding-agent",
@@ -37,6 +41,7 @@
     "bin",
     "dist",
     "lib",
+    "CHANGELOG.md",
     "LICENSE",
     "README.md"
   ],
@@ -51,8 +56,10 @@
     "benchmark:discovery": "node --expose-gc test/benchmarks/codex-discovery.mjs",
     "benchmark:overview": "node --expose-gc test/benchmarks/codex-overview.mjs",
     "benchmark:scale": "node --expose-gc test/benchmarks/codex-list.mjs",
+    "benchmark:size": "node --expose-gc test/benchmarks/codex-size.mjs",
     "benchmark:transcripts": "node --expose-gc test/benchmarks/codex-transcripts.mjs",
     "prepack": "npm run build",
+    "pretest": "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",