@mindtnv/todoist-cli 0.3.1 → 0.5.0

package/src/plugins/types.ts

@@ -0,0 +1,226 @@
+import type { Command as CliCommand } from "commander";
+import type {
+  Task, Project, Label, Section, Comment,
+  CreateTaskParams, UpdateTaskParams, TaskFilter,
+} from "../api/types.ts";
+
+// ── Plugin Storage ──
+
+export interface PluginStorage {
+  get<T>(key: string): Promise<T | null>;
+  set<T>(key: string, value: T): Promise<void>;
+  delete(key: string): Promise<void>;
+  list(prefix?: string): Promise<string[]>;
+  getTaskData<T>(taskId: string, key: string): Promise<T | null>;
+  setTaskData<T>(taskId: string, key: string, value: T): Promise<void>;
+}
+
+// ── Plugin Logger ──
+
+export interface PluginLogger {
+  info(message: string): void;
+  warn(message: string): void;
+  error(message: string): void;
+}
+
+// ── Plugin Context ──
+
+export interface PluginContext {
+  api: PluginApi;
+  storage: PluginStorage;
+  config: Record<string, unknown>;
+  pluginDir: string;
+  log: PluginLogger;
+}
+
+export interface PluginApi {
+  getTasks: (filter?: TaskFilter) => Promise<Task[]>;
+  getTask: (id: string) => Promise<Task>;
+  createTask: (params: CreateTaskParams) => Promise<Task>;
+  updateTask: (id: string, params: UpdateTaskParams) => Promise<Task>;
+  closeTask: (id: string) => Promise<void>;
+  reopenTask: (id: string) => Promise<void>;
+  deleteTask: (id: string) => Promise<void>;
+  getProjects: () => Promise<Project[]>;
+  getProject: (id: string) => Promise<Project>;
+  getLabels: () => Promise<Label[]>;
+  getLabel: (id: string) => Promise<Label>;
+  getSections: (projectId?: string) => Promise<Section[]>;
+  getComments: (taskId: string) => Promise<Comment[]>;
+}
+
+// ── Hook Registry ──
+
+export type HookEvent =
+  | "task.creating"
+  | "task.created"
+  | "task.completing"
+  | "task.completed"
+  | "task.updating"
+  | "task.updated"
+  | "task.deleting"
+  | "task.deleted";
+
+// ── Per-event hook context types ──
+
+export interface TaskCreatingContext { params: CreateTaskParams }
+export interface TaskCreatedContext { task: Task }
+export interface TaskCompletingContext { task: Task }
+export interface TaskCompletedContext { task: Task }
+export interface TaskUpdatingContext { task: Task; changes: UpdateTaskParams }
+export interface TaskUpdatedContext { task: Task; changes: UpdateTaskParams }
+export interface TaskDeletingContext { task: Task }
+export interface TaskDeletedContext { task: Task }
+
+export type HookContextMap = {
+  "task.creating": TaskCreatingContext;
+  "task.created": TaskCreatedContext;
+  "task.completing": TaskCompletingContext;
+  "task.completed": TaskCompletedContext;
+  "task.updating": TaskUpdatingContext;
+  "task.updated": TaskUpdatedContext;
+  "task.deleting": TaskDeletingContext;
+  "task.deleted": TaskDeletedContext;
+};
+
+/** Union of all hook context types — kept for backward compatibility */
+export type HookContext = HookContextMap[HookEvent];
+
+export type HookHandler<E extends HookEvent = HookEvent> = (ctx: HookContextMap[E]) => Promise<{ message?: string } | void>;
+
+export interface HookRegistry {
+  on<E extends HookEvent>(event: E, handler: HookHandler<E>): void;
+  off<E extends HookEvent>(event: E, handler: HookHandler<E>): void;
+  emit<E extends HookEvent>(event: E, ctx: HookContextMap[E]): Promise<string[]>;
+}
+
+// ── View Registry ──
+
+export interface PluginViewDefinition {
+  name: string;
+  label: string;
+  component: React.ComponentType<PluginViewProps>;
+  sidebar?: { icon: string; section: string };
+  shortcut?: string;
+}
+
+export interface PluginViewProps {
+  onBack: () => void;
+  onNavigate: (view: string) => void;
+  ctx: PluginContext;
+  tasks: Task[];
+  projects: Project[];
+  labels: Label[];
+}
+
+export interface ViewRegistry {
+  addView(view: PluginViewDefinition): void;
+  getViews(): PluginViewDefinition[];
+}
+
+// ── Extension Registry ──
+
+export interface TaskColumnDefinition {
+  id: string;
+  label: string;
+  width: number;
+  position: "after-priority" | "after-due" | "before-content";
+  render: (task: Task, ctx: PluginContext) => string;
+  color?: (task: Task) => string;
+  refreshInterval?: number; // ms — triggers re-render at this interval (e.g. 1000 for live timer)
+}
+
+export interface StatusBarItemDefinition {
+  id: string;
+  render: (ctx: PluginContext) => string;
+  color?: (ctx: PluginContext) => string;
+  refreshInterval?: number; // ms
+}
+
+export interface DetailSectionDefinition {
+  id: string;
+  label: string;
+  position: "after-comments" | "after-subtasks" | "after-labels";
+  component: React.ComponentType<{ task: Task; ctx: PluginContext }>;
+}
+
+export interface KeybindingDefinition {
+  key: string;
+  description: string;
+  helpSection: string;
+  action: (ctx: PluginContext, currentTask: Task | null) => Promise<{ statusMessage?: string } | void>;
+}
+
+export interface ExtensionRegistry {
+  addTaskColumn(column: TaskColumnDefinition): void;
+  addDetailSection(section: DetailSectionDefinition): void;
+  addKeybinding(binding: KeybindingDefinition): void;
+  addStatusBarItem(item: StatusBarItemDefinition): void;
+  getTaskColumns(): TaskColumnDefinition[];
+  getDetailSections(): DetailSectionDefinition[];
+  getKeybindings(): KeybindingDefinition[];
+  getStatusBarItems(): StatusBarItemDefinition[];
+}
+
+// ── Palette Registry ──
+
+export interface PaletteInputPrompt {
+  label: string;
+  placeholder?: string;
+  formatPreview?: (value: string) => string;
+}
+
+export interface PaletteCommandDefinition {
+  label: string;
+  category: string;
+  shortcut?: string;
+  inputPrompt?: PaletteInputPrompt;
+  action: (
+    ctx: PluginContext,
+    currentTask: Task | null,
+    navigate: (view: string) => void,
+    input?: string,
+  ) => Promise<void> | void;
+}
+
+export interface PaletteRegistry {
+  addCommands(commands: PaletteCommandDefinition[]): void;
+  getCommands(): PaletteCommandDefinition[];
+}
+
+// ── Plugin Interface ──
+
+export interface TodoistPlugin {
+  name: string;
+  version: string;
+  description?: string;
+  registerCommands?(program: CliCommand, ctx: PluginContext): void;
+  registerViews?(registry: ViewRegistry): void;
+  registerHooks?(hooks: HookRegistry): void;
+  registerExtensions?(extensions: ExtensionRegistry): void;
+  registerPaletteCommands?(palette: PaletteRegistry): void;
+  onLoad?(ctx: PluginContext): Promise<void>;
+  onUnload?(): Promise<void>;
+}
+
+// ── Plugin Manifest (plugin.json) ──
+
+export interface PluginManifest {
+  name: string;
+  version: string;
+  description?: string;
+  main: string;
+  author?: string;
+  source?: string;
+  engines?: { "todoist-cli"?: string };
+  permissions?: string[];
+}
+
+// ── Plugin Config (in config.toml) ──
+
+export interface PluginConfigEntry {
+  source: string;
+  enabled?: boolean;
+  after?: string;
+  [key: string]: unknown;
+}

package/src/plugins/view-registry.ts

@@ -0,0 +1,19 @@
+import type { PluginViewDefinition, ViewRegistry } from "./types.ts";
+
+export function createViewRegistry(): ViewRegistry {
+  const views: PluginViewDefinition[] = [];
+
+  return {
+    addView(view: PluginViewDefinition) {
+      if (views.some(v => v.name === view.name)) {
+        console.warn(`[plugin] View "${view.name}" already registered, skipping`);
+        return;
+      }
+      views.push(view);
+    },
+
+    getViews() {
+      return [...views];
+    },
+  };
+}

package/src/ui/App.tsx

@@ -0,0 +1,234 @@
+import { useState, useEffect, useCallback, useRef } from "react";
+import { render, Box, Text, useApp } from "ink";
+import type { Task, Project, Label, Section } from "../api/types.ts";
+import { getTasks } from "../api/tasks.ts";
+import { getProjects } from "../api/projects.ts";
+import { getLabels } from "../api/labels.ts";
+import { getSections } from "../api/sections.ts";
+import { TasksView } from "./views/TasksView.tsx";
+import type { ListViewState } from "./views/TasksView.tsx";
+import { TaskDetailView } from "./views/TaskDetailView.tsx";
+import { StatsView } from "./views/StatsView.tsx";
+import { CompletedView } from "./views/CompletedView.tsx";
+import { ActivityView } from "./views/ActivityView.tsx";
+import { createHookRegistry } from "../plugins/hook-registry.ts";
+import { createViewRegistry } from "../plugins/view-registry.ts";
+import { createExtensionRegistry } from "../plugins/extension-registry.ts";
+import { createPaletteRegistry } from "../plugins/palette-registry.ts";
+import { loadPlugins } from "../plugins/loader.ts";
+import type { LoadedPlugins } from "../plugins/loader.ts";
+
+type View =
+  | { type: "list" }
+  | { type: "detail"; task: Task }
+  | { type: "stats" }
+  | { type: "completed" }
+  | { type: "activity" }
+  | { type: "plugin"; name: string };
+
+function App() {
+  const { exit } = useApp();
+  const [tasks, setTasks] = useState<Task[]>([]);
+  const [projects, setProjects] = useState<Project[]>([]);
+  const [labels, setLabels] = useState<Label[]>([]);
+  const [sections, setSections] = useState<Section[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [view, setView] = useState<View>({ type: "list" });
+  const [statusMessage, setStatusMessage] = useState("");
+  const [loadedPlugins, setLoadedPlugins] = useState<LoadedPlugins | null>(null);
+  const listStateRef = useRef<ListViewState | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+
+    async function init() {
+      try {
+        const [t, p, l, s] = await Promise.all([
+          getTasks(),
+          getProjects(),
+          getLabels(),
+          getSections(),
+        ]);
+        if (!cancelled) {
+          setTasks(t);
+          setProjects(p);
+          setLabels(l);
+          setSections(s);
+          setLoading(false);
+
+          // Load plugins
+          try {
+            const hooks = createHookRegistry();
+            const viewReg = createViewRegistry();
+            const extReg = createExtensionRegistry();
+            const palReg = createPaletteRegistry();
+            const lp = await loadPlugins(hooks, viewReg, extReg, palReg);
+            if (!cancelled) setLoadedPlugins(lp);
+          } catch {
+            // Plugin loading failure is non-fatal
+          }
+        }
+      } catch (err) {
+        if (!cancelled) {
+          setError(err instanceof Error ? err.message : "Failed to load data");
+          setLoading(false);
+        }
+      }
+    }
+
+    init();
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  const handleOpenTask = useCallback((task: Task) => {
+    setView({ type: "detail", task });
+  }, []);
+
+  const handleBackToList = useCallback(() => {
+    setView({ type: "list" });
+  }, []);
+
+  const handleNavigate = useCallback((viewName: string) => {
+    switch (viewName) {
+      case "stats":
+        setView({ type: "stats" });
+        break;
+      case "completed":
+        setView({ type: "completed" });
+        break;
+      case "activity":
+        setView({ type: "activity" });
+        break;
+      default: {
+        const pluginViews = loadedPlugins?.views.getViews() ?? [];
+        if (pluginViews.some(v => v.name === viewName)) {
+          setView({ type: "plugin", name: viewName });
+        } else {
+          setView({ type: "list" });
+        }
+        break;
+      }
+    }
+  }, [loadedPlugins]);
+
+  const handleTaskChanged = useCallback(async (message?: string) => {
+    if (message) setStatusMessage(message);
+    try {
+      const newTasks = await getTasks();
+      setTasks(newTasks);
+    } catch {
+      setStatusMessage("Failed to refresh tasks after change");
+    }
+    setView({ type: "list" });
+  }, []);
+
+  if (loading) {
+    return (
+      <Box flexDirection="column" justifyContent="center" alignItems="center" width="100%" height="100%">
+        <Text bold color="cyan">Todoist CLI</Text>
+        <Box marginTop={1}>
+          <Text color="gray">Loading your tasks...</Text>
+        </Box>
+      </Box>
+    );
+  }
+
+  if (error) {
+    return (
+      <Box flexDirection="column" justifyContent="center" alignItems="center" width="100%" height="100%">
+        <Text color="red">Error: {error}</Text>
+        <Text color="gray">Make sure you have configured your API token with: todoist auth login</Text>
+      </Box>
+    );
+  }
+
+  if (view.type === "detail") {
+    return (
+      <TaskDetailView
+        task={view.task}
+        allTasks={tasks}
+        projects={projects}
+        labels={labels}
+        onBack={handleBackToList}
+        onTaskChanged={handleTaskChanged}
+        pluginSections={loadedPlugins?.extensions.getDetailSections()}
+        pluginSectionContextMap={loadedPlugins?.detailSectionContextMap}
+        pluginHooks={loadedPlugins?.hooks ?? null}
+      />
+    );
+  }
+
+  if (view.type === "stats") {
+    return <StatsView onBack={handleBackToList} />;
+  }
+
+  if (view.type === "completed") {
+    return <CompletedView onBack={handleBackToList} />;
+  }
+
+  if (view.type === "activity") {
+    return <ActivityView onBack={handleBackToList} />;
+  }
+
+  if (view.type === "plugin" && loadedPlugins) {
+    const pluginView = loadedPlugins.views.getViews().find(v => v.name === view.name);
+    if (pluginView) {
+      const ctx = loadedPlugins.viewContextMap.get(view.name);
+      if (ctx) {
+        const Component = pluginView.component;
+        return (
+          <Component
+            onBack={handleBackToList}
+            onNavigate={handleNavigate}
+            ctx={ctx}
+            tasks={tasks}
+            projects={projects}
+            labels={labels}
+          />
+        );
+      }
+    }
+  }
+
+  return (
+    <TasksView
+      tasks={tasks}
+      projects={projects}
+      labels={labels}
+      onTasksChange={setTasks}
+      onProjectsChange={setProjects}
+      onLabelsChange={setLabels}
+      onQuit={exit}
+      onOpenTask={handleOpenTask}
+      sections={sections}
+      onNavigate={handleNavigate}
+      initialStatus={statusMessage}
+      onStatusClear={() => setStatusMessage("")}
+      savedStateRef={listStateRef}
+      pluginExtensions={loadedPlugins?.extensions ?? null}
+      pluginPalette={loadedPlugins?.palette ?? null}
+      pluginViews={loadedPlugins?.views ?? null}
+      pluginKeybindingContextMap={loadedPlugins?.keybindingContextMap}
+      pluginColumnContextMap={loadedPlugins?.columnContextMap}
+      pluginPaletteContextMap={loadedPlugins?.paletteContextMap}
+      pluginStatusBarContextMap={loadedPlugins?.statusBarContextMap}
+      pluginHooks={loadedPlugins?.hooks ?? null}
+    />
+  );
+}
+
+export async function launchUI(): Promise<void> {
+  // Enter alternate screen buffer (like vim/htop) — clean TUI, restores terminal on exit
+  process.stdout.write("\x1b[?1049h");
+  process.stdout.write("\x1b[H\x1b[2J");
+
+  const instance = render(<App />, { exitOnCtrlC: true });
+
+  await instance.waitUntilExit();
+
+  // Leave alternate screen buffer — restore previous terminal content
+  process.stdout.write("\x1b[?1049l");
+}

package/src/ui/components/Breadcrumb.tsx

@@ -0,0 +1,18 @@
+import { Box, Text } from "ink";
+
+interface BreadcrumbProps {
+  segments: Array<{ label: string; color?: string }>;
+}
+
+export function Breadcrumb({ segments }: BreadcrumbProps) {
+  return (
+    <Box>
+      {segments.map((seg, i) => (
+        <Text key={seg.label}>
+          {i > 0 && <Text color="gray"> / </Text>}
+          <Text color={seg.color ?? "white"} bold={i === segments.length - 1}>{seg.label}</Text>
+        </Text>
+      ))}
+    </Box>
+  );
+}