ttrak 0.1.0

package/.claude/settings.local.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(tree:*)"
+    ]
+  }
+}

package/.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+name: Publish
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - run: bun install
+
+      - run: bun publish --tolerate-republish --provenance
+        env:
+          NPM_CONFIG_PROVENANCE: true

package/AGENTS.md

@@ -0,0 +1,151 @@
+# AGENTS.md
+
+This guide is for agentic coding assistants working in this repository.
+
+## Build Commands
+
+### Development
+
+- `bun dev` - Run in watch mode (builds schema, runs src/index.ts)
+- `bun build` - Build the project (generates schemas only)
+
+### Running Scripts
+
+- `bun run <script.ts>` - Execute any TypeScript file directly
+- `bun run build:schema` - Generate JSON schemas from Zod schemas
+
+### Testing
+
+- No test framework configured yet
+- Manual testing: `bun run test-store.ts` to test data store loading
+
+## Code Style Guidelines
+
+### Import Conventions
+
+- Use ES module syntax: `import { x } from "./path"`
+- Type-only imports use `type` keyword: `import type { Task } from "../schema"`
+- Relative imports with `./` and `../` (no path aliases like `@/`)
+- Group external packages first, then internal modules
+
+### TypeScript Configuration
+
+- Strict mode enabled with all strict checks
+- `verbatimModuleSyntax: true` - explicit type imports required
+- `noUncheckedIndexedAccess: true` - safer array/object access
+- Type definitions inferred from Zod schemas: `export type Task = z.infer<typeof TaskSchema>`
+
+### Formatting
+
+- 2-space indentation
+- No semicolons
+- No trailing whitespace
+- Consistent spacing around operators
+- Multiline objects/arrays aligned visually
+- Avoid unnecessary comments - code should be self-documenting
+
+### Naming Conventions
+
+- Classes: `PascalCase` (e.g., `TaskItem`, `TaskListView`)
+- Interfaces: `PascalCase` (e.g., `Theme`, `TaskModalResult`)
+- Types: `PascalCase` (e.g., `Task`, `DataStore`)
+- Functions/Methods: `camelCase` (e.g., `loadDataStore`, `handleKeyPress`)
+- Variables: `camelCase` (e.g., `selectedIndex`, `activeFilter`)
+- Constants: `SCREAMING_SNAKE_CASE` (e.g., `CONFIG_DIR`)
+- Private members: prefix with `#` (private fields) or keep private conventionally
+
+### File Structure
+
+```
+src/
+  schema.ts          # Zod schemas and type definitions
+  index.ts           # Entry point
+  data/              # Data layer (store, persistence)
+  ui/
+    theme.ts         # Theme configuration
+    components/      # Reusable UI components
+    views/           # Screen/page components
+scripts/             # Build scripts
+```
+
+### Error Handling
+
+- Use try/catch for file I/O operations
+- Use `safeParse()` for Zod schema validation, return defaults on failure
+- Log errors with `console.error()` for invalid data
+- Don't let errors crash the app - provide sensible fallbacks
+
+### UI Component Patterns
+
+- Class-based components with private properties
+- Constructor takes dependencies (renderer, theme, store, callbacks)
+- `destroy()` method for cleanup (remove event listeners, destroy renderables)
+- Event handlers bound in constructor: `this.boundHandler = this.method.bind(this)`
+- Use event emitter pattern: `renderer.keyInput.on("keypress", this.boundHandler)`
+- Remember to cleanup in destroy(): `renderer.keyInput.off("keypress", this.boundHandler)`
+
+### State Management
+
+- State stored in private class properties
+- Modify state, then call `saveAndRender()` or `renderTasks()`
+- Use immutable patterns where possible
+- `saveDataStore()` persists to ~/.config/ttrak/data.json
+
+### Schema-Driven Development
+
+- Define all data structures in src/schema.ts using Zod
+- Use `.default()` for default values in schema definitions
+- After modifying schemas, regenerate JSON schemas: `bun run build:schema`
+- Types inferred from schemas ensure type safety throughout the codebase
+
+### Specific Patterns
+
+#### Zod Schema Definitions
+
+```typescript
+export const TaskSchema = z.object({
+  id: z.string().regex(/^(LOCAL|[A-Z]+)-\d+$/),
+  title: z.string().min(1).max(200),
+  // ...
+});
+export type Task = z.infer<typeof TaskSchema>;
+```
+
+#### Data Loading
+
+```typescript
+const result = DataStoreSchema.safeParse(data);
+if (!result.success) {
+  console.error("Invalid data:", result.error);
+  return DataStoreSchema.parse({});
+}
+return result.data;
+```
+
+#### Component Event Handlers
+
+```typescript
+private boundHandler: (key: KeyEvent) => void;
+
+constructor() {
+  this.boundHandler = this.handleKeyPress.bind(this);
+  this.renderer.keyInput.on("keypress", this.boundHandler);
+}
+
+destroy() {
+  this.renderer.keyInput.off("keypress", this.boundHandler);
+}
+```
+
+## Key Dependencies
+
+- `@opentui/core` - TUI framework (renderables, event handling)
+- `zod` - Schema validation and type inference
+- `@catppuccin/palette` - Theme colors
+- `bun` - Runtime and standard library (file I/O, etc.)
+
+## Configuration
+
+- Data stored in `~/.config/ttrak/data.json`
+- Config in `~/.config/ttrak/config.json`
+- JSON schemas auto-generated for IDE validation

package/README.md

@@ -0,0 +1,15 @@
+# core
+
+To install dependencies:
+
+```bash
+bun install
+```
+
+To run:
+
+```bash
+bun dev
+```
+
+This project was created using `bun create tui`. [create-tui](https://git.new/create-tui) is the easiest way to get started with OpenTUI.

package/config.schema.json

@@ -0,0 +1,103 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "default": "./config.schema.json",
+      "type": "string"
+    },
+    "version": {
+      "default": 1,
+      "type": "number"
+    },
+    "linear": {
+      "type": "object",
+      "properties": {
+        "apiKey": {
+          "type": "string"
+        },
+        "teamId": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "apiKey"
+      ],
+      "additionalProperties": false
+    },
+    "github": {
+      "type": "object",
+      "properties": {
+        "token": {
+          "type": "string"
+        },
+        "repo": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "token"
+      ],
+      "additionalProperties": false
+    },
+    "theme": {
+      "default": {
+        "mode": "auto",
+        "flavor": "mocha"
+      },
+      "type": "object",
+      "properties": {
+        "mode": {
+          "default": "auto",
+          "type": "string",
+          "enum": [
+            "auto",
+            "catppuccin",
+            "system"
+          ]
+        },
+        "flavor": {
+          "default": "mocha",
+          "type": "string",
+          "enum": [
+            "latte",
+            "frappe",
+            "macchiato",
+            "mocha"
+          ]
+        },
+        "overrides": {
+          "type": "object",
+          "propertyNames": {
+            "type": "string"
+          },
+          "additionalProperties": {
+            "type": "string"
+          }
+        }
+      },
+      "required": [
+        "mode",
+        "flavor"
+      ],
+      "additionalProperties": false
+    },
+    "defaultView": {
+      "default": "all",
+      "type": "string",
+      "enum": [
+        "all",
+        "todo",
+        "inProgress",
+        "done"
+      ]
+    }
+  },
+  "required": [
+    "$schema",
+    "version",
+    "theme",
+    "defaultView"
+  ],
+  "additionalProperties": false
+}

package/data.schema.json

@@ -0,0 +1,144 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "default": "./data.schema.json",
+      "type": "string"
+    },
+    "version": {
+      "default": 1,
+      "type": "number"
+    },
+    "tasks": {
+      "default": [],
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^(LOCAL|[A-Z]+)-\\d+$"
+          },
+          "title": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 200
+          },
+          "description": {
+            "type": "string"
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "todo",
+              "inProgress",
+              "done",
+              "cancelled"
+            ]
+          },
+          "priority": {
+            "type": "string",
+            "enum": [
+              "none",
+              "low",
+              "medium",
+              "high",
+              "urgent"
+            ]
+          },
+          "createdAt": {
+            "type": "string"
+          },
+          "updatedAt": {
+            "type": "string"
+          },
+          "linear": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string"
+              },
+              "url": {
+                "type": "string"
+              },
+              "syncedAt": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "id",
+              "url",
+              "syncedAt"
+            ],
+            "additionalProperties": false
+          },
+          "github": {
+            "type": "object",
+            "properties": {
+              "type": {
+                "type": "string",
+                "enum": [
+                  "issue",
+                  "pr"
+                ]
+              },
+              "number": {
+                "type": "number"
+              },
+              "url": {
+                "type": "string"
+              },
+              "syncedAt": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "type",
+              "number",
+              "url",
+              "syncedAt"
+            ],
+            "additionalProperties": false
+          },
+          "tags": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "dueDate": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "id",
+          "title",
+          "status",
+          "priority",
+          "createdAt",
+          "updatedAt"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "lastSync": {
+      "default": null,
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "required": [
+    "$schema",
+    "version",
+    "tasks",
+    "lastSync"
+  ],
+  "additionalProperties": false
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+	"name": "ttrak",
+	"version": "0.1.0",
+	"description": "A terminal task tracker",
+	"module": "src/index.ts",
+	"type": "module",
+	"bin": {
+		"ttrak": "./src/index.ts"
+	},
+	"scripts": {
+		"build:schema": "bun run scripts/generate-schema.ts",
+		"dev": "bun run build:schema && bun run --watch src/index.ts",
+		"build": "bun run build:schema",
+		"prepublishOnly": "bun run build"
+	},
+	"devDependencies": {
+		"@types/bun": "latest"
+	},
+	"peerDependencies": {
+		"typescript": "^5"
+	},
+	"dependencies": {
+		"@catppuccin/palette": "^1.7.1",
+		"@opentui/core": "^0.1.63",
+		"zod": "^4.2.1"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/emots/ttrak.git"
+	},
+	"keywords": ["terminal", "task", "tracker", "tui", "cli"],
+	"author": "",
+	"license": "MIT"
+}

package/scripts/generate-schema.ts

@@ -0,0 +1,10 @@
+import { DataStoreSchema, ConfigStoreSchema } from "../src/schema";
+
+const dataJsonSchema = DataStoreSchema.toJSONSchema();
+const configJsonSchema = ConfigStoreSchema.toJSONSchema();
+Bun.write("data.schema.json", JSON.stringify(dataJsonSchema, null, 2));
+
+Bun.write("config.schema.json", JSON.stringify(configJsonSchema, null, 2));
+
+console.log("✓ Generated data.schema.json");
+console.log("✓ Generated config.schema.json");

package/src/data/store.ts

@@ -0,0 +1,86 @@
+import { homedir } from "os";
+import { join } from "path";
+import { mkdir } from "fs/promises";
+import {
+  DataStoreSchema,
+  ConfigStoreSchema,
+  type DataStore,
+  type ConfigStore,
+} from "../schema";
+
+const CONFIG_DIR = join(homedir(), ".config", "ttrak");
+const DATA_PATH = join(CONFIG_DIR, "data.json");
+const CONFIG_PATH = join(CONFIG_DIR, "config.json");
+
+async function ensureConfigDir() {
+  await mkdir(CONFIG_DIR, { recursive: true });
+}
+
+export async function loadDataStore(): Promise<DataStore> {
+  await ensureConfigDir();
+
+  try {
+    const raw = await Bun.file(DATA_PATH).text();
+    const data = JSON.parse(raw);
+    const result = DataStoreSchema.safeParse(data);
+
+    if (!result.success) {
+      console.error("Invalid data store:", result.error);
+      return DataStoreSchema.parse({});
+    }
+
+    return result.data;
+  } catch (error) {
+    return DataStoreSchema.parse({});
+  }
+}
+
+export async function saveDataStore(store: DataStore): Promise<void> {
+  await ensureConfigDir();
+
+  const { $schema, ...rest } = store;
+  const output = {
+    $schema: "./data.schema.json",
+    ...rest,
+  };
+
+  await Bun.write(DATA_PATH, JSON.stringify(output, null, 2));
+}
+
+export async function loadConfigStore(): Promise<ConfigStore> {
+  await ensureConfigDir();
+
+  try {
+    const raw = await Bun.file(CONFIG_PATH).text();
+    const data = JSON.parse(raw);
+    const result = ConfigStoreSchema.safeParse(data);
+
+    if (!result.success) {
+      console.error("Invalid config store:", result.error);
+      return ConfigStoreSchema.parse({});
+    }
+
+    return result.data;
+  } catch (error) {
+    return ConfigStoreSchema.parse({});
+  }
+}
+
+export async function saveConfigStore(store: ConfigStore): Promise<void> {
+  await ensureConfigDir();
+
+  const output = {
+    ...store,
+    $schema: "./config.schema.json",
+  };
+
+  await Bun.write(CONFIG_PATH, JSON.stringify(output, null, 2));
+}
+
+export function getDataPath(): string {
+  return DATA_PATH;
+}
+
+export function getConfigPath(): string {
+  return CONFIG_PATH;
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env bun
+import { createCliRenderer } from "@opentui/core";
+import { loadDataStore, loadConfigStore } from "./data/store";
+import { getTheme } from "./ui/theme";
+import { TaskListView } from "./ui/views/TaskListView";
+
+async function main() {
+  const renderer = await createCliRenderer({
+    exitOnCtrlC: true,
+    targetFps: 30,
+  });
+
+  const [dataStore, configStore] = await Promise.all([
+    loadDataStore(),
+    loadConfigStore(),
+  ]);
+
+  const theme = await getTheme(renderer, configStore.theme);
+  renderer.setBackgroundColor(theme.bg);
+
+  const view = new TaskListView(renderer, theme, dataStore, () => {
+    view.destroy();
+    renderer.destroy();
+  });
+}
+
+main().catch(console.error);

package/src/schema.ts

@@ -0,0 +1,65 @@
+import { z } from "zod";
+
+export const TaskSchema = z.object({
+  id: z.string().regex(/^(LOCAL|[A-Z]+)-\d+$/),
+  title: z.string().min(1).max(200),
+  description: z.string().optional(),
+  status: z.enum(["todo", "inProgress", "done", "cancelled"]),
+  priority: z.enum(["none", "low", "medium", "high", "urgent"]),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+  linear: z
+    .object({
+      id: z.string(),
+      url: z.string(),
+      syncedAt: z.string(),
+    })
+    .optional(),
+  github: z
+    .object({
+      type: z.enum(["issue", "pr"]),
+      number: z.number(),
+      url: z.string(),
+      syncedAt: z.string(),
+    })
+    .optional(),
+  tags: z.array(z.string()).optional(),
+  dueDate: z.string().optional(),
+});
+
+export const ThemeConfigSchema = z.object({
+  mode: z.enum(["auto", "catppuccin", "system"]).default("auto"),
+  flavor: z.enum(["latte", "frappe", "macchiato", "mocha"]).default("mocha"),
+  overrides: z.record(z.string(), z.string()).optional(),
+});
+
+export const DataStoreSchema = z.object({
+  $schema: z.string().default("./data.schema.json"),
+  version: z.number().default(1),
+  tasks: z.array(TaskSchema).default([]),
+  lastSync: z.string().nullable().default(null),
+});
+
+export const ConfigStoreSchema = z.object({
+  $schema: z.string().default("./config.schema.json"),
+  version: z.number().default(1),
+  linear: z
+    .object({
+      apiKey: z.string(),
+      teamId: z.string().optional(),
+    })
+    .optional(),
+  github: z
+    .object({
+      token: z.string(),
+      repo: z.string().optional(),
+    })
+    .optional(),
+  theme: ThemeConfigSchema.default({ mode: "auto", flavor: "mocha" }),
+  defaultView: z.enum(["all", "todo", "inProgress", "done"]).default("all"),
+});
+
+export type Task = z.infer<typeof TaskSchema>;
+export type ThemeConfig = z.infer<typeof ThemeConfigSchema>;
+export type DataStore = z.infer<typeof DataStoreSchema>;
+export type ConfigStore = z.infer<typeof ConfigStoreSchema>;