npm - session-steward - Versions diffs - 0.3.0 → 0.4.0 - Mend

session-steward 0.3.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/CHANGELOG.md +16 -0
package/README.md +14 -14
package/dist/assets/index-BQ6SUqXr.css +2 -0
package/dist/assets/{index-fUX3qen0.js → index-QhQbSn0H.js} +1 -1
package/dist/index.html +2 -2
package/lib/cli.mjs +5 -0
package/lib/providers/claude-code/store.mjs +60 -15
package/lib/providers/codex/database-families.mjs +177 -0
package/lib/providers/codex/store.mjs +466 -329
package/lib/server.mjs +8 -3
package/package.json +2 -1
package/dist/assets/index-CN9iax_v.css +0 -2

package/dist/index.html CHANGED Viewed

@@ -5,8 +5,8 @@
     <meta name="viewport" content="width=device-width,initial-scale=1.0"/>
     <link href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3E%3Crect width='32' height='32' rx='8' fill='%23171717'/%3E%3Cpath d='M16 4 26 8v7c0 6-4 11-10 13C10 26 6 21 6 15V8Z' fill='%23f5f5f5'/%3E%3Cpath d='m9.5 16 2.2-2.2 3 3 6.5-6.5 2.2 2.2-8.7 8.7Z' fill='%23171717'/%3E%3C/svg%3E" rel="icon"/>
     <title>Session Steward</title>
-    <script type="module" crossorigin src="/assets/index-fUX3qen0.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-CN9iax_v.css">
+    <script type="module" crossorigin src="/assets/index-QhQbSn0H.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-BQ6SUqXr.css">
   </head>
   <body>
     <div id="root"></div>

package/lib/cli.mjs CHANGED Viewed

@@ -908,6 +908,11 @@ async function runInteractive(state) {
               `Skipped ${result.skippedTranscriptPaths.length} missing transcript paths.\n`,
             );
           }
+          if (result.unrecognizedLocationCount > 0) {
+            output.write(
+              `${result.unrecognizedLocationCount} ${result.unrecognizedLocationCount === 1 ? "location" : "locations"} in your Claude folder ${result.unrecognizedLocationCount === 1 ? "was" : "were"} not recognized and ${result.unrecognizedLocationCount === 1 ? "was" : "were"} not examined.\n`,
+            );
+          }
           state.provider.invalidateSessionCache?.(
             providerOptions(state.provider.id, state.providerHome),

package/lib/providers/claude-code/store.mjs CHANGED Viewed

@@ -10,6 +10,10 @@ import { measurePath } from "../../storage/files.mjs";
 import { readJsonlEntries, rewriteJsonlFile } from "../../storage/jsonl.mjs";
 const PROVIDER_ID = "claude-code";
+const COMPATIBILITY_PROFILE = Object.freeze({
+  id: "claude-local-store-2026-08",
+  builtFor: { claudeCli: ["2.1.199", "2.1.220"], claudeDesktop: ["1.24012.9"] },
+});
 const SUPPORTED_ENTRYPOINTS = new Set(["cli", "claude-desktop"]);
 const KNOWN_TOP_LEVEL = new Set([
   ".DS_Store", ".last-cleanup", ".last-update-result.json", "agents", "backups", "cache", "commands", "debug", "downloads", "file-history", "history.jsonl",
@@ -331,8 +335,9 @@ async function discover(claudeHome, desktopDataHome) {
   const summariesById = new Map();
   const unknown = [];
   let projectDirectories = [];
+  let projectsAvailability = "available";
   try { projectDirectories = await fs.readdir(paths.projectsDirectory, { withFileTypes: true }); } catch (error) {
-    if (error?.code !== "ENOENT") throw error;
+    projectsAvailability = error?.code === "ENOENT" ? "missing" : "unreadable";
   }
   for (const projectEntry of projectDirectories) {
     if (!projectEntry.isDirectory()) continue;
@@ -387,7 +392,7 @@ async function discover(claudeHome, desktopDataHome) {
       updatedAtMs: Math.max(...copies.map((item) => item.activityAtMs)),
     });
   }
-  return { desktop, paths, records, recordsById: new Map(records.map((record) => [record.id, record])), unknown };
+  return { desktop, paths, projectsAvailability, records, recordsById: new Map(records.map((record) => [record.id, record])), unknown };
 }
 async function discoverCached(claudeHome, desktopDataHome, { refresh = false } = {}) {
@@ -513,24 +518,31 @@ async function topLevelEntries(directory) {
 export async function diagnoseStorageCompatibility({ claudeHome, desktopDataHome }) {
   const store = await discoverCached(claudeHome, desktopDataHome);
-  const newlyDiscovered = [];
+  const unrecognized = [];
   for (const entry of await topLevelEntries(store.paths.claudeHome)) {
-    if (!KNOWN_TOP_LEVEL.has(entry.name)) newlyDiscovered.push(`Unrecognized Claude data: ${entry.name}`);
+    if (!KNOWN_TOP_LEVEL.has(entry.name)) unrecognized.push(`Unrecognized Claude data: ${entry.name}`);
   }
-  if (store.unknown.length) newlyDiscovered.push(`${store.unknown.length} session file${store.unknown.length === 1 ? "" : "s"} could not be classified safely.`);
-  if (store.desktop.unlinked.length) newlyDiscovered.push(`${store.desktop.unlinked.length} Desktop session record${store.desktop.unlinked.length === 1 ? "" : "s"} could not be linked safely.`);
+  if (store.unknown.length) unrecognized.push(`${store.unknown.length} session file${store.unknown.length === 1 ? "" : "s"} could not be classified safely.`);
+  if (store.desktop.unlinked.length) unrecognized.push(`${store.desktop.unlinked.length} Desktop session record${store.desktop.unlinked.length === 1 ? "" : "s"} could not be linked safely.`);
+  const missing = store.projectsAvailability === "available"
+    ? []
+    : [store.projectsAvailability === "missing"
+      ? "Claude project sessions folder was not found."
+      : "Claude project sessions folder could not be read."];
   return {
-    builtFor: { claudeCli: ["2.1.199", "2.1.220"], claudeDesktop: ["1.24012.9"] },
+    builtFor: COMPATIBILITY_PROFILE.builtFor,
     changed: [],
-    missing: (await exists(store.paths.projectsDirectory)) ? [] : ["Claude project sessions folder was not found."],
-    newlyDiscovered,
-    status: newlyDiscovered.length ? "newer-version" : "ready",
+    missing,
+    profileId: COMPATIBILITY_PROFILE.id,
+    status: missing.length ? "unsupported" : unrecognized.length ? "partial" : "ready",
+    unrecognized,
   };
 }
 export async function assertDeepCleanupSupported(options) {
   const diagnostic = await diagnoseStorageCompatibility(options);
-  if (diagnostic.status !== "ready") throw new Error("Thorough cleanup is paused because some Claude session data is not recognized yet. Standard cleanup is still available.");
+  if (diagnostic.status === "unsupported") throw new Error("Thorough cleanup is paused because the Claude project sessions folder could not be read.");
+  return diagnostic;
 }
 async function matchingHistoryStats(historyPath, ids) {
@@ -630,6 +642,8 @@ export async function planSessionDeletion({ recordIds, store }) {
     transcriptBytes: files.reduce((sum, file) => sum + file.size, 0),
     transcriptFileCount: files.length,
     transcriptPaths: [...selectedPaths],
+    unrecognizedLocationCount: (await topLevelEntries(store.paths.claudeHome))
+      .filter((entry) => !KNOWN_TOP_LEVEL.has(entry.name)).length + store.unknown.length + store.desktop.unlinked.length,
   };
 }
@@ -784,7 +798,20 @@ async function createBackup(plan, store, scope) {
       await backupHistoryRows(store.paths.historyPath, destination, new Set(plan.ids));
       sharedJsonl.push({ backupRelative, relative: "history.jsonl", root: "claude" });
     }
-    const manifest = { createdAt: new Date().toISOString(), entries, providerId: PROVIDER_ID, scope, sharedJsonl, version: 1 };
+    const compatibility = await diagnoseStorageCompatibility({
+      claudeHome: store.paths.claudeHome,
+      desktopDataHome: store.paths.desktopDataHome,
+    });
+    const manifest = {
+      compatibilityStatus: compatibility.status,
+      createdAt: new Date().toISOString(),
+      entries,
+      profileId: COMPATIBILITY_PROFILE.id,
+      providerId: PROVIDER_ID,
+      scope,
+      sharedJsonl,
+      version: 2,
+    };
     await fs.writeFile(path.join(backupDirectory, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
     return backupDirectory;
   } catch (error) {
@@ -807,7 +834,13 @@ export async function executeSessionDeletion({ onProgress = () => {}, plan, scop
     if (scope === "deep") targets.push(...plan.deepPaths);
     for (const target of [...new Set(targets)].sort((a, b) => b.length - a.length)) await fs.rm(target, { force: true, recursive: true });
     onProgress({ canCancel: false, message: "Checking cleanup", phase: "verification", progress: 90 });
-    return { backupDirectory, deletedIds: plan.ids, deletedTranscriptPaths: plan.transcriptPaths, skippedTranscriptPaths: [] };
+    return {
+      backupDirectory,
+      deletedIds: plan.ids,
+      deletedTranscriptPaths: plan.transcriptPaths,
+      skippedTranscriptPaths: [],
+      unrecognizedLocationCount: plan.unrecognizedLocationCount,
+    };
   } catch (error) {
     error.backupDirectory = backupDirectory;
     throw error;
@@ -863,7 +896,7 @@ export async function listSessionDeletionBackups({ claudeHome }) {
       measurePath(backupDirectory),
     ]);
     const restorable = manifest?.providerId === PROVIDER_ID &&
-      manifest?.version === 1 &&
+      [1, 2].includes(manifest?.version) &&
       Array.isArray(manifest.entries);
     backups.push({
@@ -892,6 +925,8 @@ export async function restoreSessionDeletionBackup({ backupDirectory, claudeHome
   }
   const manifest = JSON.parse(await fs.readFile(path.join(backupDirectory, "manifest.json"), "utf8"));
   if (manifest?.providerId !== PROVIDER_ID || !Array.isArray(manifest.entries)) throw new Error("This recovery backup is not valid for Claude Code.");
+  invalidateSessionCache({ claudeHome, desktopDataHome });
+  const currentCompatibilityBeforeRestore = await diagnoseStorageCompatibility({ claudeHome, desktopDataHome });
   const safetyBackupDirectory = path.join(store.paths.backupRoot, `restore-safety-${Date.now()}-${randomBytes(4).toString("hex")}`);
   await fs.mkdir(safetyBackupDirectory, { mode: 0o700, recursive: true });
   try {
@@ -931,7 +966,17 @@ export async function restoreSessionDeletionBackup({ backupDirectory, claudeHome
       await pipeline(createReadStream(source), createWriteStream(destination, { flags: "a", mode: 0o600 }));
     }
     onProgress({ message: "Checking restored sessions", progress: 92 });
-    return { recoveryBackupsDeleted: false, restoredEntryCount: manifest.entries.length + (manifest.sharedJsonl?.length ?? 0), safetyBackupDirectory };
+    const layoutChanged = manifest.version === 2 && (
+      manifest.profileId !== COMPATIBILITY_PROFILE.id
+      || manifest.compatibilityStatus !== currentCompatibilityBeforeRestore.status
+    );
+    invalidateSessionCache({ claudeHome, desktopDataHome });
+    return {
+      note: layoutChanged ? "The Claude storage layout changed after this backup was created. The recorded files were restored to their original locations." : null,
+      recoveryBackupsDeleted: false,
+      restoredEntryCount: manifest.entries.length + (manifest.sharedJsonl?.length ?? 0),
+      safetyBackupDirectory,
+    };
   } catch (error) {
     error.safetyBackupDirectory = safetyBackupDirectory;
     throw error;

package/lib/providers/codex/database-families.mjs ADDED Viewed

@@ -0,0 +1,177 @@
+import { readdirSync } from "node:fs";
+import path from "node:path";
+import { queryRows } from "../../storage/sqlite.mjs";
+const CACHE_TTL_MS = 2_000;
+export const CODEX_DATABASE_PROFILE = Object.freeze({
+  id: "codex-local-store-2026-08",
+  builtFor: {
+    chatgptDesktop: ["26.727.40816"],
+    codexCli: ["0.144.1", "0.146.0"],
+  },
+});
+const SCHEMA_REQUIREMENTS = Object.freeze({
+  state: {
+    fallback: "state_5.sqlite",
+    pattern: /^state_(\d+)\.sqlite$/u,
+    required: true,
+    tables: [{ name: "threads", requiredColumns: ["id", "rollout_path"] }],
+  },
+  logs: {
+    fallback: "logs_2.sqlite",
+    pattern: /^logs_(\d+)\.sqlite$/u,
+    required: false,
+    tables: [{ name: "logs", requiredColumns: ["thread_id"] }],
+  },
+  memories: {
+    fallback: "memories_1.sqlite",
+    pattern: /^memories_(\d+)\.sqlite$/u,
+    required: false,
+    tables: [{ name: "stage1_outputs", requiredColumns: ["thread_id"] }],
+  },
+  goals: {
+    fallback: "goals_1.sqlite",
+    pattern: /^goals_(\d+)\.sqlite$/u,
+    required: false,
+    tables: [
+      { name: "thread_goals", requiredColumns: ["thread_id"] },
+      { name: "thread_goal_continuation_deferrals", requiredColumns: ["thread_id"] },
+    ],
+  },
+});
+const resolutionCache = new Map();
+function inspectTable(databasePath, tableName) {
+  const exists = queryRows(
+    databasePath,
+    "select name from sqlite_master where type = 'table' and name = ?",
+    [tableName],
+  ).length > 0;
+  if (!exists) return { columns: new Set(), exists: false };
+  return {
+    columns: new Set(
+      queryRows(databasePath, "select name from pragma_table_info(?)", [tableName])
+        .map((column) => String(column.name)),
+    ),
+    exists: true,
+  };
+}
+function inspectCandidate(codexHome, filename, version, family) {
+  const databasePath = path.join(codexHome, filename);
+  try {
+    const tables = Object.fromEntries(
+      family.tables.map((requirement) => {
+        const inspection = inspectTable(databasePath, requirement.name);
+        const missingColumns = requirement.requiredColumns.filter(
+          (column) => !inspection.columns.has(column),
+        );
+        return [requirement.name, { ...inspection, missingColumns }];
+      }),
+    );
+    const invalidTable = family.tables.find((requirement) => {
+      const table = tables[requirement.name];
+      return !table.exists || table.missingColumns.length > 0;
+    });
+    return {
+      filename,
+      path: databasePath,
+      reason: invalidTable
+        ? !tables[invalidTable.name].exists
+          ? `Missing table: ${invalidTable.name}`
+          : `Missing fields in ${invalidTable.name}: ${tables[invalidTable.name].missingColumns.join(", ")}`
+        : null,
+      tables,
+      valid: !invalidTable,
+      version,
+    };
+  } catch (error) {
+    return {
+      filename,
+      path: databasePath,
+      reason: error instanceof Error ? error.message : "Database could not be inspected.",
+      tables: {},
+      valid: false,
+      version,
+    };
+  }
+}
+function fallbackResolution(codexHome) {
+  return Object.fromEntries(Object.entries(SCHEMA_REQUIREMENTS).map(([name, family]) => [name, {
+    invalid: [],
+    primary: {
+      filename: family.fallback,
+      path: path.join(codexHome, family.fallback),
+      tables: {},
+      valid: true,
+      version: Number(family.pattern.exec(family.fallback)?.[1] ?? 0),
+    },
+    required: family.required,
+    secondaries: [],
+  }]));
+}
+function discover(codexHome) {
+  let names;
+  try {
+    names = readdirSync(codexHome, { withFileTypes: true })
+      .filter((entry) => entry.isFile())
+      .map((entry) => entry.name);
+  } catch {
+    return { families: fallbackResolution(codexHome), readable: false };
+  }
+  const families = {};
+  for (const [name, family] of Object.entries(SCHEMA_REQUIREMENTS)) {
+    const candidates = names.flatMap((filename) => {
+      const match = family.pattern.exec(filename);
+      return match ? [{ filename, version: Number(match[1]) }] : [];
+    }).sort((left, right) => right.version - left.version || left.filename.localeCompare(right.filename));
+    const inspected = candidates.map((candidate) => inspectCandidate(
+      codexHome,
+      candidate.filename,
+      candidate.version,
+      family,
+    ));
+    const valid = inspected.filter((candidate) => candidate.valid);
+    families[name] = {
+      invalid: inspected.filter((candidate) => !candidate.valid),
+      primary: valid[0] ?? null,
+      required: family.required,
+      secondaries: valid.slice(1),
+    };
+  }
+  return { families, readable: true };
+}
+export function resolveCodexDatabases(codexHomeInput, { refresh = false } = {}) {
+  const codexHome = path.resolve(codexHomeInput);
+  const cached = resolutionCache.get(codexHome);
+  if (!refresh && cached?.expiresAtMs > Date.now()) return cached.value;
+  const value = discover(codexHome);
+  resolutionCache.set(codexHome, { expiresAtMs: Date.now() + CACHE_TTL_MS, value });
+  return value;
+}
+export function invalidateCodexDatabaseResolution(codexHomeInput) {
+  resolutionCache.delete(path.resolve(codexHomeInput));
+}
+export function databaseFamilySummary(resolution) {
+  return Object.fromEntries(Object.entries(resolution.families).map(([name, family]) => [name, {
+    invalid: family.invalid.map(({ filename, reason, version }) => ({ filename, reason, version })),
+    primary: family.primary
+      ? { filename: family.primary.filename, version: family.primary.version }
+      : null,
+    secondaries: family.secondaries.map(({ filename, version }) => ({ filename, version })),
+  }]));
+}
+export function allValidDatabases(family) {
+  return family.primary ? [family.primary, ...family.secondaries] : [];
+}