@gamflaz/opencode-todolist 1.0.11 → 1.1.0

package/dist/schemas/todo.js

@@ -1,31 +1,45 @@
 import z from "zod";
 import { PrioritySchema, TodoStatusSchema } from "./status.js";
+/** A top-level id only: `1`, `2`, ... — never a dotted subtask id. */
+export const RootIdSchema = z
+    .number()
+    .int()
+    .positive()
+    .describe("Unique task identifier (e.g. 1)");
 // Child id format: <root_id>.<n> as a number -> 1.1, 2.3, etc.
 // Only a single decimal digit (1-9) is allowed, see the note below.
-const ChildIdSchema = z
+export const ChildIdSchema = z
     .number()
     .refine((n) => /^[1-9]\d*\.[1-9]$/.test(String(n)), {
     message: "Child id must follow the format <root_id>.<n> with n from 1 to 9, e.g. 1.1",
 })
     .describe("Unique subtask identifier, format <root_id>.<n> (e.g. 1.1)");
+// Root or child id, composed from the two schemas above so the id rules
+// live in exactly one place.
+export const TodoTargetIdSchema = z
+    .union([RootIdSchema, ChildIdSchema])
+    .describe("Root or child todo id, e.g. 1 or 1.1");
 // TodoItem Children SCHEMA
-export const TodoChildernItemSchema = z.object({
+export const TodoChildrenItemSchema = z
+    .object({
     id: ChildIdSchema,
     content: z.string().describe("Subtask description"),
     status: TodoStatusSchema,
     priority: PrioritySchema.optional(),
     note: z.string().optional(),
-});
+})
+    .strict();
 // TodoItem Root SCHEMA
 export const TodoRootItemSchema = z
     .object({
-    id: z.number().int().positive().describe("Unique task identifier (e.g. 1)"),
+    id: RootIdSchema,
     content: z.string().describe("Main task summary"),
     status: TodoStatusSchema,
     priority: PrioritySchema.optional(),
     note: z.string().optional(),
-    children: z.array(TodoChildernItemSchema).max(9).optional(),
+    children: z.array(TodoChildrenItemSchema).max(9).optional(),
 })
+    .strict()
     .superRefine((root, ctx) => {
     const seen = new Set();
     if (root.children) {
@@ -70,32 +84,73 @@ export const TodoListSchema = z
     });
 })
     .describe("Hierarchical task list");
-// TodoHook Write Input
-export const TodoWriteInputSchema = z.object({
-    todos: TodoListSchema,
-});
-export const TodoTargetIdSchema = z
-    .number()
-    .positive()
-    .refine((id) => Number.isInteger(id) || /^[1-9]\d*\.[1-9]$/.test(String(id)), "ID must be a root number or child number such as 1 or 1.1");
 // TodoHook Tool Schema
-export const TodoReadOperationSchema = z
+//
+// `read` is a discriminated union on `scope`, so an impossible combination
+// cannot be written at all: `target` exists only alongside `scope: "item"`,
+// `"children"` and `"root"`, none of which is valid without one. `.strict()`
+// on every member is what enforces that — without it
+// `{ scope: "all", target: 1 }` would parse and silently ignore `target`.
+//
+// An omitted `scope` defaults to "all", so a bare `{ operation: "read" }` keeps
+// behaving exactly as it did before this option existed. That default has to
+// live on the discriminator itself; a member without `scope` is rejected at
+// construction time.
+const readOperation = z
+    .literal("read")
+    .describe("'read' to inspect current todos.");
+export const TodoReadAllSchema = z
     .object({
-    operation: z.literal("read").describe("'read' to inspect current todos."),
+    operation: readOperation,
+    scope: z
+        .literal("all")
+        .default("all")
+        .describe("Default. Return the whole list."),
 })
     .strict();
+export const TodoReadItemSchema = z
+    .object({
+    operation: readOperation,
+    scope: z.literal("item").describe("Return only the targeted item."),
+    target: TodoTargetIdSchema.describe("Root or child todo id, e.g. 1 or 1.1."),
+})
+    .strict();
+export const TodoReadChildrenSchema = z
+    .object({
+    operation: readOperation,
+    scope: z
+        .literal("children")
+        .describe("Return one root and its subtasks. The root is included as context."),
+    target: ChildIdSchema.describe("A subtask id such as 1.1; its root is resolved from the id."),
+})
+    .strict();
+export const TodoReadRootSchema = z
+    .object({
+    operation: readOperation,
+    scope: z
+        .literal("root")
+        .describe("Return exactly one root together with all of its subtasks."),
+    target: RootIdSchema.describe("Root todo id, e.g. 1."),
+})
+    .strict();
+export const TodoReadOperationSchema = z.discriminatedUnion("scope", [
+    TodoReadAllSchema,
+    TodoReadItemSchema,
+    TodoReadChildrenSchema,
+    TodoReadRootSchema,
+]);
 export const TodoWriteOperationSchema = z
     .object({
     operation: z
         .literal("write")
-        .describe("'write' to initialize an empty list."),
+        .describe("'write' to replace the whole list. Pass [] to clear it."),
     todos: TodoListSchema.describe("Required for 'write'. Pass [] to clear the list."),
 })
     .strict();
 export const TodoUpdateOperationSchema = z
     .object({
     operation: z.literal("update").describe("'update' one root or child todo."),
-    id: TodoTargetIdSchema.describe("Root or child todo ID, e.g. 1 or 1.1"),
+    id: TodoTargetIdSchema,
     status: TodoStatusSchema.describe("New status for the target todo."),
     content: z.string().optional(),
     priority: PrioritySchema.nullable().optional(),
@@ -108,5 +163,5 @@ export const TodoInputToolSchema = z.discriminatedUnion("operation", [
     TodoUpdateOperationSchema,
 ]);
 export const TodoOutputToolSchema = z.object({
-    todos: z.array(TodoRootItemSchema),
+    todos: TodoListSchema,
 });

package/dist/storage/db.d.ts

@@ -0,0 +1,71 @@
+import { Database as BunDatabase } from "bun:sqlite";
+import { type SQLiteBunDatabase } from "drizzle-orm/bun-sqlite";
+/**
+ * Database connection for todo storage.
+ *
+ * One file holds every session; rows are partitioned by `session_key`. Two
+ * separate OpenCode processes reach the same file:
+ *
+ *   - the server process runs `manage_todo_list` and writes
+ *   - the CLI process renders the TUI widget and reads
+ *
+ * They share no memory, so the PRAGMAs below are not decoration:
+ *
+ *   - `journal_mode = WAL` lets a reader work while a writer commits
+ *   - `busy_timeout` makes a concurrent writer wait instead of failing
+ *   - `foreign_keys = ON` is per-connection in SQLite, so it must be set on
+ *     every open or the composite parent/child constraint silently stops
+ *     being enforced
+ *
+ * PRAGMAs run before `migrate()` so the migration itself benefits from WAL and
+ * enforced foreign keys.
+ *
+ * `run` is used rather than `exec`: in `bun:sqlite` they are the same call, but
+ * `exec` is deprecated in favour of `run`, and a deprecated alias on the hot
+ * path is noise in every build.
+ */
+/**
+ * No relations generic: this schema is queried with the core builder
+ * (`select`/`insert`/`update`/`delete`), never with relational `db.query`.
+ * Drizzle 1.0 dropped `schema` from the SQLite config for that reason, so there
+ * is nothing to thread through here.
+ */
+export type TodoDatabase = SQLiteBunDatabase;
+export interface TodoDatabaseHandle {
+    /** Raw connection, for statements Drizzle does not expose (e.g. PRAGMA). */
+    readonly sqlite: BunDatabase;
+    readonly db: TodoDatabase;
+    readonly path: string;
+}
+/**
+ * Folder holding the generated migrations.
+ *
+ * `import.meta.dirname` resolves to the plugin's own directory because OpenCode
+ * loads local plugins as ordinary files from disk (not embedded in the host
+ * binary). That was verified against a standalone Bun host importing an
+ * external plugin: `import.meta.dirname` pointed at the real folder.
+ *
+ * At runtime this file lives in `dist/storage/`, so the migrations folder sits
+ * two levels up at the package root. Each migration is its own timestamped
+ * subfolder holding `migration.sql` — the layout `drizzle-kit` 1.0 emits and
+ * the migrator reads back.
+ */
+export declare function resolveMigrationsFolder(): string;
+export declare function openDatabase(path: string, migrationsFolder?: string): TodoDatabaseHandle;
+/**
+ * Process-wide singleton.
+ *
+ * Opening is not free: it applies migrations and sets up WAL. The tool and the
+ * widget each call this repeatedly, so the connection is created once per
+ * process. `resetDatabaseForTests` exists for tests that need a fresh handle.
+ */
+export declare function getDatabase(path: string): TodoDatabaseHandle;
+export declare function resetDatabaseForTests(): void;
+/**
+ * SQLite's cross-connection change counter.
+ *
+ * `PRAGMA data_version` changes when *another* connection commits, and stays
+ * put for this connection's own writes. That is exactly the signal a reader
+ * wants, so the TUI can poll it and skip work when nothing external changed.
+ */
+export declare function getDataVersion(sqlite: BunDatabase): number;

package/dist/storage/db.js

@@ -0,0 +1,59 @@
+import { Database as BunDatabase } from "bun:sqlite";
+import { drizzle } from "drizzle-orm/bun-sqlite";
+import { migrate } from "drizzle-orm/bun-sqlite/migrator";
+import { mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+let handle;
+/**
+ * Folder holding the generated migrations.
+ *
+ * `import.meta.dirname` resolves to the plugin's own directory because OpenCode
+ * loads local plugins as ordinary files from disk (not embedded in the host
+ * binary). That was verified against a standalone Bun host importing an
+ * external plugin: `import.meta.dirname` pointed at the real folder.
+ *
+ * At runtime this file lives in `dist/storage/`, so the migrations folder sits
+ * two levels up at the package root. Each migration is its own timestamped
+ * subfolder holding `migration.sql` — the layout `drizzle-kit` 1.0 emits and
+ * the migrator reads back.
+ */
+export function resolveMigrationsFolder() {
+    return join(import.meta.dirname, "..", "..", "drizzle");
+}
+export function openDatabase(path, migrationsFolder = resolveMigrationsFolder()) {
+    mkdirSync(dirname(path), { recursive: true });
+    const sqlite = new BunDatabase(path, { create: true });
+    sqlite.run("PRAGMA journal_mode = WAL");
+    sqlite.run("PRAGMA synchronous = NORMAL");
+    sqlite.run("PRAGMA busy_timeout = 5000");
+    sqlite.run("PRAGMA cache_size = -64000");
+    sqlite.run("PRAGMA foreign_keys = ON");
+    const db = drizzle({ client: sqlite });
+    migrate(db, { migrationsFolder });
+    return { sqlite, db, path };
+}
+/**
+ * Process-wide singleton.
+ *
+ * Opening is not free: it applies migrations and sets up WAL. The tool and the
+ * widget each call this repeatedly, so the connection is created once per
+ * process. `resetDatabaseForTests` exists for tests that need a fresh handle.
+ */
+export function getDatabase(path) {
+    return (handle ??= openDatabase(path));
+}
+export function resetDatabaseForTests() {
+    handle?.sqlite.close();
+    handle = undefined;
+}
+/**
+ * SQLite's cross-connection change counter.
+ *
+ * `PRAGMA data_version` changes when *another* connection commits, and stays
+ * put for this connection's own writes. That is exactly the signal a reader
+ * wants, so the TUI can poll it and skip work when nothing external changed.
+ */
+export function getDataVersion(sqlite) {
+    const row = sqlite.query("PRAGMA data_version").get();
+    return row?.data_version ?? 0;
+}

package/dist/storage/migrate-json.d.ts

@@ -0,0 +1,82 @@
+import { type TodoRootItem } from "../schemas/todo";
+import type { TodoDatabaseHandle } from "./db";
+/**
+ * One-time import of the legacy per-session JSON files into SQLite, plus the
+ * shared write primitive every caller uses.
+ *
+ * The old layout kept one file per session:
+ *
+ *   <base>/s_<hash>/todos/todos-<timestamp>.json
+ *   <base>/s_<hash>/todos/version
+ *
+ * Design rules:
+ *
+ * - **Never delete data.** A file is renamed to `.json.migrated` only after the
+ *   transaction committed, so a crash mid-import leaves the original intact.
+ * - **Idempotent.** Importing a session that already holds rows is refused
+ *   rather than merged, so a partial import cannot silently duplicate items.
+ * - **Validated.** JSON is checked with the same `TodoListSchema` the tool
+ *   uses, so a corrupt legacy file fails loudly here instead of producing a
+ *   half-valid database.
+ */
+export interface MigrationResult {
+    readonly imported: string[];
+    readonly skipped: string[];
+    readonly failed: {
+        file: string;
+        error: string;
+    }[];
+}
+/** `todos-<ts>.json` holds the payload; `version` holds the counter. */
+export declare function readLegacyVersion(sessionDir: string): number;
+/** Newest payload file wins, matching the old "latest wins" behaviour. */
+export declare function findLegacyTodoFile(sessionDir: string): string | undefined;
+/** Parses a legacy payload, accepting the wrapped object and the bare array. */
+export declare function parseLegacyTodos(raw: string): TodoRootItem[];
+/**
+ * Replaces a session's whole list in one transaction.
+ *
+ * Used by both the importer and every normal write, so ordering (`position`)
+ * and atomicity are identical everywhere.
+ *
+ * `behavior: "immediate"` takes the write lock before reading, so two
+ * processes cannot both observe an old revision and then write rows that
+ * conflict. Combined with `busy_timeout` the second writer waits instead of
+ * failing.
+ */
+export declare function replaceSessionTodos(handle: TodoDatabaseHandle, sessionKey: string, todos: readonly TodoRootItem[]): number;
+/** Reads a session's revision, or 0 when the session has never been written. */
+export declare function readRevision(handle: TodoDatabaseHandle, sessionKey: string): number;
+/**
+ * Read-modify-write under one `IMMEDIATE` transaction.
+ *
+ * Every write goes through here so the read, the caller's transform, and the
+ * replacement cannot interleave with another process's write. Reading outside
+ * the transaction and writing inside it would allow a lost update: two
+ * processes could each read revision N, then both write revision N+1, and one
+ * change would silently disappear.
+ *
+ * The transform receives the current list and returns the next one; validation
+ * happens inside the transaction so an invalid result rolls the whole thing
+ * back without bumping the revision.
+ */
+export declare function mutateSessionTodos(handle: TodoDatabaseHandle, sessionKey: string, transform: (current: TodoRootItem[]) => TodoRootItem[]): {
+    todos: TodoRootItem[];
+    revision: number;
+};
+/** Reads a session's list in `position` order, rebuilt into the nested shape. */
+export declare function selectTodos(executor: Pick<TodoDatabaseHandle["db"], "select">, sessionKey: string): TodoRootItem[];
+/**
+ * Writes the full list for a session inside a transaction, without opening one.
+ *
+ * Kept separate so `mutateSessionTodos` can compose it with a read in the same
+ * transaction.
+ */
+export declare function writeSessionTodos(tx: Pick<TodoDatabaseHandle["db"], "select" | "insert" | "update" | "delete">, sessionKey: string, todos: readonly TodoRootItem[]): number;
+/**
+ * Scans every session folder under `baseDir` and imports the legacy JSON.
+ *
+ * Safe to run on every startup: sessions already present in SQLite are
+ * skipped, and consumed files no longer match the payload pattern.
+ */
+export declare function importLegacyJson(handle: TodoDatabaseHandle, baseDir: string): MigrationResult;

package/dist/storage/migrate-json.js

@@ -0,0 +1,278 @@
+import { readFileSync, readdirSync, renameSync } from "node:fs";
+import { join } from "node:path";
+import { asc, eq } from "drizzle-orm";
+import { TodoListSchema } from "../schemas/todo.js";
+import { InvalidTodoDataError } from "./errors.js";
+import { todoItem, todoSession } from "./schema.js";
+const FILE_PREFIX = "todos-";
+const FILE_SUFFIX = ".json";
+const MIGRATED_SUFFIX = ".json.migrated";
+/** `todos-<ts>.json` holds the payload; `version` holds the counter. */
+export function readLegacyVersion(sessionDir) {
+    for (const candidate of [
+        join(sessionDir, "version"),
+        join(sessionDir, "todos", "version"),
+    ]) {
+        try {
+            const value = Number.parseInt(readFileSync(candidate, "utf8").trim(), 10);
+            if (Number.isSafeInteger(value) && value >= 0)
+                return value;
+        }
+        catch {
+            // try the next candidate
+        }
+    }
+    return 0;
+}
+/** Newest payload file wins, matching the old "latest wins" behaviour. */
+export function findLegacyTodoFile(sessionDir) {
+    for (const dir of [join(sessionDir, "todos"), sessionDir]) {
+        let names;
+        try {
+            names = readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        const newest = names
+            .filter((name) => name.startsWith(FILE_PREFIX) && name.endsWith(FILE_SUFFIX))
+            .map((name) => ({
+            path: join(dir, name),
+            timestamp: Number(name.slice(FILE_PREFIX.length, -FILE_SUFFIX.length)),
+        }))
+            .filter((entry) => Number.isSafeInteger(entry.timestamp) && entry.timestamp >= 0)
+            .sort((left, right) => right.timestamp - left.timestamp)[0];
+        if (newest)
+            return newest.path;
+    }
+    return undefined;
+}
+/** Parses a legacy payload, accepting the wrapped object and the bare array. */
+export function parseLegacyTodos(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new InvalidTodoDataError(`[todo store read failed] invalid todo data: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const list = Array.isArray(parsed)
+        ? parsed
+        : typeof parsed === "object" && parsed !== null && "todos" in parsed
+            ? parsed.todos
+            : undefined;
+    if (!Array.isArray(list)) {
+        throw new InvalidTodoDataError("[todo store read failed] invalid todo data: todo list is missing");
+    }
+    const result = TodoListSchema.safeParse(list);
+    if (!result.success) {
+        throw new InvalidTodoDataError(`[todo store read failed] invalid todo data: ${result.error.issues
+            .map((issue) => issue.message)
+            .join(", ")}`);
+    }
+    return result.data;
+}
+/**
+ * Replaces a session's whole list in one transaction.
+ *
+ * Used by both the importer and every normal write, so ordering (`position`)
+ * and atomicity are identical everywhere.
+ *
+ * `behavior: "immediate"` takes the write lock before reading, so two
+ * processes cannot both observe an old revision and then write rows that
+ * conflict. Combined with `busy_timeout` the second writer waits instead of
+ * failing.
+ */
+export function replaceSessionTodos(handle, sessionKey, todos) {
+    return handle.db.transaction((tx) => writeSessionTodos(tx, sessionKey, todos), { behavior: "immediate" });
+}
+/** Reads a session's revision, or 0 when the session has never been written. */
+export function readRevision(handle, sessionKey) {
+    const row = handle.db
+        .select({ revision: todoSession.revision })
+        .from(todoSession)
+        .where(eq(todoSession.sessionKey, sessionKey))
+        .get();
+    return row?.revision ?? 0;
+}
+/**
+ * Read-modify-write under one `IMMEDIATE` transaction.
+ *
+ * Every write goes through here so the read, the caller's transform, and the
+ * replacement cannot interleave with another process's write. Reading outside
+ * the transaction and writing inside it would allow a lost update: two
+ * processes could each read revision N, then both write revision N+1, and one
+ * change would silently disappear.
+ *
+ * The transform receives the current list and returns the next one; validation
+ * happens inside the transaction so an invalid result rolls the whole thing
+ * back without bumping the revision.
+ */
+export function mutateSessionTodos(handle, sessionKey, transform) {
+    return handle.db.transaction((tx) => {
+        const todos = selectTodos(tx, sessionKey);
+        const next = transform(todos);
+        const revision = writeSessionTodos(tx, sessionKey, next);
+        return { todos: next, revision };
+    }, { behavior: "immediate" });
+}
+/** Reads a session's list in `position` order, rebuilt into the nested shape. */
+export function selectTodos(executor, sessionKey) {
+    const rows = executor
+        .select()
+        .from(todoItem)
+        .where(eq(todoItem.sessionKey, sessionKey))
+        .orderBy(asc(todoItem.position))
+        .all();
+    const roots = new Map();
+    const order = [];
+    for (const row of rows) {
+        const base = {
+            id: Number(row.id),
+            content: row.content,
+            status: row.status,
+            ...(row.priority ? { priority: row.priority } : {}),
+            ...(row.note !== null && row.note !== undefined ? { note: row.note } : {}),
+        };
+        if (row.parentId === null) {
+            roots.set(row.id, base);
+            order.push(row.id);
+            continue;
+        }
+        const parent = roots.get(row.parentId);
+        if (!parent)
+            continue; // orphan; the foreign key prevents this
+        parent.children ??= [];
+        parent.children.push(base);
+    }
+    return order.map((id) => roots.get(id));
+}
+/**
+ * Writes the full list for a session inside a transaction, without opening one.
+ *
+ * Kept separate so `mutateSessionTodos` can compose it with a read in the same
+ * transaction.
+ */
+export function writeSessionTodos(tx, sessionKey, todos) {
+    const now = new Date().toISOString();
+    const existing = tx
+        .select({
+        revision: todoSession.revision,
+        createdAt: todoSession.createdAt,
+    })
+        .from(todoSession)
+        .where(eq(todoSession.sessionKey, sessionKey))
+        .get();
+    const revision = (existing?.revision ?? 0) + 1;
+    const createdAt = existing?.createdAt ?? now;
+    // A clear keeps the session row and still bumps the revision: the row holds
+    // `revision` and `hint_revision`, so dropping it would reset the change
+    // counter a reader polls and could re-emit an already-delivered hint. Only
+    // the items are removed, which the delete below does for every write.
+    if (existing) {
+        tx.update(todoSession)
+            .set({ revision, updatedAt: now })
+            .where(eq(todoSession.sessionKey, sessionKey))
+            .run();
+    }
+    else {
+        tx.insert(todoSession)
+            .values({ sessionKey, revision, createdAt, updatedAt: now })
+            .run();
+    }
+    // Replace rather than diff: callers always supply the full list, and
+    // delete-then-insert keeps `position` dense with no extra bookkeeping.
+    tx.delete(todoItem).where(eq(todoItem.sessionKey, sessionKey)).run();
+    let position = 0;
+    const rows = todos.flatMap((root) => {
+        const rootRow = {
+            sessionKey,
+            id: String(root.id),
+            parentId: null,
+            content: root.content,
+            status: root.status,
+            priority: root.priority ?? null,
+            note: root.note ?? null,
+            position: position++,
+        };
+        const childRows = (root.children ?? []).map((child) => ({
+            sessionKey,
+            id: String(child.id),
+            parentId: String(root.id),
+            content: child.content,
+            status: child.status,
+            priority: child.priority ?? null,
+            note: child.note ?? null,
+            position: position++,
+        }));
+        return [rootRow, ...childRows];
+    });
+    // Roots precede their children so the composite self-reference resolves
+    // within the same transaction.
+    if (rows.length > 0)
+        tx.insert(todoItem).values(rows).run();
+    return revision;
+}
+/**
+ * Imports one session folder. Returns what happened so the caller can report
+ * it; throws only on an unexpected filesystem error.
+ */
+function importSession(handle, sessionKey, sessionDir) {
+    const file = findLegacyTodoFile(sessionDir);
+    if (!file)
+        return "empty";
+    const todos = parseLegacyTodos(readFileSync(file, "utf8"));
+    // Refuse to merge into a session that already has rows: a second import
+    // would duplicate items, and silently merging is worse than skipping.
+    if (readRevision(handle, sessionKey) > 0)
+        return "skipped";
+    replaceSessionTodos(handle, sessionKey, todos);
+    // Only now is it safe to mark the source as consumed.
+    renameSync(file, file.replace(/\.json$/, MIGRATED_SUFFIX));
+    return "imported";
+}
+/**
+ * Scans every session folder under `baseDir` and imports the legacy JSON.
+ *
+ * Safe to run on every startup: sessions already present in SQLite are
+ * skipped, and consumed files no longer match the payload pattern.
+ */
+export function importLegacyJson(handle, baseDir) {
+    const result = { imported: [], skipped: [], failed: [] };
+    let entries;
+    try {
+        entries = readdirSync(baseDir);
+    }
+    catch {
+        return result;
+    }
+    for (const name of entries) {
+        const sessionDir = join(baseDir, name);
+        let file;
+        try {
+            file = findLegacyTodoFile(sessionDir);
+            if (!file)
+                continue;
+        }
+        catch {
+            continue;
+        }
+        // The hashed folder name is the session key; the legacy plaintext layout
+        // used the raw session id, which is also a valid key.
+        const sessionKey = name;
+        try {
+            const outcome = importSession(handle, sessionKey, sessionDir);
+            if (outcome === "imported")
+                result.imported.push(file);
+            else if (outcome === "skipped")
+                result.skipped.push(file);
+        }
+        catch (error) {
+            result.failed.push({
+                file,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return result;
+}