@gamflaz/opencode-todolist 1.0.12 → 1.1.1

package/dist/schemas/todo.d.ts

@@ -1,5 +1,9 @@
 import z from "zod";
-export declare const TodoChildernItemSchema: z.ZodObject<{
+/** A top-level id only: `1`, `2`, ... — never a dotted subtask id. */
+export declare const RootIdSchema: z.ZodNumber;
+export declare const ChildIdSchema: z.ZodNumber;
+export declare const TodoTargetIdSchema: z.ZodUnion<readonly [z.ZodNumber, z.ZodNumber]>;
+export declare const TodoChildrenItemSchema: z.ZodObject<{
     id: z.ZodNumber;
     content: z.ZodString;
     status: z.ZodEnum<{
@@ -15,8 +19,7 @@ export declare const TodoChildernItemSchema: z.ZodObject<{
         medium: "medium";
     }>>;
     note: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-export type TodoChildern = z.infer<typeof TodoChildernItemSchema>;
+}, z.core.$strict>;
 export declare const TodoRootItemSchema: z.ZodObject<{
     id: z.ZodNumber;
     content: z.ZodString;
@@ -49,9 +52,8 @@ export declare const TodoRootItemSchema: z.ZodObject<{
             medium: "medium";
         }>>;
         note: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>>;
-}, z.core.$strip>;
-export type TodoRootItem = z.infer<typeof TodoRootItemSchema>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
 export declare const formatRootId: (id: number) => string;
 export declare const formatChildId: (id: number) => string;
 export declare const TodoListSchema: z.ZodArray<z.ZodObject<{
@@ -86,49 +88,43 @@ export declare const TodoListSchema: z.ZodArray<z.ZodObject<{
             medium: "medium";
         }>>;
         note: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>>;
-}, z.core.$strip>>;
-export declare const TodoWriteInputSchema: z.ZodObject<{
-    todos: z.ZodArray<z.ZodObject<{
-        id: z.ZodNumber;
-        content: z.ZodString;
-        status: z.ZodEnum<{
-            cancelled: "cancelled";
-            completed: "completed";
-            error: "error";
-            in_progress: "in_progress";
-            pending: "pending";
-        }>;
-        priority: z.ZodOptional<z.ZodEnum<{
-            high: "high";
-            low: "low";
-            medium: "medium";
-        }>>;
-        note: z.ZodOptional<z.ZodString>;
-        children: z.ZodOptional<z.ZodArray<z.ZodObject<{
-            id: z.ZodNumber;
-            content: z.ZodString;
-            status: z.ZodEnum<{
-                cancelled: "cancelled";
-                completed: "completed";
-                error: "error";
-                in_progress: "in_progress";
-                pending: "pending";
-            }>;
-            priority: z.ZodOptional<z.ZodEnum<{
-                high: "high";
-                low: "low";
-                medium: "medium";
-            }>>;
-            note: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>>>;
-    }, z.core.$strip>>;
-}, z.core.$strip>;
-export type TodoWriteInput = z.infer<typeof TodoWriteInputSchema>;
-export declare const TodoTargetIdSchema: z.ZodNumber;
-export declare const TodoReadOperationSchema: z.ZodObject<{
+    }, z.core.$strict>>>;
+}, z.core.$strict>>;
+export declare const TodoReadAllSchema: z.ZodObject<{
+    operation: z.ZodLiteral<"read">;
+    scope: z.ZodDefault<z.ZodLiteral<"all">>;
+}, z.core.$strict>;
+export declare const TodoReadItemSchema: z.ZodObject<{
     operation: z.ZodLiteral<"read">;
+    scope: z.ZodLiteral<"item">;
+    target: z.ZodUnion<readonly [z.ZodNumber, z.ZodNumber]>;
 }, z.core.$strict>;
+export declare const TodoReadChildrenSchema: z.ZodObject<{
+    operation: z.ZodLiteral<"read">;
+    scope: z.ZodLiteral<"children">;
+    target: z.ZodNumber;
+}, z.core.$strict>;
+export declare const TodoReadRootSchema: z.ZodObject<{
+    operation: z.ZodLiteral<"read">;
+    scope: z.ZodLiteral<"root">;
+    target: z.ZodNumber;
+}, z.core.$strict>;
+export declare const TodoReadOperationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    operation: z.ZodLiteral<"read">;
+    scope: z.ZodDefault<z.ZodLiteral<"all">>;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"read">;
+    scope: z.ZodLiteral<"item">;
+    target: z.ZodUnion<readonly [z.ZodNumber, z.ZodNumber]>;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"read">;
+    scope: z.ZodLiteral<"children">;
+    target: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"read">;
+    scope: z.ZodLiteral<"root">;
+    target: z.ZodNumber;
+}, z.core.$strict>], "scope">;
 export declare const TodoWriteOperationSchema: z.ZodObject<{
     operation: z.ZodLiteral<"write">;
     todos: z.ZodArray<z.ZodObject<{
@@ -163,12 +159,12 @@ export declare const TodoWriteOperationSchema: z.ZodObject<{
                 medium: "medium";
             }>>;
             note: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>>>;
-    }, z.core.$strip>>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 export declare const TodoUpdateOperationSchema: z.ZodObject<{
     operation: z.ZodLiteral<"update">;
-    id: z.ZodNumber;
+    id: z.ZodUnion<readonly [z.ZodNumber, z.ZodNumber]>;
     status: z.ZodEnum<{
         cancelled: "cancelled";
         completed: "completed";
@@ -184,10 +180,22 @@ export declare const TodoUpdateOperationSchema: z.ZodObject<{
     }>>>;
     note: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strict>;
-export type TodoUpdateInput = z.infer<typeof TodoUpdateOperationSchema>;
-export declare const TodoInputToolSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+export declare const TodoInputToolSchema: z.ZodDiscriminatedUnion<[z.ZodDiscriminatedUnion<[z.ZodObject<{
+    operation: z.ZodLiteral<"read">;
+    scope: z.ZodDefault<z.ZodLiteral<"all">>;
+}, z.core.$strict>, z.ZodObject<{
     operation: z.ZodLiteral<"read">;
+    scope: z.ZodLiteral<"item">;
+    target: z.ZodUnion<readonly [z.ZodNumber, z.ZodNumber]>;
 }, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"read">;
+    scope: z.ZodLiteral<"children">;
+    target: z.ZodNumber;
+}, z.core.$strict>, z.ZodObject<{
+    operation: z.ZodLiteral<"read">;
+    scope: z.ZodLiteral<"root">;
+    target: z.ZodNumber;
+}, z.core.$strict>], "scope">, z.ZodObject<{
     operation: z.ZodLiteral<"write">;
     todos: z.ZodArray<z.ZodObject<{
         id: z.ZodNumber;
@@ -221,11 +229,11 @@ export declare const TodoInputToolSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
                 medium: "medium";
             }>>;
             note: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>>>;
-    }, z.core.$strip>>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
 }, z.core.$strict>, z.ZodObject<{
     operation: z.ZodLiteral<"update">;
-    id: z.ZodNumber;
+    id: z.ZodUnion<readonly [z.ZodNumber, z.ZodNumber]>;
     status: z.ZodEnum<{
         cancelled: "cancelled";
         completed: "completed";
@@ -241,7 +249,6 @@ export declare const TodoInputToolSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     }>>>;
     note: z.ZodOptional<z.ZodNullable<z.ZodString>>;
 }, z.core.$strict>], "operation">;
-export type TodoInputTool = z.infer<typeof TodoInputToolSchema>;
 export declare const TodoOutputToolSchema: z.ZodObject<{
     todos: z.ZodArray<z.ZodObject<{
         id: z.ZodNumber;
@@ -275,7 +282,18 @@ export declare const TodoOutputToolSchema: z.ZodObject<{
                 medium: "medium";
             }>>;
             note: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>>>;
-    }, z.core.$strip>>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
 }, z.core.$strip>;
+export type TodoChildren = z.infer<typeof TodoChildrenItemSchema>;
+export type TodoRootItem = z.infer<typeof TodoRootItemSchema>;
+export type TodoReadAllInput = z.infer<typeof TodoReadAllSchema>;
+export type TodoReadItemInput = z.infer<typeof TodoReadItemSchema>;
+export type TodoReadChildrenInput = z.infer<typeof TodoReadChildrenSchema>;
+export type TodoReadRootInput = z.infer<typeof TodoReadRootSchema>;
+export type TodoReadInput = z.infer<typeof TodoReadOperationSchema>;
+export type TodoReadScope = TodoReadInput["scope"];
+export type TodoWriteOperationInput = z.infer<typeof TodoWriteOperationSchema>;
+export type TodoUpdateInput = z.infer<typeof TodoUpdateOperationSchema>;
+export type TodoInputTool = z.infer<typeof TodoInputToolSchema>;
 export type TodoOutputTool = z.infer<typeof TodoOutputToolSchema>;

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;