trekoon 0.1.0

package/src/io/human-table.ts

@@ -0,0 +1,191 @@
+export interface HumanTableOptions {
+  readonly wrapColumns?: readonly number[];
+  readonly maxWidth?: number;
+}
+
+const DEFAULT_TERMINAL_WIDTH = 100;
+const CELL_SEPARATOR = " | ";
+const DIVIDER_SEPARATOR = "-+-";
+
+function getTerminalWidth(override?: number): number {
+  if (override && override > 0) {
+    return override;
+  }
+
+  const detected: number | undefined = process.stdout.columns;
+  if (!detected || detected <= 0) {
+    return DEFAULT_TERMINAL_WIDTH;
+  }
+
+  return detected;
+}
+
+function splitLongToken(token: string, width: number): string[] {
+  if (token.length <= width) {
+    return [token];
+  }
+
+  const chunks: string[] = [];
+  for (let index = 0; index < token.length; index += width) {
+    chunks.push(token.slice(index, index + width));
+  }
+
+  return chunks;
+}
+
+function wrapLine(line: string, width: number): string[] {
+  if (line.length === 0) {
+    return [""];
+  }
+
+  const tokens = line.split(/\s+/g).filter((part) => part.length > 0);
+  if (tokens.length === 0) {
+    return [""];
+  }
+
+  const wrapped: string[] = [];
+  let current = "";
+
+  for (const token of tokens) {
+    const tokenParts = splitLongToken(token, width);
+    for (const part of tokenParts) {
+      if (current.length === 0) {
+        current = part;
+        continue;
+      }
+
+      const combined = `${current} ${part}`;
+      if (combined.length <= width) {
+        current = combined;
+        continue;
+      }
+
+      wrapped.push(current);
+      current = part;
+    }
+  }
+
+  if (current.length > 0) {
+    wrapped.push(current);
+  }
+
+  return wrapped;
+}
+
+function wrapCell(value: string, width: number): string[] {
+  const normalized = value.replace(/\t/g, " ");
+  const paragraphs = normalized.split("\n");
+  const lines: string[] = [];
+
+  for (const paragraph of paragraphs) {
+    lines.push(...wrapLine(paragraph, width));
+  }
+
+  return lines.length > 0 ? lines : [""];
+}
+
+function shrinkWidths(
+  widths: number[],
+  wrapColumns: ReadonlySet<number>,
+  minimumWidths: readonly number[],
+  maxWidth: number,
+  separatorWidth: number,
+): void {
+  const totalWidth = (): number => widths.reduce((sum, width) => sum + width, 0) + separatorWidth;
+  const hardMinimumWidth = 4;
+
+  while (totalWidth() > maxWidth) {
+    let changed = false;
+
+    for (let index = 0; index < widths.length; index += 1) {
+      if (!wrapColumns.has(index)) {
+        continue;
+      }
+
+      const minWidth = minimumWidths[index] ?? 4;
+      const currentWidth = widths[index];
+      if (currentWidth !== undefined && currentWidth > minWidth) {
+        widths[index] = currentWidth - 1;
+        changed = true;
+        if (totalWidth() <= maxWidth) {
+          return;
+        }
+      }
+    }
+
+    if (changed) {
+      continue;
+    }
+
+    for (let index = 0; index < widths.length; index += 1) {
+      if (!wrapColumns.has(index)) {
+        continue;
+      }
+
+      const currentWidth = widths[index];
+      if (currentWidth !== undefined && currentWidth > hardMinimumWidth) {
+        widths[index] = currentWidth - 1;
+        changed = true;
+        if (totalWidth() <= maxWidth) {
+          return;
+        }
+      }
+    }
+
+    if (!changed) {
+      return;
+    }
+  }
+}
+
+export function formatHumanTable(
+  headers: readonly string[],
+  rows: readonly (readonly string[])[],
+  options: HumanTableOptions = {},
+): string {
+  if (headers.length === 0) {
+    return "";
+  }
+
+  const wrapColumns = new Set(options.wrapColumns ?? []);
+  const minimumWidths = headers.map((header, index) => {
+    if (wrapColumns.has(index)) {
+      return Math.min(Math.max(header.length, 12), 20);
+    }
+
+    return header.length;
+  });
+
+  const widths: number[] = headers.map((header, index) => {
+    const rowMax = rows.reduce((max, row) => Math.max(max, (row[index] ?? "").length), 0);
+    return Math.max(header.length, rowMax);
+  });
+
+  const separatorWidth = (headers.length - 1) * CELL_SEPARATOR.length;
+  shrinkWidths(widths, wrapColumns, minimumWidths, getTerminalWidth(options.maxWidth), separatorWidth);
+
+  const formatSingleLine = (row: readonly string[]): string =>
+    row.map((cell, index) => (cell ?? "").padEnd(widths[index] ?? 0)).join(CELL_SEPARATOR);
+
+  const headerLine = formatSingleLine(headers);
+  const dividerLine = widths.map((width) => "-".repeat(width)).join(DIVIDER_SEPARATOR);
+
+  const renderedRows: string[] = [];
+  for (const row of rows) {
+    const wrappedCells = row.map((cell, index) => {
+      if (!wrapColumns.has(index)) {
+        return [cell ?? ""];
+      }
+
+      return wrapCell(cell ?? "", widths[index] ?? 1);
+    });
+    const height = wrappedCells.reduce((max, cellLines) => Math.max(max, cellLines.length), 1);
+
+    for (let lineIndex = 0; lineIndex < height; lineIndex += 1) {
+      const lineCells = wrappedCells.map((cellLines, index) => (cellLines[lineIndex] ?? "").padEnd(widths[index] ?? 0));
+      renderedRows.push(lineCells.join(CELL_SEPARATOR));
+    }
+  }
+
+  return [headerLine, dividerLine, ...renderedRows].join("\n");
+}

package/src/io/output.ts

@@ -0,0 +1,70 @@
+import { encode } from "@toon-format/toon";
+import { type CliResult, type OutputMode, type ToonEnvelope, type ToonError } from "../runtime/command-types";
+
+export interface ResultInput {
+  readonly command: string;
+  readonly data: unknown;
+  readonly human: string;
+  readonly meta?: Record<string, unknown>;
+}
+
+export function okResult(input: ResultInput): CliResult {
+  const base: CliResult = {
+    ok: true,
+    command: input.command,
+    data: input.data,
+    human: input.human,
+  };
+
+  if (!input.meta) {
+    return base;
+  }
+
+  return {
+    ...base,
+    meta: input.meta,
+  };
+}
+
+export function failResult(input: ResultInput & { readonly error: ToonError }): CliResult {
+  const base: CliResult = {
+    ok: false,
+    command: input.command,
+    data: input.data,
+    human: input.human,
+    error: input.error,
+  };
+
+  if (!input.meta) {
+    return base;
+  }
+
+  return {
+    ...base,
+    meta: input.meta,
+  };
+}
+
+export function toToonEnvelope(result: CliResult): ToonEnvelope {
+  return {
+    ok: result.ok,
+    command: result.command,
+    data: result.data,
+    ...(result.error ? { error: result.error } : {}),
+    ...(result.meta ? { meta: result.meta } : {}),
+  };
+}
+
+export function renderResult(result: CliResult, mode: OutputMode): string {
+  const envelope: ToonEnvelope = toToonEnvelope(result);
+
+  if (mode === "json") {
+    return JSON.stringify(envelope);
+  }
+
+  if (mode === "toon") {
+    return encode(envelope);
+  }
+
+  return result.human;
+}

package/src/runtime/cli-shell.ts

@@ -0,0 +1,158 @@
+import { runHelp } from "../commands/help";
+import { runDep } from "../commands/dep";
+import { runEpic } from "../commands/epic";
+import { runInit } from "../commands/init";
+import { runQuickstart } from "../commands/quickstart";
+import { runSubtask } from "../commands/subtask";
+import { runSync } from "../commands/sync";
+import { runTask } from "../commands/task";
+import { runWipe } from "../commands/wipe";
+import { failResult, okResult, renderResult } from "../io/output";
+import { type CliContext, type CliResult, type OutputMode } from "./command-types";
+
+const CLI_VERSION = "0.1.0";
+
+const SUPPORTED_ROOT_COMMANDS: readonly string[] = [
+  "init",
+  "quickstart",
+  "epic",
+  "task",
+  "subtask",
+  "dep",
+  "sync",
+  "wipe",
+];
+
+export interface ParsedInvocation {
+  readonly mode: OutputMode;
+  readonly command: string | null;
+  readonly args: readonly string[];
+  readonly wantsHelp: boolean;
+  readonly wantsVersion: boolean;
+}
+
+export interface ParseInvocationOptions {
+  readonly stdoutIsTTY?: boolean;
+}
+
+export function parseInvocation(argv: readonly string[], options: ParseInvocationOptions = {}): ParsedInvocation {
+  const stdoutIsTTY: boolean = options.stdoutIsTTY ?? Boolean(process.stdout.isTTY);
+  let explicitMode: OutputMode | null = null;
+  let wantsHelp = false;
+  let wantsVersion = false;
+  const positionals: string[] = [];
+
+  for (const token of argv) {
+    if (token === "--json") {
+      explicitMode = "json";
+      continue;
+    }
+
+    if (token === "--toon") {
+      explicitMode = "toon";
+      continue;
+    }
+
+    if (token === "--help" || token === "-h") {
+      wantsHelp = true;
+      continue;
+    }
+
+    if (token === "--version" || token === "-v") {
+      wantsVersion = true;
+      continue;
+    }
+
+    positionals.push(token);
+  }
+
+  return {
+    mode: explicitMode ?? (stdoutIsTTY ? "human" : "json"),
+    command: positionals[0] ?? null,
+    args: positionals.slice(1),
+    wantsHelp,
+    wantsVersion,
+  };
+}
+
+export function renderShellResult(result: CliResult, mode: OutputMode): string {
+  return renderResult(result, mode);
+}
+
+export async function executeShell(parsed: ParsedInvocation, cwd: string = process.cwd()): Promise<CliResult> {
+  if (parsed.wantsVersion) {
+    return okResult({
+      command: "version",
+      human: CLI_VERSION,
+      data: { version: CLI_VERSION },
+    });
+  }
+
+  if (parsed.wantsHelp) {
+    const helpContext: CliContext = {
+      mode: parsed.mode,
+      cwd,
+      args: parsed.command ? [parsed.command] : [],
+    };
+
+    return runHelp(helpContext);
+  }
+
+  if (!parsed.command) {
+    return runHelp({
+      mode: parsed.mode,
+      args: [],
+      cwd,
+    });
+  }
+
+  if (!SUPPORTED_ROOT_COMMANDS.includes(parsed.command)) {
+    return failResult({
+      command: "shell",
+      human: `Unknown command: ${parsed.command}\nRun 'trekoon --help' for usage.`,
+      data: {
+        command: parsed.command,
+        supportedCommands: SUPPORTED_ROOT_COMMANDS,
+      },
+      error: {
+        code: "unknown_command",
+        message: `Unknown command '${parsed.command}'`,
+      },
+    });
+  }
+
+  const context: CliContext = {
+    mode: parsed.mode,
+    args: parsed.args,
+    cwd,
+  };
+
+  switch (parsed.command) {
+    case "init":
+      return runInit(context);
+    case "quickstart":
+      return runQuickstart(context);
+    case "wipe":
+      return runWipe(context);
+    case "epic":
+      return runEpic(context);
+    case "task":
+      return runTask(context);
+    case "subtask":
+      return runSubtask(context);
+    case "dep":
+      return runDep(context);
+    case "sync":
+      return runSync(context);
+    default:
+      return failResult({
+        command: "shell",
+        human: `Unhandled command: ${parsed.command}`,
+        data: { command: parsed.command },
+        error: {
+          code: "unhandled_command",
+          message: `No shell handler for '${parsed.command}'`,
+        },
+      });
+  }
+}

package/src/runtime/command-types.ts

@@ -0,0 +1,33 @@
+export type OutputMode = "human" | "json" | "toon";
+
+export interface CliContext {
+  readonly mode: OutputMode;
+  readonly args: readonly string[];
+  readonly cwd: string;
+}
+
+export interface ToonError {
+  readonly code: string;
+  readonly message: string;
+}
+
+export interface ToonEnvelope {
+  readonly ok: boolean;
+  readonly command: string;
+  readonly data: unknown;
+  readonly error?: ToonError;
+  readonly meta?: Record<string, unknown>;
+}
+
+export interface CliResult {
+  readonly ok: boolean;
+  readonly command: string;
+  readonly data: unknown;
+  readonly human: string;
+  readonly error?: ToonError;
+  readonly meta?: Record<string, unknown>;
+}
+
+export interface CommandHandler {
+  run(context: CliContext): Promise<CliResult>;
+}

package/src/storage/database.ts

@@ -0,0 +1,35 @@
+import { mkdirSync } from "node:fs";
+
+import { Database } from "bun:sqlite";
+
+import { migrateDatabase } from "./migrations";
+import { resolveStoragePaths, type StoragePaths } from "./path";
+
+export interface TrekoonDatabase {
+  readonly db: Database;
+  readonly paths: StoragePaths;
+  close(): void;
+}
+
+export function openTrekoonDatabase(workingDirectory: string = process.cwd()): TrekoonDatabase {
+  const paths: StoragePaths = resolveStoragePaths(workingDirectory);
+
+  mkdirSync(paths.storageDir, { recursive: true });
+
+  const db: Database = new Database(paths.databaseFile, { create: true });
+
+  db.exec("PRAGMA busy_timeout = 5000;");
+  db.exec("PRAGMA journal_mode = WAL;");
+  db.exec("PRAGMA foreign_keys = ON;");
+
+  migrateDatabase(db);
+
+  return {
+    db,
+    paths,
+    close(): void {
+      db.exec("PRAGMA wal_checkpoint(PASSIVE);");
+      db.close(false);
+    },
+  };
+}

package/src/storage/migrations.ts

@@ -0,0 +1,46 @@
+import { Database } from "bun:sqlite";
+
+import { BASE_SCHEMA_STATEMENTS, SCHEMA_VERSION } from "./schema";
+
+const BASE_MIGRATION_NAME = `0001_base_schema_v${SCHEMA_VERSION}`;
+
+function hasMigration(db: Database, name: string): boolean {
+  const migrationTableExists: { count: number } | null = db
+    .query(
+      `
+      SELECT COUNT(*) AS count
+      FROM sqlite_master
+      WHERE type = 'table' AND name = 'schema_migrations';
+      `,
+    )
+    .get() as { count: number } | null;
+
+  if (!migrationTableExists || migrationTableExists.count === 0) {
+    return false;
+  }
+
+  const row: { count: number } | null = db
+    .query("SELECT COUNT(*) AS count FROM schema_migrations WHERE name = ?;")
+    .get(name) as { count: number } | null;
+
+  return Boolean(row && row.count > 0);
+}
+
+export function migrateDatabase(db: Database): void {
+  if (hasMigration(db, BASE_MIGRATION_NAME)) {
+    return;
+  }
+
+  const now: number = Date.now();
+
+  db.transaction((): void => {
+    for (const statement of BASE_SCHEMA_STATEMENTS) {
+      db.exec(statement);
+    }
+
+    db.query("INSERT INTO schema_migrations (name, applied_at) VALUES (?, ?);").run(
+      BASE_MIGRATION_NAME,
+      now,
+    );
+  })();
+}

package/src/storage/path.ts

@@ -0,0 +1,22 @@
+import { resolve } from "node:path";
+
+const DB_DIRNAME = ".trekoon";
+const DB_FILENAME = "trekoon.db";
+
+export interface StoragePaths {
+  readonly worktreeRoot: string;
+  readonly storageDir: string;
+  readonly databaseFile: string;
+}
+
+export function resolveStoragePaths(workingDirectory: string = process.cwd()): StoragePaths {
+  const worktreeRoot: string = resolve(workingDirectory);
+  const storageDir: string = resolve(worktreeRoot, DB_DIRNAME);
+  const databaseFile: string = resolve(storageDir, DB_FILENAME);
+
+  return {
+    worktreeRoot,
+    storageDir,
+    databaseFile,
+  };
+}

package/src/storage/schema.ts

@@ -0,0 +1,116 @@
+export const SCHEMA_VERSION = 1;
+
+export const BASE_SCHEMA_STATEMENTS: readonly string[] = [
+  `PRAGMA foreign_keys = ON;`,
+  `
+  CREATE TABLE IF NOT EXISTS schema_migrations (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT NOT NULL UNIQUE,
+    applied_at INTEGER NOT NULL
+  );
+  `,
+  `
+  CREATE TABLE IF NOT EXISTS epics (
+    id TEXT PRIMARY KEY,
+    title TEXT NOT NULL,
+    description TEXT NOT NULL DEFAULT '',
+    status TEXT NOT NULL,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL,
+    version INTEGER NOT NULL DEFAULT 1
+  );
+  `,
+  `
+  CREATE TABLE IF NOT EXISTS tasks (
+    id TEXT PRIMARY KEY,
+    epic_id TEXT NOT NULL,
+    title TEXT NOT NULL,
+    description TEXT NOT NULL DEFAULT '',
+    status TEXT NOT NULL,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL,
+    version INTEGER NOT NULL DEFAULT 1,
+    FOREIGN KEY (epic_id) REFERENCES epics (id) ON DELETE CASCADE
+  );
+  `,
+  `
+  CREATE TABLE IF NOT EXISTS subtasks (
+    id TEXT PRIMARY KEY,
+    task_id TEXT NOT NULL,
+    title TEXT NOT NULL,
+    description TEXT NOT NULL DEFAULT '',
+    status TEXT NOT NULL,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL,
+    version INTEGER NOT NULL DEFAULT 1,
+    FOREIGN KEY (task_id) REFERENCES tasks (id) ON DELETE CASCADE
+  );
+  `,
+  `
+  CREATE TABLE IF NOT EXISTS dependencies (
+    id TEXT PRIMARY KEY,
+    source_id TEXT NOT NULL,
+    source_kind TEXT NOT NULL,
+    depends_on_id TEXT NOT NULL,
+    depends_on_kind TEXT NOT NULL,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL,
+    version INTEGER NOT NULL DEFAULT 1
+  );
+  `,
+  `
+  CREATE TABLE IF NOT EXISTS events (
+    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 TABLE IF NOT EXISTS git_context (
+    id TEXT PRIMARY KEY,
+    worktree_path TEXT NOT NULL,
+    branch_name TEXT,
+    head_sha TEXT,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL,
+    version INTEGER NOT NULL DEFAULT 1
+  );
+  `,
+  `
+  CREATE TABLE IF NOT EXISTS sync_cursors (
+    id TEXT PRIMARY KEY,
+    source_branch TEXT NOT NULL,
+    cursor_token TEXT NOT NULL,
+    last_event_at INTEGER,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL,
+    version INTEGER NOT NULL DEFAULT 1
+  );
+  `,
+  `
+  CREATE TABLE IF NOT EXISTS sync_conflicts (
+    id TEXT PRIMARY KEY,
+    event_id TEXT NOT NULL,
+    entity_kind TEXT NOT NULL,
+    entity_id TEXT NOT NULL,
+    field_name TEXT NOT NULL,
+    ours_value TEXT,
+    theirs_value TEXT,
+    resolution TEXT NOT NULL DEFAULT 'pending',
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL,
+    version INTEGER NOT NULL DEFAULT 1
+  );
+  `,
+  `CREATE INDEX IF NOT EXISTS idx_tasks_epic_id ON tasks(epic_id);`,
+  `CREATE INDEX IF NOT EXISTS idx_subtasks_task_id ON subtasks(task_id);`,
+  `CREATE INDEX IF NOT EXISTS idx_events_entity ON events(entity_kind, entity_id);`,
+  `CREATE INDEX IF NOT EXISTS idx_conflicts_resolution ON sync_conflicts(resolution);`,
+];

package/src/storage/types.ts

@@ -0,0 +1,15 @@
+export interface MutableRow {
+  readonly created_at: number;
+  readonly updated_at: number;
+  readonly version: number;
+}
+
+export interface MigrationRecord {
+  readonly id: number;
+  readonly name: string;
+  readonly applied_at: number;
+}
+
+export interface TrekoonStorageConfig {
+  readonly workingDirectory: string;
+}