@zinn-dev/core 0.0.4 → 0.1.0

package/index.ts

@@ -1,31 +1,353 @@
-// TODO: do not initialize before the first "valid" command
-import "./src/config";
-import { db, addProject, getProjectByKey, deleteProjectByKey } from "./src/db";
+import type { Column } from "./src/types";
 
-function standardizeKey(key: string) {
-  // TODO: maybe force latin characters only to prevent unexpected stuff from charaters like Ğ, İ, etc.
-  return key.toUpperCase();
-}
+import { randomUUIDv7 } from "bun";
+import { generateKeyBetween } from "fractional-indexing";
+
+import * as dbProject from "./src/db/project";
+import * as dbColumn from "./src/db/column";
+import * as dbTask from "./src/db/task";
+import { standardizeProjectKey } from "./src/lib";
+import { validateTaskInput, taskCreateSchema, taskEditSchema } from "./src/schemas/task";
+import type { TaskCreateInput, TaskEditInput } from "./src/schemas/task";
+
+export { taskCreateSchema, taskEditSchema } from "./src/schemas/task";
+export type { TaskCreateInput, TaskEditInput } from "./src/schemas/task";
+
+export const project = {
+  getById: dbProject.getById,
+  getByKey: dbProject.getByKey,
+  create: (props: { key: string; name: string }) => {
+    const validKeyRegex = /^[A-Za-z][A-Za-z0-9]*$/;
+    if (!validKeyRegex.test(props.key)) {
+      throw new Error("Project key must start with a letter and contain only letters and numbers");
+    }
+
+    const invalidNameCharRegex = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/;
+    // control characters and Unicode line separators are not valid project data.
+    if (props.name.trim().length === 0 || invalidNameCharRegex.test(props.name)) {
+      throw new Error("Project name must contain printable text on a single line");
+    }
+
+    const existingProject = dbProject.getByKey(props.key);
+
+    if (existingProject != null) {
+      throw new Error(`Project with key "${existingProject.key}" already exists!`);
+    }
+
+    const project = dbProject.create(props)!;
+
+    const defaultColumns = ["Backlog", "TODO", "In Progress", "Review", "Done"];
+    let lastColumnOrder: string | null = null;
+
+    for (const col of defaultColumns) {
+      const columnOrder = generateKeyBetween(lastColumnOrder, null);
+      dbColumn.create({
+        id: randomUUIDv7(),
+        project_id: project?.id,
+        name: col,
+        column_order: columnOrder,
+      })!;
+      lastColumnOrder = columnOrder;
+    }
+  },
+  getAll: dbProject.getAll,
+  delete: (key: string) => {
+    const project = dbProject.getByKey(key);
+
+    if (project == null) {
+      throw new Error(`Project with key "${key}" does not exist!`);
+    }
+
+    dbProject.deleteByKey(key);
+  },
+  standardizeKey: standardizeProjectKey,
+};
+
+export const column = {
+  getById: dbColumn.getById,
+  getAllByProjectKey: (key: string) => {
+    const standardizedKey = standardizeProjectKey(key);
+    const project = dbProject.getByKey(standardizedKey);
+
+    if (project == null) {
+      throw new Error(`Project with key "${key}" does not exist!`);
+    }
+    return dbColumn.getAllByProjectId(project.id);
+  },
+  create: (column: Omit<Column, "id" | "project_id" | "column_order"> & { projectKey: string }) => {
+    const standardizedKey = standardizeProjectKey(column.projectKey);
+    const project = dbProject.getByKey(standardizedKey);
 
-// TODO: switch to object param
-export function createProject(key: string, name: string) {
-  const standardizedKey = standardizeKey(key);
-  const project = getProjectByKey(standardizedKey);
+    if (project == null) {
+      throw new Error(`Project with key "${standardizedKey}" does not exist!`);
+    }
 
-  if (project != null) {
-    throw new Error(`Project with key "${standardizedKey}" already exists!`);
+    const allProjectColumns = dbColumn.getAllByProjectId(project.id);
+    const existingColumn = allProjectColumns.find(
+      (existing) => existing.name.toLowerCase() === column.name.toLowerCase(),
+    );
+
+    if (existingColumn != null) {
+      throw new Error(
+        `Column with name "${column.name}" already exists in project "${project.key}"!`,
+      );
+    }
+
+    const lastColOrder = allProjectColumns[allProjectColumns.length - 1]?.column_order ?? null;
+    const res = dbColumn.create({
+      id: randomUUIDv7(),
+      name: column.name,
+      column_order: generateKeyBetween(lastColOrder, null),
+      project_id: project.id,
+    });
+  },
+};
+
+function getTaskByKey(taskKey: string) {
+  const taskKeyMatch = /^([A-Za-z][A-Za-z0-9]*)-(\d+)$/.exec(taskKey);
+  if (taskKeyMatch == null) {
+    throw new Error(`Invalid task key "${taskKey}". Expected format PROJECT-1`);
   }
 
-  addProject(standardizedKey, name);
-}
+  const projectKey = taskKeyMatch[1]!;
+  const taskNumber = Number(taskKeyMatch[2]);
+  if (!Number.isSafeInteger(taskNumber) || taskNumber < 1) {
+    throw new Error(`Invalid task key "${taskKey}". Expected format PROJECT-1`);
+  }
 
-export function deleteProject(key: string) {
-  const standardizedKey = standardizeKey(key);
-  const project = getProjectByKey(standardizedKey);
+  const project = dbProject.getByKey(projectKey);
 
   if (project == null) {
-    throw new Error(`Project with key "${standardizedKey}" does not exist!`);
+    throw new Error(`Project with key "${standardizeProjectKey(projectKey)}" does not exist!`);
+  }
+
+  const taskMatch = dbTask.getByProjectIdAndNumber({
+    projectId: project.id,
+    number: taskNumber,
+  });
+
+  if (taskMatch == null) {
+    throw new Error(`Task "${project.key}-${taskNumber}" does not exist!`);
   }
 
-  deleteProjectByKey(standardizedKey);
+  return taskMatch;
 }
+
+type TaskOrderProps =
+  | {
+      taskKey: string;
+      direction: "top" | "up" | "down" | "bottom";
+      targetTaskKey?: never;
+    }
+  | {
+      taskKey: string;
+      direction: "before" | "after";
+      targetTaskKey: string;
+    };
+
+export const task = {
+  create: (input: TaskCreateInput) => {
+    const task = validateTaskInput(taskCreateSchema, input);
+
+    // TODO: if anything after this fails, especially the task creation, the counter is still incremented but not assigned to any task
+    // TODO: rename
+    const project = dbProject.incrementTaskCounterById(task.project_id);
+
+    if (project == null) {
+      throw new Error(`Project's next task number could not be retrieved  (ID:${task.project_id})`);
+    }
+
+    const initialColumn = dbColumn.getAllByProjectId(task.project_id)[0]!;
+    const lastTask = dbTask.getLastByColumnId(initialColumn.id);
+    const order = generateKeyBetween(lastTask?.task_order ?? null, null);
+
+    const now = Date.now();
+    return dbTask.create({
+      id: randomUUIDv7(),
+      project_id: task.project_id,
+      column_id: initialColumn.id,
+      number: project.task_count,
+      title: task.title,
+      description: task.description,
+      task_order: order,
+      created_at: now,
+      updated_at: now,
+    });
+  },
+  getAll: (props: { projectKey?: string; archive?: dbTask.TaskArchiveFilter } = {}) => {
+    if (props.projectKey == null) {
+      return dbTask.getAll(props.archive);
+    }
+
+    const taskProject = dbProject.getByKey(props.projectKey);
+
+    if (taskProject == null) {
+      throw new Error(`Project with key "${props.projectKey}" does not exist!`);
+    }
+
+    return dbTask.getAllByProjectId(taskProject.id, props.archive);
+  },
+  getByKey: getTaskByKey,
+  /** Edit supplied content fields, including on archived tasks. Unchanged edits are no-ops. */
+  edit: (input: TaskEditInput) => {
+    const props = validateTaskInput(taskEditSchema, input);
+    const existing = getTaskByKey(props.taskKey);
+    const isTitleUnchanged = props.title === undefined || props.title === existing.title;
+    const isDescriptionUnchanged =
+      props.description === undefined || props.description === existing.description;
+
+    if (isTitleUnchanged && isDescriptionUnchanged) {
+      return existing;
+    }
+
+    return dbTask.update({
+      id: existing.id,
+      title: props.title,
+      description: props.description,
+      updated_at: Date.now(),
+    });
+  },
+  /**
+   * Moves a task to another column in its project.
+   *
+   * Moving a task to a different column lists it last in that column,
+   *  matching placement at the bottom of a visual kanban column.
+   * Giving a task's current column as the target will not do anything.
+   * Archived tasks must be unarchived before they can be moved.
+   */
+  move: (props: { taskKey: string; targetColumn: string }) => {
+    const taskMatch = getTaskByKey(props.taskKey);
+
+    if (taskMatch.archived_at != null) {
+      throw new Error(`Archived task "${props.taskKey}" cannot be moved`);
+    }
+
+    const columnMatch = dbColumn
+      .getAllByProjectId(taskMatch.project_id)
+      .find((column) => column.name.toLowerCase() === props.targetColumn.toLowerCase());
+
+    if (columnMatch == null) {
+      // TODO: maybe a `did you mean` type of fuzzy check for misspelllings
+      throw new Error(
+        `Column "${props.targetColumn}" does not exist in task "${props.taskKey}"'s project!`,
+      );
+    }
+
+    if (columnMatch.id === taskMatch.column_id) {
+      return taskMatch;
+    }
+
+    const lastTask = dbTask.getLastByColumnId(columnMatch.id);
+    const order = generateKeyBetween(lastTask?.task_order ?? null, null);
+
+    return dbTask.update({
+      id: taskMatch.id,
+      column_id: columnMatch.id,
+      task_order: order,
+      updated_at: Date.now(),
+    });
+  },
+  order: (props: TaskOrderProps) => {
+    const { taskKey, direction } = props;
+    const taskMatch = getTaskByKey(taskKey);
+
+    if (taskMatch.archived_at != null) {
+      throw new Error(`Archived task "${taskKey}" cannot be reordered`);
+    }
+
+    const allTasks = dbTask.getAllByColumnId(taskMatch.column_id);
+    const taskIndex = allTasks.findIndex((candidate) => candidate.id === taskMatch.id);
+    const otherTasks = allTasks.filter((candidate) => candidate.id !== taskMatch.id);
+    let insertionIndex: number;
+
+    switch (direction) {
+      case "top":
+        insertionIndex = 0;
+        break;
+      case "up":
+        insertionIndex = Math.max(0, taskIndex - 1);
+        break;
+      case "down":
+        insertionIndex = Math.min(otherTasks.length, taskIndex + 1);
+        break;
+      case "bottom":
+        insertionIndex = otherTasks.length;
+        break;
+      case "before":
+      case "after": {
+        const targetTask = getTaskByKey(props.targetTaskKey);
+
+        if (targetTask.id === taskMatch.id) {
+          return taskMatch;
+        }
+
+        if (targetTask.project_id !== taskMatch.project_id) {
+          throw new Error(
+            `Tasks "${taskKey}" and "${props.targetTaskKey}" must be in the same project`,
+          );
+        }
+
+        if (targetTask.column_id !== taskMatch.column_id) {
+          throw new Error(
+            `Tasks "${taskKey}" and "${props.targetTaskKey}" must be in the same column`,
+          );
+        }
+
+        if (targetTask.archived_at != null) {
+          throw new Error(`Archived task "${props.targetTaskKey}" cannot be an ordering target`);
+        }
+
+        const targetIndex = otherTasks.findIndex((candidate) => candidate.id === targetTask.id);
+        insertionIndex = direction === "before" ? targetIndex : targetIndex + 1;
+        break;
+      }
+    }
+
+    if (insertionIndex === taskIndex) {
+      return taskMatch;
+    }
+
+    const futurePrevTask = otherTasks[insertionIndex - 1] ?? null;
+    const futureNextTask = otherTasks[insertionIndex] ?? null;
+
+    return dbTask.update({
+      id: taskMatch.id,
+      task_order: generateKeyBetween(
+        futurePrevTask?.task_order ?? null,
+        futureNextTask?.task_order ?? null,
+      ),
+      updated_at: Date.now(),
+    });
+  },
+  delete: (taskKey: string) => {
+    const taskMatch = getTaskByKey(taskKey);
+    return dbTask.deleteById(taskMatch.id);
+  },
+  archive: (taskKey: string) => {
+    const taskMatch = getTaskByKey(taskKey);
+
+    if (taskMatch.archived_at != null) {
+      return taskMatch;
+    }
+
+    const now = Date.now();
+    return dbTask.update({ id: taskMatch.id, updated_at: now, archived_at: now });
+  },
+  unarchive: (taskKey: string) => {
+    const taskMatch = getTaskByKey(taskKey);
+
+    if (taskMatch.archived_at == null) {
+      return taskMatch;
+    }
+
+    const lastTask = dbTask.getLastByColumnId(taskMatch.column_id);
+    const order = generateKeyBetween(lastTask?.task_order ?? null, null);
+
+    return dbTask.update({
+      id: taskMatch.id,
+      task_order: order,
+      updated_at: Date.now(),
+      archived_at: null,
+    });
+  },
+};

package/package.json

@@ -1,26 +1,30 @@
 {
-	"name": "@zinn-dev/core",
-	"version": "0.0.4",
-	"description": "Shared logic for zinn, a kanban workflow in the terminal.",
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/yethranayeh/zinn.git",
-		"directory": "packages/core"
-	},
-	"private": false,
-	"type": "module",
-	"module": "index.ts",
-	"exports": {
-		".": {
-			"types": "./index.ts",
-			"import": "./index.ts"
-		}
-	},
-	"files": [
-		"index.ts",
-		"src"
-	],
-	"publishConfig": {
-		"access": "public"
-	}
-}
+  "name": "@zinn-dev/core",
+  "version": "0.1.0",
+  "description": "Shared logic for zinn, a kanban workflow in the terminal.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yethranayeh/zinn.git",
+    "directory": "packages/core"
+  },
+  "private": false,
+  "type": "module",
+  "module": "index.ts",
+  "exports": {
+    ".": {
+      "types": "./index.ts",
+      "import": "./index.ts"
+    }
+  },
+  "files": [
+    "index.ts",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "fractional-indexing": "4.0.0",
+    "zod": "4.6.4"
+  }
+}

package/src/config.ts

@@ -1,14 +1,16 @@
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { DATA_DIR, MAIN_DIR, CONFIG_PATH, defaultConfig } from "./constant";
 
-if (!existsSync(MAIN_DIR)) {
-  mkdirSync(MAIN_DIR);
-}
+export function ensureConfigSetup() {
+  if (!existsSync(MAIN_DIR)) {
+    mkdirSync(MAIN_DIR);
+  }
 
-if (!existsSync(DATA_DIR)) {
-  mkdirSync(DATA_DIR);
-}
+  if (!existsSync(DATA_DIR)) {
+    mkdirSync(DATA_DIR);
+  }
 
-if (!existsSync(CONFIG_PATH)) {
-  writeFileSync(CONFIG_PATH, JSON.stringify(defaultConfig) + "\n", { encoding: "utf-8" });
+  if (!existsSync(CONFIG_PATH)) {
+    writeFileSync(CONFIG_PATH, JSON.stringify(defaultConfig) + "\n", { encoding: "utf-8" });
+  }
 }

package/src/constant.ts

@@ -5,13 +5,15 @@ export const MAIN_FOLDER_NAME = ".zinn";
 export const CONFIG_FILE_NAME = "settings.json";
 export const DB_FILE_NAME = "zinn.sqlite";
 
-export const MAIN_DIR = join(homedir(), MAIN_FOLDER_NAME);
+export const MAIN_DIR = process.env.ZINN_DIR ?? join(homedir(), MAIN_FOLDER_NAME);
 export const CONFIG_PATH = join(MAIN_DIR, CONFIG_FILE_NAME);
 export const DATA_DIR = join(MAIN_DIR, "data");
 // TODO: environment variable based path overriding for tests
 export const DB_PATH = join(DATA_DIR, DB_FILE_NAME);
 export const DB_TABLE = {
   project: "project",
+  projectColumn: "project_column",
+  task: "task",
 };
 
 // TODO: implement zod schema for setting.json

package/src/db/column.ts

@@ -0,0 +1,39 @@
+import type { Bind, Column } from "../types";
+
+import { DB_TABLE } from "../constant";
+import { getDb } from "../db";
+
+export function getById(id: string) {
+  const db = getDb();
+  return db
+    .query<Column, Partial<Bind<Pick<Column, "id">>>>(`SELECT * FROM ${DB_TABLE.projectColumn}
+    WHERE id = $id`)
+    .get({ $id: id });
+}
+
+export function getAllByProjectId(projectId: string) {
+  const db = getDb();
+  return db
+    .query<
+      Column,
+      Partial<Bind<Pick<Column, "project_id">>>
+    >(`SELECT * FROM ${DB_TABLE.projectColumn}
+    WHERE project_id = $project_id
+    ORDER BY column_order`)
+    .all({ $project_id: projectId });
+}
+
+export function create(column: Column) {
+  const db = getDb();
+  const query = db.query<Column, Bind<Column>>(`INSERT INTO
+    ${DB_TABLE.projectColumn} (id, project_id, name, column_order)
+    VALUES                    ($id, $project_id, $name, $column_order)
+    RETURNING *;`);
+
+  return query.get({
+    $id: column.id,
+    $project_id: column.project_id,
+    $name: column.name,
+    $column_order: column.column_order,
+  });
+}

package/src/db/project.test.ts

@@ -0,0 +1,183 @@
+import { test, expect, afterAll } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import type { Task } from "../types";
+
+const TEMP_DIR_ROOT = tmpdir();
+const PREFIX = join(TEMP_DIR_ROOT, "zinntest-");
+const TEST_DIR = mkdtempSync(PREFIX);
+process.env.ZINN_DIR = TEST_DIR;
+
+// ? Dynamic so env is set before `MAIN_DIR` constant is initialized.
+const project = await import("./project");
+const column = await import("./column");
+const task = await import("./task");
+
+afterAll(() => {
+  if (!TEST_DIR.startsWith(PREFIX)) {
+    throw new Error(`Refusing to delete "${TEST_DIR}": not a ${PREFIX}* directory`);
+  }
+
+  rmSync(TEST_DIR, { recursive: true, force: true });
+});
+
+test("project.create can establish a project", () => {
+  const created = project.create({ key: "WIP", name: "Work In Progress" });
+
+  expect(created).not.toBeNull();
+  expect(created?.key).toBe("WIP");
+  expect(created?.name).toBe("Work In Progress");
+  expect(created?.task_count).toBe(0);
+  expect(created?.archived_at).toBeNull();
+});
+
+test("project.create standardizes the key", () => {
+  const created = project.create({ key: "key", name: "Lowercased Key" });
+
+  expect(created?.key).toBe("KEY");
+});
+
+test("project.create rejects a duplicate key", () => {
+  expect(project.create({ key: "DUPE", name: "First" })?.key).toBe("DUPE");
+
+  // ? "dupe" standardizes to the already-taken "DUPE".
+  expect(() => project.create({ key: "dupe", name: "Second" })).toThrow(
+    "UNIQUE constraint failed: project.key",
+  );
+});
+
+test("project.getById finds an existing project", () => {
+  const created = project.create({ key: "BYID", name: "By Id" })!;
+  const found = project.getById(created.id);
+
+  expect(found?.id).toEqual(created.id);
+});
+
+test("project.getById returns null for an unknown id", () => {
+  expect(project.getById("unknwon")).toBeNull();
+});
+
+test("project.getByKey is case insensitive for matching", () => {
+  const created = project.create({ key: "someKey", name: "Got By Key" })!;
+
+  expect(project.getByKey("SOMEKEY")).toEqual(created);
+  expect(project.getByKey("somekey")).toEqual(created);
+  expect(project.getByKey("SomEkeY")).toEqual(created);
+});
+
+test("project.getByKey returns null for an unknown key", () => {
+  expect(project.getByKey("NO")).toBeNull();
+});
+
+test("project.incrementTaskCounterById returns the next task number", () => {
+  const created = project.create({ key: "COUNT", name: "Counter" })!;
+
+  expect(project.incrementTaskCounterById(created.id)?.task_count).toBe(1);
+  expect(project.incrementTaskCounterById(created.id)?.task_count).toBe(2);
+  expect(project.getById(created.id)?.task_count).toBe(2);
+});
+
+test("project.incrementTaskCounterById returns null for an unknown id", () => {
+  expect(project.incrementTaskCounterById("nonexistent")).toBeNull();
+});
+
+test("project.deleteByKey removes a project regardless of key casing", () => {
+  const created = project.create({ key: "GONE", name: "Gone" })!;
+
+  const result = project.deleteByKey("gone");
+
+  expect(result.changes).toBe(1);
+  expect(project.getByKey("GONe")).toBeNull();
+  expect(project.getById(created.id)).toBeNull();
+});
+
+test("project.deleteByKey doesn't do anything for nonexistent project", () => {
+  expect(project.deleteByKey("void").changes).toBe(0);
+});
+
+function createTask(title: string) {
+  const suffix = crypto.randomUUID();
+  const taskProject = project.create({ key: `P${suffix.replaceAll("-", "")}`, name: title })!;
+  const taskColumn = {
+    id: crypto.randomUUID(),
+    project_id: taskProject.id,
+    name: "Backlog",
+    column_order: "a0",
+  };
+  column.create(taskColumn);
+
+  const created: Omit<Task, "archived_at"> = {
+    id: crypto.randomUUID(),
+    project_id: taskProject.id,
+    column_id: taskColumn.id,
+    number: 1,
+    title,
+    description: "original description",
+    task_order: "a0",
+    created_at: 10,
+    updated_at: 10,
+  };
+  task.create(created);
+
+  return created;
+}
+
+test("task.update changes supplied fields and preserves omitted fields", () => {
+  const created = createTask("original title");
+
+  const updated = task.update({
+    id: created.id,
+    title: "updated title",
+    description: null,
+    updated_at: 20,
+  });
+
+  expect(updated).toEqual({
+    ...created,
+    title: "updated title",
+    description: null,
+    updated_at: 20,
+    archived_at: null,
+  });
+});
+
+test("task.update distinguishes null from an omitted field", () => {
+  const created = createTask("archivable task");
+
+  const archived = task.update({ id: created.id, archived_at: 30, updated_at: 30 })!;
+  const unarchived = task.update({ id: created.id, archived_at: null, updated_at: 40 });
+
+  expect(archived.archived_at).toBe(30);
+  expect(archived.description).toBe("original description");
+  expect(unarchived?.archived_at).toBeNull();
+  expect(unarchived?.description).toBe("original description");
+});
+
+test("task lists exclude archived tasks by default and support explicit filters", () => {
+  const created = createTask("filtered task");
+  task.update({ id: created.id, archived_at: 50, updated_at: 50 });
+
+  expect(task.getAll().map(({ id }) => id)).not.toContain(created.id);
+  expect(task.getAllByProjectId(created.project_id)).toEqual([]);
+  expect(task.getAll("archived").map(({ id }) => id)).toContain(created.id);
+  expect(task.getAllByProjectId(created.project_id, "all").map(({ id }) => id)).toEqual([
+    created.id,
+  ]);
+});
+
+test("task.getLastByColumnId ignores archived tasks", () => {
+  const first = createTask("active ordering tail");
+  const archived = {
+    ...first,
+    id: crypto.randomUUID(),
+    number: 2,
+    title: "archived ordering tail",
+    task_order: "z0",
+  };
+  task.create(archived);
+  task.update({ id: archived.id, archived_at: 50, updated_at: 50 });
+
+  expect(task.getLastByColumnId(first.column_id)?.id).toBe(first.id);
+});

package/src/db/project.ts

@@ -0,0 +1,73 @@
+import type { Bind, Project } from "../types";
+
+import { randomUUIDv7 } from "bun";
+
+import { DB_TABLE } from "../constant";
+import { getDb } from "../db";
+import { standardizeProjectKey } from "../lib";
+
+export function getAll() {
+  const db = getDb();
+  return db.query<Project, any>(`SELECT * FROM ${DB_TABLE.project}`).all();
+}
+
+export function getById(id: string) {
+  const db = getDb();
+
+  return db
+    .query<Project, Bind<{ id: string }>>(`SELECT * FROM ${DB_TABLE.project} WHERE id = $id`)
+    .get({ $id: id });
+}
+
+export function getByKey(key: string) {
+  const db = getDb();
+  const standardizedKey = standardizeProjectKey(key);
+
+  return db
+    .query<Project, Bind<{ key: string }>>(`SELECT * FROM ${DB_TABLE.project} WHERE key = $key`)
+    .get({ $key: standardizedKey });
+}
+
+export function create({ key, name }: { key: string; name: string }) {
+  const db = getDb();
+
+  const query = db.query<
+    Project,
+    Bind<Pick<Project, "id" | "key" | "name" | "created_at" | "updated_at">>
+  >(`INSERT INTO
+    ${DB_TABLE.project} (id, key, name, created_at, updated_at)
+    VALUES              ($id, $key, $name, $created_at, $updated_at)
+    RETURNING *;`);
+
+  const time = Date.now();
+  const standardizedKey = standardizeProjectKey(key);
+
+  return query.get({
+    $id: randomUUIDv7(),
+    $key: standardizedKey,
+    $name: name,
+    $created_at: time,
+    $updated_at: time,
+  });
+}
+
+export function incrementTaskCounterById(projectId: string) {
+  const db = getDb();
+
+  const nextTaskNumber = db
+    .query<Pick<Project, "task_count">, Bind<Pick<Project, "id">>>(`UPDATE ${DB_TABLE.project}
+          SET task_count = task_count + 1
+          WHERE id = $id RETURNING task_count`)
+    .get({ $id: projectId });
+  return nextTaskNumber;
+}
+
+// TODO: maybe allow both by `key` and `id`, and use whichever is provided
+export function deleteByKey(key: string) {
+  const db = getDb();
+
+  const standardizedKey = standardizeProjectKey(key);
+  return db
+    .query(`DELETE FROM ${DB_TABLE.project} WHERE key = $key;`)
+    .run({ $key: standardizedKey });
+}

package/src/db/task.ts

@@ -0,0 +1,152 @@
+import type { Bind, Task } from "../types";
+
+import { getDb } from "../db";
+import { DB_TABLE } from "../constant";
+
+export type TaskArchiveFilter = "active" | "archived" | "all";
+
+function getArchiveCondition(filter: TaskArchiveFilter) {
+  switch (filter) {
+    case "active":
+      return `${DB_TABLE.task}.archived_at IS NULL`;
+    case "archived":
+      return `${DB_TABLE.task}.archived_at IS NOT NULL`;
+    case "all":
+      return null;
+  }
+}
+
+// TODO: refined parameters, preferably of type SQLBindings
+export function getAll(archive: TaskArchiveFilter = "active") {
+  const db = getDb();
+  const archiveCondition = getArchiveCondition(archive);
+  const whereClause = archiveCondition == null ? "" : `WHERE ${archiveCondition}`;
+
+  return db
+    .query<Task, any>(`SELECT * FROM ${DB_TABLE.task}
+    ${whereClause}
+    ORDER BY (${DB_TABLE.task}.archived_at IS NOT NULL) ASC`)
+    .all();
+}
+
+export function getAllByProjectId(projectId: string, archive: TaskArchiveFilter = "active") {
+  const db = getDb();
+  const archiveCondition = getArchiveCondition(archive);
+  const archiveCluase = archiveCondition == null ? "" : `AND ${archiveCondition}`;
+
+  return db
+    .query<Task, Bind<Pick<Task, "project_id">>>(`SELECT task.*
+    FROM ${DB_TABLE.task}
+    INNER JOIN ${DB_TABLE.projectColumn}
+      ON project_column.id = task.column_id
+    WHERE task.project_id = $project_id
+      ${archiveCluase}
+    ORDER BY project_column.column_order ASC,
+      (task.archived_at IS NOT NULL) ASC,
+      task.task_order ASC,
+      task.number ASC`)
+    .all({ $project_id: projectId });
+}
+
+export function getAllByColumnId(columnId: string, archive: TaskArchiveFilter = "active") {
+  const db = getDb();
+  const archiveCondition = getArchiveCondition(archive);
+  const archiveClause = archiveCondition == null ? "" : `AND ${archiveCondition}`;
+
+  return db
+    .query<Task, Bind<Pick<Task, "column_id">>>(`SELECT *
+    FROM ${DB_TABLE.task}
+    WHERE column_id = $column_id
+      ${archiveClause}
+    ORDER BY task_order ASC,
+      number ASC`)
+    .all({ $column_id: columnId });
+}
+
+export function getLastByColumnId(columnId: string) {
+  const db = getDb();
+  return db
+    .query<Task, Bind<Pick<Task, "column_id">>>(`SELECT *
+    FROM ${DB_TABLE.task}
+    WHERE column_id = $column_id
+      AND archived_at IS NULL
+    ORDER BY task_order DESC
+    LIMIT 1`)
+    .get({ $column_id: columnId });
+}
+
+export function getByProjectIdAndNumber(props: { projectId: string; number: number }) {
+  const db = getDb();
+  return db
+    .query<Task, Bind<Pick<Task, "project_id" | "number">>>(`SELECT *
+    FROM ${DB_TABLE.task}
+    WHERE project_id = $project_id
+    AND number = $number`)
+    .get({ $project_id: props.projectId, $number: props.number });
+}
+
+export function create(task: Omit<Task, "archived_at">) {
+  const db = getDb();
+
+  const q = db.query<Task, Bind<Omit<Task, "archived_at">>>(`INSERT INTO
+    ${DB_TABLE.task}  (id, project_id, column_id, number, title, description, task_order, created_at, updated_at)
+    VALUES            ($id, $project_id, $column_id, $number, $title, $description, $task_order, $created_at, $updated_at);`);
+
+  return q.run({
+    $id: task.id,
+    $project_id: task.project_id,
+    $column_id: task.column_id,
+    $number: task.number,
+    $title: task.title,
+    $description: task.description,
+    $task_order: task.task_order,
+    $created_at: task.created_at,
+    $updated_at: task.updated_at,
+  });
+}
+
+const TASK_UPDATE_COLUMNS = [
+  "column_id",
+  "title",
+  "description",
+  "task_order",
+  "updated_at",
+  "archived_at",
+] as const satisfies ReadonlyArray<keyof Task>;
+
+type TaskUpdateColumn = (typeof TASK_UPDATE_COLUMNS)[number];
+type TaskUpdateParams = Pick<Task, "id" | "updated_at"> &
+  Partial<Pick<Task, Exclude<TaskUpdateColumn, "updated_at">>>;
+type TaskUpdateBindings = Record<string, Task[keyof Task]>;
+
+export function update(props: TaskUpdateParams) {
+  const db = getDb();
+
+  const setClauses: Array<string> = [];
+  const bindings: TaskUpdateBindings = { $id: props.id };
+
+  for (const column of TASK_UPDATE_COLUMNS) {
+    const value = props[column];
+    if (value === undefined) {
+      continue;
+    }
+
+    setClauses.push(`${column} = $${column}`);
+    bindings[`$${column}`] = value;
+  }
+
+  return db
+    .prepare<Task, TaskUpdateBindings>(`UPDATE ${DB_TABLE.task}
+    SET ${setClauses.join(",\n        ")}
+    WHERE id = $id
+    RETURNING *;`)
+    .get(bindings);
+}
+
+export function deleteById(taskId: string) {
+  const db = getDb();
+
+  return db
+    .query<never, Bind<Pick<Task, "id">>>(`DELETE FROM ${DB_TABLE.task} WHERE id = $id;`)
+    .run({ $id: taskId });
+}

package/src/db.ts

@@ -1,34 +1,59 @@
 import { Database } from "bun:sqlite";
 import { DB_PATH, DB_TABLE } from "./constant";
-import { randomUUIDv7 } from "bun";
+import { ensureConfigSetup } from "./config";
 
-export const db = new Database(DB_PATH, { create: true });
-db.run("PRAGMA journal_mode = WAL;");
-// TODO: https://bun.com/docs/runtime/sqlite#wal-sidecar-file-cleanup macOS does not auto cleanup
+let db: Database | null = null;
 
-const projectTableSetup = db.query(`CREATE TABLE IF NOT EXISTS ${DB_TABLE.project} (
+function initDb() {
+  // TODO: turn on strict mode, and refactor `$` prefixes: https://bun.com/docs/runtime/sqlite#strict-true-lets-you-bind-values-without-prefixes
+  const db = new Database(DB_PATH, { create: true });
+
+  db.run("PRAGMA journal_mode = WAL;");
+  db.run("PRAGMA foreign_keys = true;");
+  // TODO: https://bun.com/docs/runtime/sqlite#wal-sidecar-file-cleanup macOS does not auto cleanup
+
+  // --- PROJECT TABLE
+  db.query(`CREATE TABLE IF NOT EXISTS ${DB_TABLE.project} (
   id          TEXT PRIMARY KEY,
   key         TEXT NOT NULL UNIQUE,
   name        TEXT NOT NULL,
+  task_count  INTEGER NOT NULL DEFAULT 0,
   created_at  INTEGER NOT NULL,
   updated_at  INTEGER NOT NULL,
-  archived_at INTEGER);`);
-projectTableSetup.run();
+  archived_at INTEGER);`).run();
 
-export function getProjectByKey(key: string) {
-  return db.query(`SELECT * FROM ${DB_TABLE.project} WHERE key = $key`).get({ $key: key });
-}
+  // --- PROJECT COLUMN TABLE
+  db.query(`CREATE TABLE IF NOT EXISTS ${DB_TABLE.projectColumn} (
+  id            TEXT PRIMARY KEY,
+  project_id    TEXT NOT NULL REFERENCES project(id) ON DELETE CASCADE,
+  name          TEXT NOT NULL,
+  column_order  TEXT);`).run();
 
-// TODO: switch to object param
-export function addProject(key: string, name: string) {
-  const query = db.query(`INSERT INTO
-    ${DB_TABLE.project} (id, key, name, created_at, updated_at)
-    VALUES              ($id, $key, $name, $created, $updated);`);
-  const time = Date.now();
+  // --- TASK TABLE
+  db.query(`CREATE TABLE IF NOT EXISTS ${DB_TABLE.task} (
+  id          TEXT PRIMARY KEY,
+  project_id  TEXT NOT NULL REFERENCES ${DB_TABLE.project}(id) ON DELETE CASCADE,
+  column_id   TEXT NOT NULL REFERENCES ${DB_TABLE.projectColumn}(id),
+  number      INTEGER NOT NULL,
+  title       TEXT NOT NULL,
+  description TEXT,
+  task_order  TEXT,
+  created_at  INTEGER NOT NULL,
+  updated_at  INTEGER NOT NULL,
+  archived_at INTEGER);`).run();
 
-  return query.run({ $id: randomUUIDv7(), $key: key, $name: name, $created: time, $updated: time });
+  return db;
 }
 
-export function deleteProjectByKey(key: string) {
-  return db.query(`DELETE FROM ${DB_TABLE.project} WHERE key = $key;`).run({ $key: key });
+export function getDb() {
+  if (db == null) {
+    try {
+      ensureConfigSetup();
+      db = initDb();
+    } catch (err) {
+      throw new Error("There was a problem initializing Zinn", { cause: err });
+    }
+  }
+
+  return db;
 }

package/src/lib.ts

@@ -0,0 +1,4 @@
+export function standardizeProjectKey(key: string) {
+  // TODO: maybe force latin characters only to prevent unexpected stuff from charaters like Ğ, İ, etc.
+  return key.toUpperCase();
+}

package/src/schemas/task.test.ts

@@ -0,0 +1,31 @@
+import { expect, test } from "bun:test";
+import { validateTaskInput, taskEditSchema, taskCreateSchema } from "./task";
+
+test("edit schemas retain explicit values and never default omitted fields", () => {
+  expect(taskEditSchema.parse({ taskKey: "TEST-1", description: "" })).toEqual({
+    taskKey: "TEST-1", description: "",
+  });
+  expect(taskEditSchema.parse({ taskKey: "TEST-1", title: " Title " })).toEqual({
+    taskKey: "TEST-1", title: " Title ",
+  });
+  expect(taskEditSchema.parse({ taskKey: "TEST-1", description: null }).description).toBeNull();
+});
+
+test("edit input validation rejects empty, mistyped, and unsupported changes", () => {
+  for (const input of [
+    { taskKey: "TEST-1" },
+    { taskKey: "TEST-1", title: undefined },
+    { taskKey: "TEST-1", title: 42 },
+    { taskKey: "TEST-1", title: "Valid", column_id: "other" },
+  ]) {
+    expect(() => validateTaskInput(taskEditSchema, input)).toThrow();
+  }
+});
+
+test("creation and editing share content validation", () => {
+  for (const title of ["", " "]) {
+    expect(taskCreateSchema.safeParse({ project_id: "id", title, description: null }).success).toBe(false);
+    expect(taskEditSchema.safeParse({ taskKey: "TEST-1", title }).success).toBe(false);
+  }
+  expect(taskCreateSchema.parse({ project_id: "id", title: "Valid", description: "" }).description).toBe("");
+});

package/src/schemas/task.ts

@@ -0,0 +1,38 @@
+import { z } from "zod";
+
+const titleMessage = "Task title cannot be blank";
+
+export const taskTitleSchema = z
+  .string({ error: titleMessage })
+  .refine((value) => value.trim().length > 0, titleMessage);
+
+export const taskDescriptionSchema = z.string().nullable();
+
+export const taskCreateSchema = z.strictObject({
+  project_id: z.string(),
+  title: taskTitleSchema,
+  description: taskDescriptionSchema,
+});
+
+export const taskEditSchema = z
+  .strictObject({
+    taskKey: z.string(),
+    title: taskTitleSchema.optional(),
+    description: taskDescriptionSchema.optional(),
+  })
+  .refine(
+    (value) => value.title !== undefined || value.description !== undefined,
+    "Provide at least one field to edit: title or description",
+  );
+
+export type TaskCreateInput = z.infer<typeof taskCreateSchema>;
+export type TaskEditInput = z.infer<typeof taskEditSchema>;
+
+export function validateTaskInput<S extends z.ZodType>(schema: S, input: unknown): z.output<S> {
+  const result = schema.safeParse(input);
+  if (!result.success) {
+    throw new Error(result.error.issues.map((issue) => issue.message).join("\n"));
+  }
+
+  return result.data;
+}

package/src/types.ts

@@ -0,0 +1,37 @@
+// https://www.typescriptlang.org/docs/handbook/2/template-literal-types.html
+type BoundProperty<P extends string> = `$${P}`;
+// https://www.typescriptlang.org/docs/handbook/2/mapped-types.html
+export type Bind<T, K extends string & keyof T = string & keyof T> = {
+  [Property in BoundProperty<K>]: T[keyof T];
+};
+
+export type Project = {
+  id: string;
+  key: string;
+  name: string;
+  task_count: number;
+  created_at: number;
+  updated_at: number;
+  archived_at: number | null;
+};
+
+export type TaskMoveDirection = "top" | "up" | "down" | "bottom";
+export type Task = {
+  id: string;
+  project_id: string;
+  column_id: string;
+  number: number;
+  title: string;
+  description: string | null;
+  task_order: string;
+  created_at: number;
+  updated_at: number;
+  archived_at: number | null;
+};
+
+export type Column = {
+  id: string;
+  project_id: string;
+  name: string;
+  column_order: string;
+};