@gamflaz/opencode-todolist 1.0.12 → 1.1.1

package/dist/storage/schema.js

@@ -0,0 +1,108 @@
+import { index, integer, primaryKey, sqliteTable, text, uniqueIndex, foreignKey, } from "drizzle-orm/sqlite-core";
+/**
+ * Relational storage for todos.
+ *
+ * Layout: one database file holds every session. Rows are partitioned by
+ * `session_key`, the OpenCode session id, so a session's data never leaks into
+ * another session's queries while still sharing one connection. Rows written by
+ * an older build keyed by a SHA-256 digest of that id are still found through
+ * `TodoStore.legacyKey`, which recomputes the same digest.
+ *
+ * Why a database instead of the previous per-session JSON files:
+ * - foreign keys make parent/child integrity structural instead of validated
+ *   after the fact
+ * - transactions make a multi-row write atomic, so a reader can never observe
+ *   a half-written list
+ * - `PRAGMA data_version` gives cross-process change detection, which is what
+ *   the TUI needs (the tool and the widget run in separate processes)
+ *
+ * `id` is TEXT, not INTEGER: child ids are dotted values such as `1.1`, and
+ * storing them as numbers would lose the shape. `position` carries ordering;
+ * ids are stable identifiers only.
+ */
+/** One row per OpenCode session that has ever stored a todo list. */
+export const todoSession = sqliteTable("todo_session", {
+    sessionKey: text("session_key").primaryKey(),
+    /** Bumped on every write; readers poll `PRAGMA data_version` to detect it. */
+    revision: integer("revision").notNull().default(0),
+    /** Revision at which the resume hint was last injected, so it fires once. */
+    hintRevision: integer("hint_revision").notNull().default(0),
+    createdAt: text("created_at").notNull(),
+    updatedAt: text("updated_at").notNull(),
+});
+/** One row per todo item: a root when `parent_id` is NULL, otherwise a child. */
+export const todoItem = sqliteTable("todo_item", {
+    sessionKey: text("session_key")
+        .notNull()
+        .references(() => todoSession.sessionKey, { onDelete: "cascade" }),
+    id: text("id").notNull(),
+    /** NULL for a root; the parent's `id` for a subtask. */
+    parentId: text("parent_id"),
+    content: text("content").notNull(),
+    status: text("status").$type().notNull(),
+    priority: text("priority").$type(),
+    note: text("note"),
+    /** Render order within the session. */
+    position: integer("position").notNull(),
+}, (t) => [
+    primaryKey({ columns: [t.sessionKey, t.id] }),
+    // Composite self-reference: the parent must live in the same session, so a
+    // child can never point at another session's item.
+    foreignKey({
+        columns: [t.sessionKey, t.parentId],
+        foreignColumns: [t.sessionKey, t.id],
+    }).onDelete("cascade"),
+    index("todo_item_session_position_idx").on(t.sessionKey, t.position),
+]);
+/** Free-form labels. Present so tagging does not need a later migration. */
+export const tag = sqliteTable("tag", {
+    id: text("id").primaryKey(),
+    name: text("name").notNull().unique(),
+});
+/** Many-to-many between items and labels. */
+export const todoItemTag = sqliteTable("todo_item_tag", {
+    sessionKey: text("session_key").notNull(),
+    todoId: text("todo_id").notNull(),
+    tagId: text("tag_id").notNull(),
+}, (t) => [
+    primaryKey({ columns: [t.sessionKey, t.todoId, t.tagId] }),
+    foreignKey({
+        columns: [t.sessionKey, t.todoId],
+        foreignColumns: [todoItem.sessionKey, todoItem.id],
+    }).onDelete("cascade"),
+    foreignKey({
+        columns: [t.tagId],
+        foreignColumns: [tag.id],
+    }).onDelete("cascade"),
+    index("todo_item_tag_tag_idx").on(t.tagId),
+]);
+/**
+ * Ordering constraints between items in the same session.
+ *
+ * Not enforced by the tool yet; the table exists so the storage layer does not
+ * need a schema change when dependency support lands.
+ */
+export const todoItemDependency = sqliteTable("todo_item_dependency", {
+    sessionKey: text("session_key").notNull(),
+    todoId: text("todo_id").notNull(),
+    dependsOnId: text("depends_on_id").notNull(),
+}, (t) => [
+    primaryKey({ columns: [t.sessionKey, t.todoId, t.dependsOnId] }),
+    foreignKey({
+        columns: [t.sessionKey, t.todoId],
+        foreignColumns: [todoItem.sessionKey, todoItem.id],
+    }).onDelete("cascade"),
+    foreignKey({
+        columns: [t.sessionKey, t.dependsOnId],
+        foreignColumns: [todoItem.sessionKey, todoItem.id],
+    }).onDelete("cascade"),
+    uniqueIndex("todo_item_dependency_pair_idx").on(t.sessionKey, t.todoId, t.dependsOnId),
+    index("todo_item_dependency_depends_on_idx").on(t.sessionKey, t.dependsOnId),
+]);
+export const schema = {
+    todoSession,
+    todoItem,
+    tag,
+    todoItemTag,
+    todoItemDependency,
+};

package/dist/storage/todo-store.d.ts

@@ -1,7 +1,27 @@
-import { type TodoRootItem } from "../schemas/todo";
+import type { TodoRootItem } from "../schemas/todo";
 /**
- * Environment/OS context used to resolve storage locations. All fields are
- * optional so callers (and tests) can simulate any platform on any host.
+ * Per-session todo persistence on SQLite.
+ *
+ * Storage shape:
+ *
+ *   <base>/todos.db          one file, every session, partitioned by session_key
+ *   <base>/todos.db-wal      write-ahead log
+ *
+ * The public API is unchanged from the previous JSON implementation, so the
+ * tool, the hint builder, and the TUI widget keep working without edits. Only
+ * the storage engine moved.
+ *
+ * Why SQLite here:
+ * - `parent_id` becomes a real foreign key, so a subtask cannot dangle
+ * - a full-list write is one transaction, so a reader never sees a half list
+ * - `PRAGMA data_version` lets the TUI detect writes made by the other process
+ *
+ * The tool and the widget run in separate processes, so nothing is shared in
+ * memory and this file is the hand-off point.
+ */
+/**
+ * Environment/OS context used to resolve storage locations. Every field is
+ * optional so callers and tests can simulate any platform on any host.
  */
 export interface PlatformContext {
     platform?: NodeJS.Platform;
@@ -14,89 +34,113 @@ export interface TodoData {
     created_at: string;
     updated_at: string;
 }
-/**
- * Per-session todo persistence.
- *
- * Layout (per session):
- *   <base>/s_<hash>/todos/todos-<timestamp>.json   todo payload (latest wins)
- *   <base>/s_<hash>/todos/version                  monotonically increasing version
- *   <base>/s_<hash>/todos/id                       hashed session folder name
- *   <base>/s_<hash>/todos/todos.lock               cross-process lock
- *   <base>/s_<hash>/todos/hint-marker.json         hint injection marker
- */
 export declare class TodoStore {
     private readonly ctx;
     private static readonly SESSION_ID_PATTERN;
-    private static readonly FILE_PREFIX;
-    private static readonly FILE_SUFFIX;
+    private handle;
+    private importedBaseDir;
     constructor(ctx?: PlatformContext);
     static isMissingFile(error: unknown): boolean;
     static normalizeSessionID(sessionID: string): string;
     /**
-     * Deterministic cryptographic hash of sessionID.
-     * Produces an opaque 32-character hexadecimal folder name prefixed with "s_".
-     * Prevents raw sessionIDs from leaking in the filesystem structure.
+     * Storage partition key for a session: the OpenCode session id verbatim.
+     *
+     * The id is already unique and `normalizeSessionID` already restricts it to
+     * `[A-Za-z0-9_-]`, so hashing it bought nothing and cost readability — a raw
+     * id can be traced back to a session by eye, a digest cannot.
      */
+    static sessionKey(sessionID: string): string;
+    /**
+     * The key older builds used for this session, kept so their rows still work.
+     *
+     * A SHA-256 digest cannot be reversed, so a stored hash can never be turned
+     * back into an id. It does not need to be: hashing is deterministic, so given
+     * the id we recompute the same digest and find the old row, which is what
+     * `resolveKey` does. A session that already has rows keeps its old key; only
+     * sessions that are new get the readable one.
+     */
+    static legacyKey(sessionID: string): string;
+    /** @deprecated Use {@link TodoStore.legacyKey}; kept for existing callers. */
     static hashSessionID(sessionID: string): string;
-    private static setPrivateMode;
     private get env();
     private get platform();
     private joinForPlatform;
-    /**
-     * Cross-platform home directory resolution.
-     *
-     * `os.homedir()` already adapts to the OS, but it can return an empty string
-     * in stripped environments, and Windows shells sometimes expose a
-     * POSIX-style `HOME` (e.g. Git Bash `/c/Users/...`). We therefore prefer the
-     * canonical variable for the running platform before falling back.
-     *
-     * @see {@link https://nodejs.org/api/os.html#oshomedir}
-     */
     resolveHomeDir(): string;
-    /**
-     * Platform-native base directory for user configuration/data.
-     *
-     * - Windows : `%APPDATA%` (fallback `%LOCALAPPDATA%` → `~/AppData/Roaming`)
-     * - macOS   : `~/Library/Application Support`
-     * - Linux   : `$XDG_CONFIG_HOME` (fallback `~/.config`)
-     *
-     * `XDG_CONFIG_HOME` is honored first on every platform so users who prefer an
-     * XDG layout (including those running OpenCode's own convention) can force it.
-     */
     resolveConfigHome(): string;
     /**
-     * Base directory that stores per-session todo folders.
+     * Base directory holding the database and the legacy session folders.
      *
      * Priority:
-     *   1. `OPENCODE_TODOS_DIR` — explicit plugin override (tests/tooling).
-     *   2. The user's home directory + `.opencode/sessions`.
+     *   1. `OPENCODE_TODOS_DIR` — explicit override for tests and tooling.
+     *   2. `<home>/.opencode/sessions`
      */
     resolveTodosBaseDir(): string;
-    /** Base directory for all sessions (replaces the old `TODOS_DIRECTORY` const). */
     get todosRoot(): string;
+    getDatabasePath(): string;
+    /**
+     * Legacy per-session directory.
+     *
+     * No longer written to. Kept because it is still read once to import old JSON
+     * and because the TUI watches this directory for filesystem changes.
+     */
     getSessionDirectory(sessionID: string): string;
     getTodosDirectory(sessionID?: string): string;
-    getTodoLockPath(sessionID: string): string;
+    /**
+     * Path of the legacy hint marker.
+     *
+     * The marker now lives in `todo_session.hint_revision`, so nothing writes
+     * here. The path is still exposed because callers may need to locate and
+     * clean up a leftover file from an older install.
+     */
     getHintMarkerPath(sessionID: string): string;
-    getSessionIDFilePath(sessionID: string): string;
-    getVersionFilePath(sessionID: string): string;
-    getTodoFilePath(sessionID: string): string;
+    private database;
+    private key;
+    /**
+     * Resolves the key a session's rows currently live under.
+     *
+     * Prefers the real session id. A session first written by an older build
+     * still sits under its hashed key, so that is checked as a fallback — without
+     * it, upgrading would look like every todo list had vanished.
+     */
+    private resolveKey;
+    /**
+     * Reads a session's list.
+     *
+     * Synchronous at its core because `bun:sqlite` is synchronous; the `async`
+     * signature is kept so existing callers do not need to change.
+     */
     readTodos(sessionID: string): Promise<TodoRootItem[]>;
     readTodosSync(sessionID: string): TodoRootItem[];
     readTodoData(sessionID: string): TodoData | null;
+    /** Revision counter, used by the TUI to detect changes cheaply. */
+    getRevision(sessionID: string): number;
+    /**
+     * Reads the hint marker value and, when it is stale, records the new
+     * revision. Returns the previous revision so the caller can decide.
+     */
+    takeHintRevision(sessionID: string, currentRevision: number): number;
+    /** Cross-process change signal for the TUI watcher. */
+    getDataVersion(): number;
+    migrationsFolder(): string;
     writeTodos(sessionID: string, todos: TodoRootItem[]): Promise<void>;
     updateTodos(sessionID: string, update: (todos: TodoRootItem[]) => TodoRootItem[]): Promise<TodoRootItem[]>;
-    private scanTodoFiles;
-    private listSessionFiles;
-    private readVersionFile;
-    private static parseTodoFile;
-    /** Shared error policy for readTodos / readTodosSync. */
-    private recoverFromReadError;
-    private writeTextAtomically;
-    private writeJsonAtomically;
-    private migrateFlatTodoFiles;
+    /** Replaces a list without running the tree validation (import path). */
+    replaceTodosSync(sessionID: string, todos: TodoRootItem[]): void;
+    /**
+     * Drops the cached connection so the next call reopens from scratch.
+     *
+     * Only for tests: the store deliberately caches one connection per process
+     * (opening applies migrations and sets up WAL, which is not free). A test
+     * that points `OPENCODE_TODOS_DIR` at a new directory must reset, otherwise
+     * the previous connection keeps servicing the old, unlinked file.
+     */
+    resetForTests(): void;
 }
 export declare const getTodosDirectory: (sessionID?: string) => string;
+export declare const getDatabasePath: () => string;
+export declare const sessionKey: (sessionID: string) => string;
+export declare const legacySessionKey: (sessionID: string) => string;
+/** @deprecated Use {@link legacySessionKey}; the hash is no longer the key. */
 export declare const hashSessionID: (sessionID: string) => string;
 export declare const readTodos: (sessionID: string) => Promise<{
     id: number;
@@ -143,3 +187,7 @@ export declare const updateTodos: (sessionID: string, update: (todos: TodoRootIt
 }[]>;
 export declare const readTodoData: (sessionID: string) => TodoData | null;
 export declare const getHintMarkerPath: (sessionID: string) => string;
+export declare const getRevision: (sessionID: string) => number;
+export declare const takeHintRevision: (sessionID: string, revision: number) => number;
+export declare const getDataVersion: () => number;
+export declare const resetTodoStoreForTests: () => void;