flowcat 1.3.0 → 1.4.4

package/core/dayAssignments.ts

@@ -0,0 +1,198 @@
+import { withWorkspaceLock } from "./lock";
+import type { DayAssignment } from "./schemas/dayAssignment";
+import type { Task } from "./schemas/task";
+import { appendDayAssignment, getLatestDayAssignment, isAssignedOnDate } from "./taskOperations";
+import type { StoredTask } from "./taskRepo";
+import { listAllTasks, saveTask } from "./taskRepo";
+import { resolveTask } from "./taskResolver";
+
+export type OrderedAssignment = {
+  stored: StoredTask;
+  lastEvent: DayAssignment;
+  lastIndex: number;
+};
+
+export type AssignToDateResult =
+  | { status: "assigned"; task: Task; order: number }
+  | { status: "already_assigned"; task: Task };
+
+export type MoveAssignmentResult =
+  | { status: "moved"; task: Task; position: number }
+  | { status: "no_change"; task: Task; position: number }
+  | { status: "not_assigned"; task: Task };
+
+export type UnassignResult =
+  | { status: "unassigned"; task: Task }
+  | { status: "already_unassigned"; task: Task };
+
+type MovePosition = "up" | "down" | "top" | "bottom";
+type MovePositionInput = MovePosition | number | string;
+
+export class DayAssignmentError extends Error {
+  code: "INVALID_POSITION" | "POSITION_OUT_OF_RANGE";
+
+  constructor(code: "INVALID_POSITION" | "POSITION_OUT_OF_RANGE", message: string) {
+    super(message);
+    this.code = code;
+    this.name = "DayAssignmentError";
+  }
+}
+
+const collectAssignments = (tasks: StoredTask[], date: string): OrderedAssignment[] => {
+  const entries: OrderedAssignment[] = [];
+  for (const stored of tasks) {
+    const latest = getLatestDayAssignment(stored.task, date);
+    if (!latest) {
+      continue;
+    }
+
+    if (latest.event.action === "assign" || latest.event.action === "reorder") {
+      entries.push({ stored, lastEvent: latest.event, lastIndex: latest.index });
+    }
+  }
+
+  return entries;
+};
+
+const sortAssignments = (entries: OrderedAssignment[]): OrderedAssignment[] => {
+  return [...entries].sort((a, b) => {
+    const orderA = a.lastEvent.order;
+    const orderB = b.lastEvent.order;
+    if (orderA != null && orderB != null) {
+      return orderA - orderB;
+    }
+    if (orderA != null) {
+      return -1;
+    }
+    if (orderB != null) {
+      return 1;
+    }
+    return a.lastIndex - b.lastIndex;
+  });
+};
+
+export const buildOrderedAssignments = (tasks: StoredTask[], date: string): OrderedAssignment[] => {
+  const entries = collectAssignments(tasks, date);
+  return sortAssignments(entries);
+};
+
+export const resolveMoveTarget = (
+  position: MovePositionInput,
+  currentIndex: number,
+  total: number,
+): number => {
+  if (position === "up") {
+    return Math.max(0, currentIndex - 1);
+  }
+  if (position === "down") {
+    return Math.min(total - 1, currentIndex + 1);
+  }
+  if (position === "top") {
+    return 0;
+  }
+  if (position === "bottom") {
+    return total - 1;
+  }
+
+  const parsed = typeof position === "number" ? position : Number(position);
+  if (!Number.isInteger(parsed)) {
+    throw new DayAssignmentError("INVALID_POSITION", `Invalid position: ${position}`);
+  }
+
+  if (parsed < 1 || parsed > total) {
+    throw new DayAssignmentError("POSITION_OUT_OF_RANGE", `Position out of range: ${position}`);
+  }
+
+  return parsed - 1;
+};
+
+export const assignTaskToDate = async (input: {
+  workspaceRoot: string;
+  identifier: string;
+  date: string;
+  message?: string;
+}): Promise<AssignToDateResult> => {
+  return withWorkspaceLock(input.workspaceRoot, async () => {
+    const tasks = await listAllTasks(input.workspaceRoot);
+    const stored = await resolveTask(input.workspaceRoot, input.identifier);
+    if (isAssignedOnDate(stored.task, input.date)) {
+      return { status: "already_assigned", task: stored.task };
+    }
+
+    const ordered = buildOrderedAssignments(tasks, input.date);
+    const order = ordered.length + 1;
+    const updated = appendDayAssignment(stored.task, input.date, "assign", input.message, order);
+    await saveTask(input.workspaceRoot, stored.status, updated);
+    return { status: "assigned", task: updated, order };
+  });
+};
+
+export const moveAssignmentForDate = async (input: {
+  workspaceRoot: string;
+  identifier: string;
+  date: string;
+  position: MovePositionInput;
+}): Promise<MoveAssignmentResult> => {
+  return withWorkspaceLock(input.workspaceRoot, async () => {
+    const stored = await resolveTask(input.workspaceRoot, input.identifier);
+    const tasks = await listAllTasks(input.workspaceRoot);
+    const ordered = buildOrderedAssignments(tasks, input.date);
+    const currentIndex = ordered.findIndex((entry) => entry.stored.task.id === stored.task.id);
+
+    if (currentIndex === -1) {
+      return { status: "not_assigned", task: stored.task };
+    }
+
+    const targetIndex = resolveMoveTarget(input.position, currentIndex, ordered.length);
+    if (targetIndex === currentIndex) {
+      return { status: "no_change", task: stored.task, position: currentIndex + 1 };
+    }
+
+    const reordered = [...ordered];
+    const [moved] = reordered.splice(currentIndex, 1);
+    if (!moved) {
+      return { status: "not_assigned", task: stored.task };
+    }
+
+    reordered.splice(targetIndex, 0, moved);
+
+    let updatedTask = stored.task;
+    for (const [index, entry] of reordered.entries()) {
+      const nextOrder = index + 1;
+      if (entry.lastEvent.order === nextOrder) {
+        continue;
+      }
+
+      const updated = appendDayAssignment(
+        entry.stored.task,
+        input.date,
+        "reorder",
+        undefined,
+        nextOrder,
+      );
+      await saveTask(input.workspaceRoot, entry.stored.status, updated);
+      if (entry.stored.task.id === stored.task.id) {
+        updatedTask = updated;
+      }
+    }
+
+    return { status: "moved", task: updatedTask, position: targetIndex + 1 };
+  });
+};
+
+export const unassignTaskFromDate = async (input: {
+  workspaceRoot: string;
+  identifier: string;
+  date: string;
+}): Promise<UnassignResult> => {
+  return withWorkspaceLock(input.workspaceRoot, async () => {
+    const stored = await resolveTask(input.workspaceRoot, input.identifier);
+    if (!isAssignedOnDate(stored.task, input.date)) {
+      return { status: "already_unassigned", task: stored.task };
+    }
+
+    const updated = appendDayAssignment(stored.task, input.date, "unassign");
+    await saveTask(input.workspaceRoot, stored.status, updated);
+    return { status: "unassigned", task: updated };
+  });
+};

package/core/edit.ts

@@ -0,0 +1,59 @@
+import { buildPrAttachment, parseGitHubPrUrl } from "./pr";
+import type { Task } from "./schemas/task";
+import { validateTaskOrThrow } from "./schemas/task";
+import { nowIso } from "./time";
+
+const parseValue = (raw: string): unknown => {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return raw;
+  }
+};
+
+export const applyTaskEdit = (task: Task, dottedPath: string, rawValue: string): Task => {
+  if (dottedPath === "status" || dottedPath.startsWith("status.")) {
+    throw new Error("Use status commands to change status");
+  }
+
+  const value = parseValue(rawValue);
+  const updated = structuredClone(task);
+  const segments = dottedPath.split(".");
+
+  let current: Record<string, unknown> = updated as unknown as Record<string, unknown>;
+  for (const segment of segments.slice(0, -1)) {
+    if (!(segment in current)) {
+      current[segment] = {};
+    }
+
+    const next = current[segment];
+    if (typeof next !== "object" || next === null || Array.isArray(next)) {
+      throw new Error(`Cannot set ${dottedPath} on non-object path`);
+    }
+
+    current = next as Record<string, unknown>;
+  }
+
+  const last = segments[segments.length - 1];
+  current[last] = value;
+
+  if (dottedPath === "metadata.pr.url") {
+    if (typeof value !== "string") {
+      throw new Error("metadata.pr.url must be a string");
+    }
+
+    const parsed = parseGitHubPrUrl(value);
+    if (!parsed) {
+      throw new Error("Invalid PR URL");
+    }
+
+    updated.metadata.pr = buildPrAttachment(parsed, updated.metadata.pr?.fetched);
+  }
+
+  const nextTask: Task = {
+    ...updated,
+    updated_at: nowIso(),
+  };
+
+  return validateTaskOrThrow(nextTask);
+};

package/core/format.ts

@@ -0,0 +1,63 @@
+import type { AliasMap } from "./aliasRepo";
+import type { Task } from "./schemas/task";
+
+export const buildAliasLookup = (aliases: AliasMap): Map<string, string> => {
+  const map = new Map<string, string>();
+  for (const [key, value] of Object.entries(aliases.T)) {
+    map.set(value, `T${key}`);
+  }
+  for (const [key, value] of Object.entries(aliases.R)) {
+    map.set(value, `R${key}`);
+  }
+  return map;
+};
+
+export const formatTaskListLine = (task: Task, alias?: string): string => {
+  const aliasText = alias ?? "--";
+  return `${aliasText.padEnd(4)} ${task.ref.padEnd(9)} ${task.status.padEnd(9)} ${task.title}`;
+};
+
+export const formatTaskDetails = (task: Task, alias?: string): string => {
+  const lines: string[] = [];
+  lines.push(`${alias ?? "--"} ${task.ref} ${task.title}`);
+  lines.push(`id: ${task.id}`);
+  lines.push(`type: ${task.type}`);
+  lines.push(`status: ${task.status}`);
+  lines.push(`created: ${task.created_at}`);
+  lines.push(`updated: ${task.updated_at}`);
+
+  if (task.metadata.url) {
+    lines.push(`url: ${task.metadata.url}`);
+  }
+
+  if (task.metadata.pr?.url) {
+    lines.push(`pr: ${task.metadata.pr.url}`);
+    if (task.metadata.pr.fetched) {
+      const fetched = task.metadata.pr.fetched;
+      lines.push(`pr_state: ${fetched.state}`);
+      lines.push(`pr_title: ${fetched.title}`);
+      lines.push(`pr_author: ${fetched.author.login}`);
+      lines.push(`pr_updated_at: ${fetched.updated_at}`);
+      lines.push(`pr_refreshed_at: ${fetched.at}`);
+    }
+  }
+
+  if (task.logs.length > 0) {
+    lines.push("logs:");
+    for (const log of task.logs) {
+      const status = log.status ? ` [${log.status}]` : "";
+      lines.push(`- ${log.ts}${status} ${log.msg}`);
+    }
+  }
+
+  if (task.day_assignments.length > 0) {
+    lines.push("day_assignments:");
+    for (const entry of task.day_assignments) {
+      const order = entry.order ? ` order:${entry.order}` : "";
+      const msg = entry.msg ? ` (${entry.msg})` : "";
+      lines.push(`- ${entry.date} ${entry.action}${order} ${entry.ts}${msg}`);
+    }
+  }
+
+  return lines.join("\n");
+};

package/core/fsm.ts

@@ -0,0 +1,28 @@
+import type { TaskAction, TaskStatus } from "./types";
+
+export const transitionTable: Record<TaskStatus, Partial<Record<TaskAction, TaskStatus>>> = {
+  backlog: {
+    start: "active",
+    cancel: "cancelled",
+  },
+  active: {
+    pause: "paused",
+    complete: "completed",
+    cancel: "cancelled",
+  },
+  paused: {
+    start: "active",
+    complete: "completed",
+    cancel: "cancelled",
+  },
+  completed: {},
+  cancelled: {},
+};
+
+export const getNextStatus = (current: TaskStatus, action: TaskAction): TaskStatus => {
+  const next = transitionTable[current][action];
+  if (!next) {
+    throw new Error(`Invalid transition: ${current} -> ${action}`);
+  }
+  return next;
+};

package/core/git.ts

@@ -0,0 +1,117 @@
+import { execFile } from "node:child_process";
+import path from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+export type GitCommitOptions = {
+  message: string;
+  files?: string[];
+  author?: {
+    name: string;
+    email: string;
+  };
+};
+
+export const isGitRepository = async (dir: string): Promise<boolean> => {
+  try {
+    await execFileAsync("git", ["-C", dir, "rev-parse", "--git-dir"], {
+      encoding: "utf8",
+    });
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+export const getGitStatus = async (
+  dir: string,
+): Promise<{
+  modified: string[];
+  added: string[];
+  deleted: string[];
+  untracked: string[];
+}> => {
+  try {
+    const { stdout } = await execFileAsync("git", ["-C", dir, "status", "--porcelain"], {
+      encoding: "utf8",
+    });
+
+    const modified: string[] = [];
+    const added: string[] = [];
+    const deleted: string[] = [];
+    const untracked: string[] = [];
+
+    for (const line of stdout.trim().split("\n")) {
+      if (!line) continue;
+
+      const status = line.substring(0, 2);
+      const filePath = line.substring(3);
+
+      if (status === "??") {
+        untracked.push(filePath);
+      } else if (status[0] === "A" || status[1] === "A") {
+        added.push(filePath);
+      } else if (status[0] === "D" || status[1] === "D") {
+        deleted.push(filePath);
+      } else if (status[0] === "M" || status[1] === "M") {
+        modified.push(filePath);
+      }
+    }
+
+    return { modified, added, deleted, untracked };
+  } catch {
+    return { modified: [], added: [], deleted: [], untracked: [] };
+  }
+};
+
+export const stageFiles = async (dir: string, files: string[]): Promise<void> => {
+  if (files.length === 0) return;
+
+  await execFileAsync("git", ["-C", dir, "add", ...files]);
+};
+
+export const commitChanges = async (dir: string, options: GitCommitOptions): Promise<void> => {
+  const args = ["-C", dir, "commit"];
+
+  if (options.author) {
+    args.push("--author", `${options.author.name} <${options.author.email}>`);
+  }
+
+  args.push("--message", options.message);
+
+  await execFileAsync("git", args);
+};
+
+export const hasChangesToCommit = async (dir: string): Promise<boolean> => {
+  const status = await getGitStatus(dir);
+  return (
+    status.modified.length > 0 ||
+    status.added.length > 0 ||
+    status.deleted.length > 0 ||
+    status.untracked.length > 0
+  );
+};
+
+export const autoCommit = async (dir: string, options: GitCommitOptions): Promise<boolean> => {
+  if (!(await isGitRepository(dir))) {
+    return false;
+  }
+
+  if (!(await hasChangesToCommit(dir))) {
+    return false;
+  }
+
+  try {
+    if (options.files) {
+      await stageFiles(dir, options.files);
+    } else {
+      await stageFiles(dir, ["."]);
+    }
+
+    await commitChanges(dir, options);
+    return true;
+  } catch {
+    return false;
+  }
+};

package/core/gitignore.ts

@@ -0,0 +1,30 @@
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { APP_DIR } from "./constants";
+
+const ignoredEntries = [`${APP_DIR}/.lock/`, `${APP_DIR}/config.json`];
+
+export const ensureWorkspaceIgnored = async (repoRoot: string): Promise<boolean> => {
+  const gitignorePath = path.join(repoRoot, ".gitignore");
+  let current = "";
+
+  try {
+    current = await readFile(gitignorePath, "utf8");
+  } catch {
+    current = "";
+  }
+
+  const lines = current.split("\n");
+  const missingEntries = ignoredEntries.filter(
+    (entry) => !lines.some((line) => line.trim() === entry),
+  );
+  if (missingEntries.length === 0) {
+    return false;
+  }
+
+  const separator = current.endsWith("\n") || current.length === 0 ? "" : "\n";
+  const next = `${current}${separator}${missingEntries.join("\n")}\n`;
+  await writeFile(gitignorePath, next, "utf8");
+  return true;
+};

package/core/id.ts

@@ -0,0 +1,41 @@
+import { createHash } from "node:crypto";
+
+import { ulid } from "ulid";
+
+import type { TaskType } from "./types";
+
+const BASE32_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+
+const base32Encode = (input: Uint8Array): string => {
+  let bits = 0;
+  let value = 0;
+  let output = "";
+
+  for (const byte of input) {
+    value = (value << 8) | byte;
+    bits += 8;
+
+    while (bits >= 5) {
+      output += BASE32_ALPHABET[(value >>> (bits - 5)) & 31];
+      bits -= 5;
+    }
+  }
+
+  if (bits > 0) {
+    output += BASE32_ALPHABET[(value << (5 - bits)) & 31];
+  }
+
+  return output;
+};
+
+export const generateTaskId = (taskType: TaskType): string => {
+  const prefix = taskType === "review" ? "R" : "T";
+  return `${prefix}${ulid()}`;
+};
+
+export const generateStableRef = (taskType: TaskType, taskId: string): string => {
+  const prefix = taskType === "review" ? "R" : "T";
+  const hash = createHash("sha256").update(taskId).digest();
+  const encoded = base32Encode(hash).slice(0, 6);
+  return `${prefix}-${encoded}`;
+};

package/core/json.ts

@@ -0,0 +1,13 @@
+import { readFile } from "node:fs/promises";
+
+import writeFileAtomic from "write-file-atomic";
+
+export const readJsonFile = async <T>(filePath: string): Promise<T> => {
+  const raw = await readFile(filePath, "utf8");
+  return JSON.parse(raw) as T;
+};
+
+export const writeJsonAtomic = async (filePath: string, data: unknown): Promise<void> => {
+  const payload = `${JSON.stringify(data, null, 2)}\n`;
+  await writeFileAtomic(filePath, payload, { encoding: "utf8", fsync: true });
+};

package/core/lock.ts

@@ -0,0 +1,31 @@
+import { writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import lockfile from "proper-lockfile";
+
+import { LOCK_DIR, LOCK_FILE } from "./constants";
+import { ensureWorkspaceLayout } from "./workspace";
+
+export const withWorkspaceLock = async <T>(
+  workspaceRoot: string,
+  fn: () => Promise<T>,
+): Promise<T> => {
+  await ensureWorkspaceLayout(workspaceRoot);
+  const lockPath = path.join(workspaceRoot, LOCK_DIR, LOCK_FILE);
+  await writeFile(lockPath, "", { flag: "a" });
+  const release = await lockfile.lock(lockPath, {
+    stale: 60_000,
+    retries: {
+      retries: 5,
+      factor: 1.5,
+      minTimeout: 50,
+      maxTimeout: 1_000,
+    },
+  });
+
+  try {
+    return await fn();
+  } finally {
+    await release();
+  }
+};

package/core/plugin.ts

@@ -0,0 +1,99 @@
+import type { Task } from "./schemas/task";
+import type { TaskAction, TaskStatus } from "./types";
+
+/**
+ * Logger interface for plugins
+ */
+export type PluginLogger = {
+  debug: (message: string) => void;
+  info: (message: string) => void;
+  warn: (message: string) => void;
+  error: (message: string) => void;
+};
+
+/**
+ * Context provided to all hook handlers
+ */
+export type PluginContext = {
+  /** Root path of the current workspace */
+  workspaceRoot: string;
+  /** Plugin-specific configuration from config.json */
+  config: Record<string, unknown>;
+  /** Logger for plugin output */
+  logger: PluginLogger;
+};
+
+/**
+ * Result returned from a hook handler
+ */
+export type HookResult = {
+  /** Return modified task, or omit to keep original */
+  task?: Task;
+};
+
+/**
+ * Hook event payloads for each lifecycle event
+ */
+export type HookEvents = {
+  "task:created": {
+    task: Task;
+    alias: string;
+  };
+  "task:transitioned": {
+    task: Task;
+    previousStatus: TaskStatus;
+    action: TaskAction;
+  };
+  "task:logged": {
+    task: Task;
+    message: string;
+  };
+  "task:edited": {
+    task: Task;
+    path: string;
+    previousValue: unknown;
+    newValue: unknown;
+  };
+  "pr:attached": {
+    task: Task;
+    prUrl: string;
+  };
+  "pr:refreshed": {
+    task: Task;
+    previousState?: "open" | "closed" | "merged";
+    newState: "open" | "closed" | "merged";
+  };
+};
+
+/**
+ * Hook handler function type
+ */
+export type HookHandler<K extends keyof HookEvents> = (
+  event: HookEvents[K],
+  context: PluginContext,
+) => Promise<HookResult | undefined>;
+
+/**
+ * Plugin definition
+ */
+export type FlowcatPlugin = {
+  /** Unique plugin name (e.g., "llm-pr-analyzer") */
+  name: string;
+
+  /** Semantic version */
+  version: string;
+
+  /** Human-readable description */
+  description?: string;
+
+  /** Hook handlers */
+  hooks?: {
+    [K in keyof HookEvents]?: HookHandler<K>;
+  };
+
+  /** Called once when plugin loads (optional) */
+  onLoad?: (context: PluginContext) => Promise<void>;
+
+  /** Called when plugin unloads (optional) */
+  onUnload?: (context: PluginContext) => Promise<void>;
+};