flowcat 1.3.0 → 1.5.0

package/core/addTask.ts

@@ -0,0 +1,121 @@
+import { z } from "zod";
+
+import { resolveGithubToken } from "./config";
+import { withWorkspaceLock } from "./lock";
+import { emitHook } from "./pluginManager";
+import { buildPrAttachment, fetchGitHubPr, parseGitHubPrUrl } from "./pr";
+import type { PrFetched } from "./schemas/pr";
+import type { Task } from "./schemas/task";
+import { taskSchema } from "./schemas/task";
+import { buildTask } from "./taskFactory";
+import { saveTask } from "./taskRepo";
+import { createTaskInStore } from "./taskStore";
+import type { TaskType } from "./types";
+import { taskTypes } from "./types";
+
+export type AddTaskInput = {
+  type: TaskType;
+  title?: string;
+  url?: string;
+  workspaceRoot: string;
+};
+
+export type AddTaskResult = {
+  alias: string;
+  task: Task;
+};
+
+export type AddTaskErrorCode = "INVALID_PR_URL" | "MISSING_PR_URL" | "MISSING_TITLE";
+
+export class AddTaskError extends Error {
+  code: AddTaskErrorCode;
+
+  constructor(code: AddTaskErrorCode, message: string) {
+    super(message);
+    this.code = code;
+    this.name = "AddTaskError";
+  }
+}
+
+const addTaskInputSchema = z.object({
+  type: z.enum(taskTypes),
+  title: z.string().optional(),
+  url: z.string().optional(),
+  workspaceRoot: z.string(),
+});
+
+export const addTask = async (input: AddTaskInput): Promise<AddTaskResult> => {
+  const parsedInput = addTaskInputSchema.parse(input);
+
+  return withWorkspaceLock(parsedInput.workspaceRoot, async () => {
+    let prAttachment: Task["metadata"]["pr"] | undefined;
+    let prTitle: string | undefined;
+    let genericUrl: string | undefined;
+
+    if (parsedInput.type === "review" && !parsedInput.url) {
+      throw new AddTaskError("MISSING_PR_URL", "Review tasks require a PR URL");
+    }
+
+    if (parsedInput.url) {
+      const parsed = parseGitHubPrUrl(parsedInput.url);
+      if (parsed) {
+        const token = await resolveGithubToken(parsedInput.workspaceRoot);
+        let fetched: PrFetched | null = null;
+        if (token) {
+          try {
+            fetched = await fetchGitHubPr(parsed, token);
+          } catch {
+            fetched = null;
+          }
+        }
+        prAttachment = buildPrAttachment(parsed, fetched ?? undefined);
+        prTitle = fetched?.title ?? `PR #${parsed.number} ${parsed.repo.owner}/${parsed.repo.name}`;
+      } else {
+        if (parsedInput.type === "review") {
+          throw new AddTaskError("INVALID_PR_URL", "Review tasks require a PR URL");
+        }
+        genericUrl = parsedInput.url;
+      }
+    }
+
+    const isExplicitTitle = Boolean(parsedInput.title);
+    let finalTitle = parsedInput.title ?? prTitle;
+    if (!finalTitle) {
+      throw new AddTaskError("MISSING_TITLE", "Title is required when the URL is not a PR");
+    }
+
+    if (parsedInput.type === "review" && !isExplicitTitle) {
+      finalTitle = `Review: ${finalTitle}`;
+    }
+
+    const metadata = {
+      url: genericUrl,
+      pr: prAttachment,
+    };
+
+    const task = buildTask({
+      type: parsedInput.type,
+      title: finalTitle,
+      metadata,
+    });
+
+    taskSchema.parse(task);
+
+    const result = await createTaskInStore(parsedInput.workspaceRoot, task);
+
+    // Emit hook and apply task modifications from plugins
+    const hookResult = await emitHook(parsedInput.workspaceRoot, "task:created", {
+      task: result.task,
+      alias: result.alias,
+    });
+
+    // If a plugin modified the task, save the updated version
+    if (hookResult.task) {
+      taskSchema.parse(hookResult.task);
+      await saveTask(parsedInput.workspaceRoot, "backlog", hookResult.task);
+      return { alias: result.alias, task: hookResult.task };
+    }
+
+    return result;
+  });
+};

package/core/aliasReconcile.ts

@@ -0,0 +1,41 @@
+import { allocateAliasInMap, readAliases, writeAliases } from "./aliasRepo";
+import { listAllTasks } from "./taskRepo";
+
+export type AliasReconcileResult = {
+  updated: boolean;
+};
+
+export const reconcileAliases = async (workspaceRoot: string): Promise<AliasReconcileResult> => {
+  const aliases = await readAliases(workspaceRoot);
+  const tasks = await listAllTasks(workspaceRoot);
+
+  const tasksById = new Map(tasks.map((stored) => [stored.task.id, stored.task]));
+
+  const normalizePrefix = (prefix: "T" | "R"): void => {
+    const next: Record<string, string> = {};
+    for (const [key, value] of Object.entries(aliases[prefix])) {
+      if (tasksById.has(value)) {
+        next[key] = value;
+      }
+    }
+
+    aliases[prefix] = next;
+  };
+
+  normalizePrefix("T");
+  normalizePrefix("R");
+
+  const existingIds = new Set<string>([...Object.values(aliases.T), ...Object.values(aliases.R)]);
+
+  const missing = tasks
+    .filter((stored) => !existingIds.has(stored.task.id))
+    .sort((a, b) => a.task.created_at.localeCompare(b.task.created_at));
+
+  for (const stored of missing) {
+    const prefix = stored.task.type === "review" ? "R" : "T";
+    allocateAliasInMap(aliases, prefix, stored.task.id);
+  }
+
+  await writeAliases(workspaceRoot, aliases);
+  return { updated: true };
+};

package/core/aliasRepo.ts

@@ -0,0 +1,92 @@
+import { access } from "node:fs/promises";
+import path from "node:path";
+
+import { readJsonFile, writeJsonAtomic } from "./json";
+
+export type AliasPrefix = "T" | "R";
+
+export type AliasMap = {
+  T: Record<string, string>;
+  R: Record<string, string>;
+};
+
+const emptyAliases = (): AliasMap => ({ T: {}, R: {} });
+
+const aliasFilePath = (workspaceRoot: string): string => path.join(workspaceRoot, "aliases.json");
+
+const fileExists = async (filePath: string): Promise<boolean> => {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+export const readAliases = async (workspaceRoot: string): Promise<AliasMap> => {
+  const filePath = aliasFilePath(workspaceRoot);
+  if (!(await fileExists(filePath))) {
+    return emptyAliases();
+  }
+
+  const data = await readJsonFile<AliasMap>(filePath);
+  return {
+    T: data.T ?? {},
+    R: data.R ?? {},
+  };
+};
+
+export const writeAliases = async (workspaceRoot: string, aliases: AliasMap): Promise<void> => {
+  await writeJsonAtomic(aliasFilePath(workspaceRoot), aliases);
+};
+
+export const parseAlias = (alias: string): { prefix: AliasPrefix; key: string } | null => {
+  const match = alias.match(/^([TR])(\d+)$/);
+  if (!match) {
+    return null;
+  }
+
+  return { prefix: match[1] as AliasPrefix, key: match[2] };
+};
+
+const formatAliasKey = (value: number): string => String(value).padStart(2, "0");
+
+export const allocateAliasInMap = (
+  aliases: AliasMap,
+  prefix: AliasPrefix,
+  taskId: string,
+): { alias: string; aliases: AliasMap } => {
+  const used = new Set(Object.keys(aliases[prefix]).map((key) => Number.parseInt(key, 10)));
+
+  let next = 1;
+  while (used.has(next)) {
+    next += 1;
+  }
+
+  const key = formatAliasKey(next);
+  aliases[prefix][key] = taskId;
+
+  return { alias: `${prefix}${key}`, aliases };
+};
+
+export const allocateAlias = async (
+  workspaceRoot: string,
+  prefix: AliasPrefix,
+  taskId: string,
+): Promise<{ alias: string; aliases: AliasMap }> => {
+  const aliases = await readAliases(workspaceRoot);
+  return allocateAliasInMap(aliases, prefix, taskId);
+};
+
+export const resolveAlias = async (
+  workspaceRoot: string,
+  alias: string,
+): Promise<string | null> => {
+  const parsed = parseAlias(alias);
+  if (!parsed) {
+    return null;
+  }
+
+  const aliases = await readAliases(workspaceRoot);
+  return aliases[parsed.prefix][parsed.key] ?? null;
+};

package/core/autoCommit.ts

@@ -0,0 +1,84 @@
+import path from "node:path";
+
+import type { CommandAction } from "./commitMessage";
+import { generateCommitMessage } from "./commitMessage";
+import { resolveAutoCommitEnabled } from "./config";
+import { autoCommit } from "./git";
+import { findGitRoot } from "./workspace";
+
+export const maybeAutoCommit = async (
+  workspaceRoot: string,
+  action: CommandAction,
+): Promise<void> => {
+  const autoCommitEnabled = await resolveAutoCommitEnabled(workspaceRoot);
+
+  if (!autoCommitEnabled) {
+    return;
+  }
+
+  const gitRoot = await findGitRoot(workspaceRoot);
+
+  if (!gitRoot) {
+    return;
+  }
+
+  const message = generateCommitMessage(action);
+
+  // Determine which files might be affected by this action
+  let filesToStage: string[] = [];
+
+  switch (action.type) {
+    case "add":
+    case "start":
+    case "pause":
+    case "complete":
+    case "cancel":
+      filesToStage = [
+        path.relative(
+          gitRoot,
+          path.join(workspaceRoot, "tasks", action.task.status, `${action.task.id}.json`),
+        ),
+      ];
+      break;
+
+    case "log":
+    case "edit":
+      filesToStage = [
+        path.relative(
+          gitRoot,
+          path.join(workspaceRoot, "tasks", action.task.status, `${action.task.id}.json`),
+        ),
+      ];
+      break;
+
+    case "assign":
+    case "unassign":
+      filesToStage = [
+        path.relative(
+          gitRoot,
+          path.join(workspaceRoot, "tasks", action.task.status, `${action.task.id}.json`),
+        ),
+      ];
+      break;
+
+    case "alias":
+      filesToStage = [path.relative(gitRoot, path.join(workspaceRoot, "aliases.json"))];
+      break;
+
+    case "bulk":
+      // For bulk operations, stage all task files and aliases
+      filesToStage = [
+        path.relative(gitRoot, path.join(workspaceRoot, "tasks")),
+        path.relative(gitRoot, path.join(workspaceRoot, "aliases.json")),
+      ];
+      break;
+  }
+
+  // Filter out empty strings and problematic paths
+  filesToStage = filesToStage.filter((file) => file && !file.startsWith("..") && file !== "");
+
+  await autoCommit(gitRoot, {
+    message,
+    files: filesToStage.length > 0 ? filesToStage : undefined,
+  });
+};

package/core/commitMessage.ts

@@ -0,0 +1,95 @@
+import type { Task } from "./schemas/task";
+import type { TaskStatus } from "./types";
+
+export type CommandAction =
+  | { type: "add"; task: Task }
+  | { type: "start"; task: Task }
+  | { type: "pause"; task: Task }
+  | { type: "complete"; task: Task }
+  | { type: "cancel"; task: Task }
+  | { type: "log"; task: Task; message: string }
+  | { type: "edit"; task: Task; changes: string[] }
+  | { type: "assign"; task: Task; date: string }
+  | { type: "unassign"; task: Task; date: string }
+  | { type: "alias"; oldAlias: string; newAlias: string }
+  | { type: "bulk"; action: string; count: number };
+
+const statusEmoji: Record<TaskStatus, string> = {
+  backlog: "📋",
+  active: "🚀",
+  paused: "⏸️",
+  completed: "✅",
+  cancelled: "❌",
+};
+
+const formatTaskRef = (task: Task): string => {
+  return task.ref;
+};
+
+export const generateCommitMessage = (action: CommandAction): string => {
+  switch (action.type) {
+    case "add": {
+      const { task } = action;
+      const emoji = statusEmoji[task.status];
+      const typeLabel = task.type === "review" ? "review" : "task";
+      return `${emoji} Add ${typeLabel}: ${task.title} [${formatTaskRef(task)}]`;
+    }
+
+    case "start": {
+      const { task } = action;
+      return `🚀 Start task: ${task.title} [${formatTaskRef(task)}]`;
+    }
+
+    case "pause": {
+      const { task } = action;
+      return `⏸️ Pause task: ${task.title} [${formatTaskRef(task)}]`;
+    }
+
+    case "complete": {
+      const { task } = action;
+      return `✅ Complete task: ${task.title} [${formatTaskRef(task)}]`;
+    }
+
+    case "cancel": {
+      const { task } = action;
+      return `❌ Cancel task: ${task.title} [${formatTaskRef(task)}]`;
+    }
+
+    case "log": {
+      const { task, message } = action;
+      const truncatedMessage = message.length > 50 ? `${message.substring(0, 47)}...` : message;
+      return `📝 Log: ${truncatedMessage} [${formatTaskRef(task)}]`;
+    }
+
+    case "edit": {
+      const { task, changes } = action;
+      const changesStr = changes.join(", ");
+      return `✏️ Edit ${changesStr} for task: ${task.title} [${formatTaskRef(task)}]`;
+    }
+
+    case "assign": {
+      const { task, date } = action;
+      return `📅 Assign task to ${date}: ${task.title} [${formatTaskRef(task)}]`;
+    }
+
+    case "unassign": {
+      const { task, date } = action;
+      return `📅 Unassign task from ${date}: ${task.title} [${formatTaskRef(task)}]`;
+    }
+
+    case "alias": {
+      const { oldAlias, newAlias } = action;
+      return `🏷️ Rename alias: ${oldAlias} → ${newAlias}`;
+    }
+
+    case "bulk": {
+      const { action: bulkAction, count } = action;
+      return `📦 ${bulkAction}: ${count} task${count === 1 ? "" : "s"}`;
+    }
+
+    default: {
+      const never: never = action;
+      throw new Error(`Unknown action type: ${never}`);
+    }
+  }
+};

package/core/config.ts

@@ -0,0 +1,110 @@
+import { access, mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+
+import { APP_NAME } from "./constants";
+import { readJsonFile, writeJsonAtomic } from "./json";
+
+export type PluginEntry = {
+  /** Path to plugin (relative to plugins dir, absolute, or package name) */
+  path: string;
+  /** Whether plugin is enabled (default: true) */
+  enabled?: boolean;
+  /** Plugin-specific configuration */
+  config?: Record<string, unknown>;
+};
+
+export type PluginSettings = {
+  /** Timeout for hook execution in ms (default: 30000) */
+  hookTimeout?: number;
+  /** Whether to continue on plugin errors (default: true) */
+  continueOnError?: boolean;
+  /** Log level for plugins: "debug" | "info" | "warn" | "error" */
+  logLevel?: "debug" | "info" | "warn" | "error";
+};
+
+export type PluginsConfig = {
+  /** Plugin directory override */
+  directory?: string;
+  /** Registered plugins */
+  entries?: PluginEntry[];
+  /** Global plugin settings */
+  settings?: PluginSettings;
+};
+
+export type AppConfig = {
+  autoCommit?: boolean;
+  github?: {
+    token?: string;
+  };
+  plugins?: PluginsConfig;
+};
+
+export const configFileExists = async (filePath: string): Promise<boolean> => {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+export const resolveGlobalConfigPath = (): string => {
+  const configHome = process.env.XDG_CONFIG_HOME ?? path.join(homedir(), ".config");
+  return path.join(configHome, APP_NAME, "config.json");
+};
+
+export const resolveWorkspaceConfigPath = (workspaceRoot: string): string => {
+  return path.join(workspaceRoot, "config.json");
+};
+
+export const readConfigFile = async (filePath: string): Promise<AppConfig> => {
+  if (!(await configFileExists(filePath))) {
+    return {};
+  }
+
+  return (await readJsonFile<AppConfig>(filePath)) ?? {};
+};
+
+export const writeConfigFile = async (filePath: string, config: AppConfig): Promise<void> => {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeJsonAtomic(filePath, config);
+};
+
+export const updateConfigFile = async (
+  filePath: string,
+  updater: (config: AppConfig) => AppConfig,
+): Promise<AppConfig> => {
+  const current = await readConfigFile(filePath);
+  const next = updater(current);
+  await writeConfigFile(filePath, next);
+  return next;
+};
+
+export const resolveAutoCommitEnabled = async (workspaceRoot: string): Promise<boolean> => {
+  const workspaceConfig = await readConfigFile(resolveWorkspaceConfigPath(workspaceRoot));
+  if (workspaceConfig.autoCommit !== undefined) {
+    return workspaceConfig.autoCommit;
+  }
+
+  const globalConfig = await readConfigFile(resolveGlobalConfigPath());
+  return globalConfig.autoCommit ?? false;
+};
+
+export const resolveGithubToken = async (workspaceRoot: string): Promise<string | null> => {
+  if (process.env.FLOWCAT_GITHUB_TOKEN) {
+    return process.env.FLOWCAT_GITHUB_TOKEN;
+  }
+
+  if (process.env.IL_GITHUB_TOKEN) {
+    return process.env.IL_GITHUB_TOKEN;
+  }
+
+  const workspaceConfig = await readConfigFile(resolveWorkspaceConfigPath(workspaceRoot));
+  if (workspaceConfig.github?.token) {
+    return workspaceConfig.github.token;
+  }
+
+  const globalConfig = await readConfigFile(resolveGlobalConfigPath());
+  return globalConfig.github?.token ?? null;
+};

package/core/constants.ts

@@ -0,0 +1,8 @@
+export const APP_NAME = "flowcat";
+export const APP_DIR = `.${APP_NAME}`;
+export const LOCK_DIR = ".lock";
+export const LOCK_FILE = "store.lock";
+export const TASKS_DIR = "tasks";
+export const PLUGINS_DIR = "plugins";
+
+export const STATUS_ORDER = ["backlog", "active", "paused", "completed", "cancelled"] as const;