trekoon 0.1.1 → 0.1.4

package/src/storage/migrations.ts

@@ -2,10 +2,142 @@ import { Database } from "bun:sqlite";
 
 import { BASE_SCHEMA_STATEMENTS, SCHEMA_VERSION } from "./schema";
 
+const BASE_MIGRATION_VERSION = 1;
 const BASE_MIGRATION_NAME = `0001_base_schema_v${SCHEMA_VERSION}`;
+const LEGACY_BASE_MIGRATION_NAME_PATTERNS: readonly string[] = [
+  "0001_base_schema_v*",
+];
 
-function hasMigration(db: Database, name: string): boolean {
-  const migrationTableExists: { count: number } | null = db
+const BASE_ROLLBACK_STATEMENTS: readonly string[] = [
+  "DROP TABLE IF EXISTS sync_conflicts;",
+  "DROP TABLE IF EXISTS sync_cursors;",
+  "DROP TABLE IF EXISTS git_context;",
+  "DROP TABLE IF EXISTS events;",
+  "DROP TABLE IF EXISTS dependencies;",
+  "DROP TABLE IF EXISTS subtasks;",
+  "DROP TABLE IF EXISTS tasks;",
+  "DROP TABLE IF EXISTS epics;",
+];
+
+const INDEX_MIGRATION_UP_STATEMENTS: readonly string[] = [
+  "CREATE INDEX IF NOT EXISTS idx_events_created_at ON events(created_at);",
+  "CREATE INDEX IF NOT EXISTS idx_events_git_branch ON events(git_branch);",
+  "CREATE INDEX IF NOT EXISTS idx_events_created_at_id ON events(created_at, id);",
+  "CREATE INDEX IF NOT EXISTS idx_dependencies_source ON dependencies(source_id);",
+  "CREATE INDEX IF NOT EXISTS idx_dependencies_depends_on ON dependencies(depends_on_id);",
+];
+
+const INDEX_MIGRATION_DOWN_STATEMENTS: readonly string[] = [
+  "DROP INDEX IF EXISTS idx_events_created_at;",
+  "DROP INDEX IF EXISTS idx_events_git_branch;",
+  "DROP INDEX IF EXISTS idx_events_created_at_id;",
+  "DROP INDEX IF EXISTS idx_dependencies_source;",
+  "DROP INDEX IF EXISTS idx_dependencies_depends_on;",
+];
+
+const EVENT_ARCHIVE_MIGRATION_UP_STATEMENTS: readonly string[] = [
+  `
+  CREATE TABLE IF NOT EXISTS event_archive (
+    id TEXT PRIMARY KEY,
+    entity_kind TEXT NOT NULL,
+    entity_id TEXT NOT NULL,
+    operation TEXT NOT NULL,
+    payload TEXT NOT NULL,
+    git_branch TEXT,
+    git_head TEXT,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL,
+    version INTEGER NOT NULL DEFAULT 1
+  );
+  `,
+  "CREATE INDEX IF NOT EXISTS idx_event_archive_created_at ON event_archive(created_at);",
+];
+
+const EVENT_ARCHIVE_MIGRATION_DOWN_STATEMENTS: readonly string[] = [
+  "DROP INDEX IF EXISTS idx_event_archive_created_at;",
+  "DROP TABLE IF EXISTS event_archive;",
+];
+
+interface Migration {
+  readonly version: number;
+  readonly name: string;
+  up(db: Database): void;
+  down(db: Database): void;
+}
+
+interface AppliedMigrationRow {
+  readonly version: number;
+  readonly name: string;
+  readonly applied_at: number;
+}
+
+export interface AppliedMigration {
+  readonly version: number;
+  readonly name: string;
+  readonly appliedAt: number;
+}
+
+export interface MigrationStatus {
+  readonly currentVersion: number;
+  readonly latestVersion: number;
+  readonly applied: readonly AppliedMigration[];
+  readonly pending: ReadonlyArray<{ version: number; name: string }>;
+}
+
+export interface RollbackSummary {
+  readonly fromVersion: number;
+  readonly toVersion: number;
+  readonly rolledBack: number;
+  readonly rolledBackMigrations: readonly string[];
+}
+
+const MIGRATIONS: readonly Migration[] = [
+  {
+    version: BASE_MIGRATION_VERSION,
+    name: BASE_MIGRATION_NAME,
+    up(db: Database): void {
+      for (const statement of BASE_SCHEMA_STATEMENTS) {
+        db.exec(statement);
+      }
+    },
+    down(db: Database): void {
+      for (const statement of BASE_ROLLBACK_STATEMENTS) {
+        db.exec(statement);
+      }
+    },
+  },
+  {
+    version: 2,
+    name: "0002_sync_dependency_indexes",
+    up(db: Database): void {
+      for (const statement of INDEX_MIGRATION_UP_STATEMENTS) {
+        db.exec(statement);
+      }
+    },
+    down(db: Database): void {
+      for (const statement of INDEX_MIGRATION_DOWN_STATEMENTS) {
+        db.exec(statement);
+      }
+    },
+  },
+  {
+    version: 3,
+    name: "0003_event_archive_retention",
+    up(db: Database): void {
+      for (const statement of EVENT_ARCHIVE_MIGRATION_UP_STATEMENTS) {
+        db.exec(statement);
+      }
+    },
+    down(db: Database): void {
+      for (const statement of EVENT_ARCHIVE_MIGRATION_DOWN_STATEMENTS) {
+        db.exec(statement);
+      }
+    },
+  },
+];
+
+function migrationTableExists(db: Database): boolean {
+  const row = db
     .query(
       `
       SELECT COUNT(*) AS count
@@ -15,32 +147,221 @@ function hasMigration(db: Database, name: string): boolean {
     )
     .get() as { count: number } | null;
 
-  if (!migrationTableExists || migrationTableExists.count === 0) {
-    return false;
+  return (row?.count ?? 0) > 0;
+}
+
+function hasMigrationVersionColumn(db: Database): boolean {
+  const columns = db.query("PRAGMA table_info(schema_migrations);").all() as Array<{ name: string }>;
+  return columns.some((column) => column.name === "version");
+}
+
+function ensureMigrationTable(db: Database): void {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS schema_migrations (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      version INTEGER NOT NULL UNIQUE,
+      name TEXT NOT NULL UNIQUE,
+      applied_at INTEGER NOT NULL
+    );
+  `);
+}
+
+function ensureMigrationVersionColumn(db: Database): void {
+  if (!migrationTableExists(db) || hasMigrationVersionColumn(db)) {
+    return;
+  }
+
+  db.exec("ALTER TABLE schema_migrations ADD COLUMN version INTEGER;");
+  db.query("UPDATE schema_migrations SET version = ? WHERE version IS NULL AND name = ?;").run(BASE_MIGRATION_VERSION, BASE_MIGRATION_NAME);
+
+  for (const legacyPattern of LEGACY_BASE_MIGRATION_NAME_PATTERNS) {
+    db.query("UPDATE schema_migrations SET version = ? WHERE version IS NULL AND name GLOB ?;").run(
+      BASE_MIGRATION_VERSION,
+      legacyPattern,
+    );
+  }
+
+  db.exec("CREATE UNIQUE INDEX IF NOT EXISTS idx_schema_migrations_version ON schema_migrations(version);");
+
+  const unresolvedRow = db
+    .query(
+      `
+      SELECT COUNT(*) AS count
+      FROM schema_migrations
+      WHERE version IS NULL;
+      `,
+    )
+    .get() as { count: number } | null;
+
+  if ((unresolvedRow?.count ?? 0) > 0) {
+    throw new Error(
+      "Unable to infer one or more schema_migrations.version values during legacy upgrade. Repair schema_migrations entries manually so every row has a valid version, then rerun migrations.",
+    );
+  }
+}
+
+function validateMigrationPlan(): void {
+  const seen = new Set<number>();
+
+  for (let index = 0; index < MIGRATIONS.length; index += 1) {
+    const migration: Migration = MIGRATIONS[index]!;
+
+    if (migration.version !== index + 1) {
+      throw new Error(`Migration versions must be contiguous from 1 (found ${migration.version} at index ${index}).`);
+    }
+
+    if (seen.has(migration.version)) {
+      throw new Error(`Duplicate migration version ${migration.version}.`);
+    }
+
+    seen.add(migration.version);
+  }
+}
+
+function runExclusive<T>(db: Database, operation: () => T): T {
+  db.exec("BEGIN EXCLUSIVE TRANSACTION;");
+
+  try {
+    const result: T = operation();
+    db.exec("COMMIT;");
+    return result;
+  } catch (error: unknown) {
+    db.exec("ROLLBACK;");
+    throw error;
+  }
+}
+
+function currentVersion(db: Database): number {
+  if (!migrationTableExists(db)) {
+    return 0;
   }
 
-  const row: { count: number } | null = db
-    .query("SELECT COUNT(*) AS count FROM schema_migrations WHERE name = ?;")
-    .get(name) as { count: number } | null;
+  const row = db
+    .query("SELECT COALESCE(MAX(version), 0) AS version FROM schema_migrations;")
+    .get() as { version: number } | null;
 
-  return Boolean(row && row.count > 0);
+  return row?.version ?? 0;
+}
+
+function listAppliedMigrations(db: Database): AppliedMigrationRow[] {
+  if (!migrationTableExists(db)) {
+    return [];
+  }
+
+  return db
+    .query(
+      `
+      SELECT version, name, applied_at
+      FROM schema_migrations
+      WHERE version IS NOT NULL
+      ORDER BY version ASC;
+      `,
+    )
+    .all() as AppliedMigrationRow[];
+}
+
+function migrationForVersion(version: number): Migration {
+  const found = MIGRATIONS.find((migration) => migration.version === version);
+
+  if (!found) {
+    throw new Error(`No migration definition found for version ${version}.`);
+  }
+
+  return found;
+}
+
+function recordMigration(db: Database, migration: Migration): void {
+  db.query("INSERT INTO schema_migrations (version, name, applied_at) VALUES (?, ?, ?);").run(
+    migration.version,
+    migration.name,
+    Date.now(),
+  );
 }
 
 export function migrateDatabase(db: Database): void {
-  if (hasMigration(db, BASE_MIGRATION_NAME)) {
-    return;
+  runExclusive(db, (): void => {
+    ensureMigrationTable(db);
+    ensureMigrationVersionColumn(db);
+    validateMigrationPlan();
+
+    const version: number = currentVersion(db);
+
+    for (const migration of MIGRATIONS) {
+      if (migration.version <= version) {
+        continue;
+      }
+
+      migration.up(db);
+      recordMigration(db, migration);
+    }
+  });
+}
+
+export function describeMigrations(db: Database): MigrationStatus {
+  ensureMigrationTable(db);
+  ensureMigrationVersionColumn(db);
+  validateMigrationPlan();
+
+  const appliedRows: AppliedMigrationRow[] = listAppliedMigrations(db);
+  const latestVersion: number = MIGRATIONS[MIGRATIONS.length - 1]?.version ?? 0;
+  const activeVersion: number = appliedRows[appliedRows.length - 1]?.version ?? 0;
+  const appliedVersions = new Set(appliedRows.map((row) => row.version));
+
+  return {
+    currentVersion: activeVersion,
+    latestVersion,
+    applied: appliedRows.map((row) => ({
+      version: row.version,
+      name: row.name,
+      appliedAt: row.applied_at,
+    })),
+    pending: MIGRATIONS.filter((migration) => !appliedVersions.has(migration.version)).map((migration) => ({
+      version: migration.version,
+      name: migration.name,
+    })),
+  };
+}
+
+export function rollbackDatabase(db: Database, targetVersion: number): RollbackSummary {
+  if (!Number.isInteger(targetVersion) || targetVersion < 0) {
+    throw new Error("Rollback target version must be a non-negative integer.");
   }
 
-  const now: number = Date.now();
+  return runExclusive(db, (): RollbackSummary => {
+    ensureMigrationTable(db);
+    ensureMigrationVersionColumn(db);
+    validateMigrationPlan();
 
-  db.transaction((): void => {
-    for (const statement of BASE_SCHEMA_STATEMENTS) {
-      db.exec(statement);
+    const fromVersion: number = currentVersion(db);
+    if (targetVersion > fromVersion) {
+      throw new Error(`Cannot roll back to version ${targetVersion}; current version is ${fromVersion}.`);
     }
 
-    db.query("INSERT INTO schema_migrations (name, applied_at) VALUES (?, ?);").run(
-      BASE_MIGRATION_NAME,
-      now,
-    );
-  })();
+    const appliedDescending = db
+      .query(
+        `
+        SELECT version, name, applied_at
+        FROM schema_migrations
+        WHERE version IS NOT NULL AND version > ?
+        ORDER BY version DESC;
+        `,
+      )
+      .all(targetVersion) as AppliedMigrationRow[];
+
+    const rolledBackMigrations: string[] = [];
+
+    for (const row of appliedDescending) {
+      const migration: Migration = migrationForVersion(row.version);
+      migration.down(db);
+      db.query("DELETE FROM schema_migrations WHERE version = ?;").run(row.version);
+      rolledBackMigrations.push(migration.name);
+    }
+
+    return {
+      fromVersion,
+      toVersion: targetVersion,
+      rolledBack: appliedDescending.length,
+      rolledBackMigrations,
+    };
+  });
 }

package/src/storage/schema.ts

@@ -5,6 +5,7 @@ export const BASE_SCHEMA_STATEMENTS: readonly string[] = [
   `
   CREATE TABLE IF NOT EXISTS schema_migrations (
     id INTEGER PRIMARY KEY AUTOINCREMENT,
+    version INTEGER NOT NULL UNIQUE,
     name TEXT NOT NULL UNIQUE,
     applied_at INTEGER NOT NULL
   );

package/src/storage/types.ts

@@ -6,6 +6,7 @@ export interface MutableRow {
 
 export interface MigrationRecord {
   readonly id: number;
+  readonly version: number;
   readonly name: string;
   readonly applied_at: number;
 }

package/src/sync/service.ts

@@ -41,11 +41,19 @@ interface EventPayload {
   readonly fields?: Record<string, unknown>;
 }
 
+function isObjectRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 function parsePayload(rawPayload: string): EventPayload {
   try {
     const parsed: unknown = JSON.parse(rawPayload);
 
-    if (typeof parsed === "object" && parsed !== null) {
+    if (isObjectRecord(parsed)) {
+      if ("fields" in parsed && !isObjectRecord(parsed.fields)) {
+        return {};
+      }
+
       return parsed as EventPayload;
     }
   } catch {

package/AGENTS.md

@@ -1,54 +0,0 @@
-# AGENTS.md
-
-This file contains guidelines for agents.
-
-## Mandatory: Atomic Commit Policy
-
-Every code change MUST be followed by an immediate commit.
-
-**Commit format**:
-```
-<imperative verb> <what changed>     ← Line 1: max 50 chars
-<blank line>                         ← Line 2: blank
-<why/context, one point per line>    ← Body: max 72 chars per line
-```
-
-**Rules**:
-1. One commit per logical change
-2. Small, atomic commits - one file per commit preferred
-3. Never batch unrelated changes
-
-**Enforcement**:
-- After any file modification, stop and commit before modifying another file
-- Run `git status --short` after each commit to verify clean tree
-- At milestones: run `bun run build && bun run lint && bun run test`
-
-**Anti-patterns**:
-- ❌ Multiple unrelated files in one commit
-- ❌ Generic messages like "Update file", "WIP", "Fix stuff"
-- ❌ Commit message over 50 chars on first line
-
-## Coding Conventions
-
-For Bun/TypeScript code:
-- **Imports**: Group order (stdlib → third-party → local), explicit named imports, remove unused
-- **Formatting**: Consistent quotes, avoid mixed tabs/spaces
-- **Types**: Prefer explicit types at API boundaries, avoid `any` unless justified
-- **Naming**: `camelCase` (vars/functions), `PascalCase` (types), `UPPER_SNAKE_CASE` (constants)
-
-**Error handling**:
-- Never silently swallow errors
-- Include actionable context (operation + endpoint + status code)
-- Redact secrets from errors and logs
-
-## Agent Behavior
-
-- Prefer minimal, targeted edits; avoid broad rewrites
-- Preserve existing examples unless fixing factual issues
-- For CLI changes, prioritize startup speed and low-latency UX
-- Keep commands compatible with macOS and Linux shells
-
-## Security
-
-- Never commit secrets (tokens, credentials)
-- Redact secrets from errors and logs

package/CONTRIBUTING.md

@@ -1,18 +0,0 @@
-# Contributing to Trekoon
-
-## No-copy implementation policy
-
-Trekoon is implemented in this repository root. The `trekker/` directory is
-reference-only.
-
-- Do not copy code or files from `trekker/` into root `src/`.
-- Do not mirror file layout one-to-one from `trekker/`.
-- Write root implementation code directly, with Trekoon-native structure.
-
-## PR checklist
-
-- [ ] Any new logic was written directly in root project files.
-- [ ] Changes were reviewed for suspiciously identical blocks/comments versus
-      `trekker/` reference code.
-- [ ] Sync-related writes preserve git context (`branch`, `head`, `worktree`).
-- [ ] README command/flag examples match actual implemented CLI behavior.

package/bun.lock

@@ -1,29 +0,0 @@
-{
-  "lockfileVersion": 1,
-  "configVersion": 0,
-  "workspaces": {
-    "": {
-      "name": "trekoon",
-      "dependencies": {
-        "@toon-format/toon": "^2.1.0",
-      },
-      "devDependencies": {
-        "@types/bun": "^1.3.9",
-        "typescript": "^5.9.3",
-      },
-    },
-  },
-  "packages": {
-    "@toon-format/toon": ["@toon-format/toon@2.1.0", "", {}, "sha512-JwWptdF5eOA0HaQxbKAzkpQtR4wSWTEfDlEy/y3/4okmOAX1qwnpLZMmtEWr+ncAhTTY1raCKH0kteHhSXnQqg=="],
-
-    "@types/bun": ["@types/bun@1.3.9", "", { "dependencies": { "bun-types": "1.3.9" } }, "sha512-KQ571yULOdWJiMH+RIWIOZ7B2RXQGpL1YQrBtLIV3FqDcCu6FsbFUBwhdKUlCKUpS3PJDsHlJ1QKlpxoVR+xtw=="],
-
-    "@types/node": ["@types/node@25.2.3", "", { "dependencies": { "undici-types": "~7.16.0" } }, "sha512-m0jEgYlYz+mDJZ2+F4v8D1AyQb+QzsNqRuI7xg1VQX/KlKS0qT9r1Mo16yo5F/MtifXFgaofIFsdFMox2SxIbQ=="],
-
-    "bun-types": ["bun-types@1.3.9", "", { "dependencies": { "@types/node": "*" } }, "sha512-+UBWWOakIP4Tswh0Bt0QD0alpTY8cb5hvgiYeWCMet9YukHbzuruIEeXC2D7nMJPB12kbh8C7XJykSexEqGKJg=="],
-
-    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
-
-    "undici-types": ["undici-types@7.16.0", "", {}, "sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw=="],
-  }
-}

package/tests/commands/dep.test.ts

@@ -1,101 +0,0 @@
-import { mkdtempSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-
-import { afterEach, describe, expect, test } from "bun:test";
-
-import { runDep } from "../../src/commands/dep";
-import { runEpic } from "../../src/commands/epic";
-import { runSubtask } from "../../src/commands/subtask";
-import { runTask } from "../../src/commands/task";
-
-const tempDirs: string[] = [];
-
-function createWorkspace(): string {
-  const workspace = mkdtempSync(join(tmpdir(), "trekoon-dep-"));
-  tempDirs.push(workspace);
-  return workspace;
-}
-
-afterEach((): void => {
-  while (tempDirs.length > 0) {
-    const next = tempDirs.pop();
-    if (next) {
-      rmSync(next, { recursive: true, force: true });
-    }
-  }
-});
-
-async function createTaskGraph(cwd: string): Promise<{ taskA: string; taskB: string; subtask: string }> {
-  const epic = await runEpic({
-    cwd,
-    mode: "human",
-    args: ["create", "--title", "Roadmap", "--description", "desc"],
-  });
-  const epicId = (epic.data as { epic: { id: string } }).epic.id;
-
-  const taskA = await runTask({
-    cwd,
-    mode: "human",
-    args: ["create", "--epic", epicId, "--title", "Task A", "--description", "desc a"],
-  });
-  const taskAId = (taskA.data as { task: { id: string } }).task.id;
-
-  const taskB = await runTask({
-    cwd,
-    mode: "human",
-    args: ["create", "--epic", epicId, "--title", "Task B", "--description", "desc b"],
-  });
-  const taskBId = (taskB.data as { task: { id: string } }).task.id;
-
-  const subtask = await runSubtask({
-    cwd,
-    mode: "human",
-    args: ["create", "--task", taskBId, "--title", "Subtask"],
-  });
-
-  return {
-    taskA: taskAId,
-    taskB: taskBId,
-    subtask: (subtask.data as { subtask: { id: string } }).subtask.id,
-  };
-}
-
-describe("dep command", (): void => {
-  test("supports add/list/remove", async (): Promise<void> => {
-    const cwd = createWorkspace();
-    const nodes = await createTaskGraph(cwd);
-
-    const added = await runDep({ cwd, mode: "human", args: ["add", nodes.taskA, nodes.subtask] });
-    expect(added.ok).toBeTrue();
-
-    const listed = await runDep({ cwd, mode: "human", args: ["list", nodes.taskA] });
-    expect(listed.ok).toBeTrue();
-    expect((listed.data as { dependencies: unknown[] }).dependencies.length).toBe(1);
-
-    const removed = await runDep({ cwd, mode: "human", args: ["remove", nodes.taskA, nodes.subtask] });
-    expect(removed.ok).toBeTrue();
-    expect((removed.data as { removed: number }).removed).toBe(1);
-  });
-
-  test("enforces referential checks for task/subtask nodes", async (): Promise<void> => {
-    const cwd = createWorkspace();
-    const nodes = await createTaskGraph(cwd);
-
-    const bad = await runDep({ cwd, mode: "human", args: ["add", nodes.taskA, "missing-node-id"] });
-    expect(bad.ok).toBeFalse();
-    expect(bad.error?.code).toBe("not_found");
-  });
-
-  test("detects dependency cycles", async (): Promise<void> => {
-    const cwd = createWorkspace();
-    const nodes = await createTaskGraph(cwd);
-
-    const first = await runDep({ cwd, mode: "human", args: ["add", nodes.taskA, nodes.taskB] });
-    expect(first.ok).toBeTrue();
-
-    const cycle = await runDep({ cwd, mode: "human", args: ["add", nodes.taskB, nodes.taskA] });
-    expect(cycle.ok).toBeFalse();
-    expect(cycle.error?.code).toBe("invalid_dependency");
-  });
-});