flowcat 1.3.0 → 1.5.0

package/core/pr.ts

@@ -0,0 +1,89 @@
+import { Octokit } from "octokit";
+
+import type { PrAttachment, PrFetched } from "./schemas/pr";
+import { nowIso } from "./time";
+
+export type ParsedPr = {
+  url: string;
+  provider: "github";
+  repo: {
+    host: string;
+    owner: string;
+    name: string;
+  };
+  number: number;
+};
+
+export const parseGitHubPrUrl = (value: string): ParsedPr | null => {
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    return null;
+  }
+
+  const parts = url.pathname.split("/").filter(Boolean);
+  if (parts.length < 4 || parts[2] !== "pull") {
+    return null;
+  }
+
+  const number = Number(parts[3]);
+  if (!Number.isInteger(number)) {
+    return null;
+  }
+
+  return {
+    url: value,
+    provider: "github",
+    repo: {
+      host: url.host,
+      owner: parts[0],
+      name: parts[1],
+    },
+    number,
+  };
+};
+
+export const buildPrAttachment = (parsed: ParsedPr, fetched?: PrFetched): PrAttachment => {
+  return {
+    url: parsed.url,
+    provider: "github",
+    repo: parsed.repo,
+    number: parsed.number,
+    fetched,
+  };
+};
+
+export const fetchGitHubPr = async (
+  parsed: ParsedPr,
+  token?: string | null,
+): Promise<PrFetched | null> => {
+  if (!parsed.repo || !parsed.number) {
+    return null;
+  }
+
+  if (!token) {
+    return null;
+  }
+
+  const octokit = new Octokit({ auth: token });
+  const response = await octokit.rest.pulls.get({
+    owner: parsed.repo.owner,
+    repo: parsed.repo.name,
+    pull_number: parsed.number,
+  });
+
+  const data = response.data;
+  const state = data.merged ? "merged" : data.state === "open" ? "open" : "closed";
+
+  return {
+    at: nowIso(),
+    title: data.title,
+    author: {
+      login: data.user?.login ?? "unknown",
+    },
+    state,
+    draft: data.draft ?? false,
+    updated_at: data.updated_at,
+  };
+};

package/core/prWorkflow.ts

@@ -0,0 +1,185 @@
+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 { appendLog, applyTransition } from "./taskOperations";
+import { moveTaskFile, saveTask } from "./taskRepo";
+import { resolveTask } from "./taskResolver";
+import { nowIso } from "./time";
+import type { TaskAction, TaskStatus } from "./types";
+
+export class PrWorkflowError extends Error {
+  code: "INVALID_PR_URL" | "MISSING_TOKEN";
+
+  constructor(code: "INVALID_PR_URL" | "MISSING_TOKEN", message: string) {
+    super(message);
+    this.code = code;
+    this.name = "PrWorkflowError";
+  }
+}
+
+export type AttachPrResult = {
+  status: "attached";
+  task: Task;
+};
+
+export type RefreshPrResult =
+  | { status: "no_pr" }
+  | { status: "refreshed"; task: Task; nextStatus: TaskStatus; transitioned: boolean };
+
+export type PrTransitionDecision = {
+  action?: TaskAction;
+  message?: string;
+};
+
+export const resolvePrTransition = (input: {
+  taskStatus: TaskStatus;
+  previousState?: PrFetched["state"];
+  nextState?: PrFetched["state"];
+  message?: string;
+}): PrTransitionDecision => {
+  const isTerminal = input.taskStatus === "completed" || input.taskStatus === "cancelled";
+  if (isTerminal || input.previousState === input.nextState) {
+    return {};
+  }
+
+  if (input.nextState === "merged") {
+    return { action: "complete", message: input.message ?? "PR merged" };
+  }
+
+  if (input.nextState === "closed") {
+    return { action: "cancel", message: input.message ?? "PR closed without merge" };
+  }
+
+  return {};
+};
+
+export const attachPrToTask = async (input: {
+  workspaceRoot: string;
+  identifier: string;
+  url: string;
+  message?: string;
+}): Promise<AttachPrResult> => {
+  return withWorkspaceLock(input.workspaceRoot, async () => {
+    const parsed = parseGitHubPrUrl(input.url);
+    if (!parsed) {
+      throw new PrWorkflowError("INVALID_PR_URL", "Invalid PR URL");
+    }
+
+    const token = await resolveGithubToken(input.workspaceRoot);
+    let fetched: PrFetched | null = null;
+    if (token) {
+      try {
+        fetched = await fetchGitHubPr(parsed, token);
+      } catch {
+        fetched = null;
+      }
+    }
+    const stored = await resolveTask(input.workspaceRoot, input.identifier);
+
+    const updated: Task = {
+      ...stored.task,
+      metadata: {
+        ...stored.task.metadata,
+        pr: buildPrAttachment(parsed, fetched ?? stored.task.metadata.pr?.fetched),
+      },
+      updated_at: nowIso(),
+    };
+
+    const logMessage = input.message ?? `Attached PR ${input.url}`;
+    let next = appendLog(updated, logMessage);
+    await saveTask(input.workspaceRoot, stored.status, next);
+
+    // Emit hook and apply task modifications from plugins
+    const hookResult = await emitHook(input.workspaceRoot, "pr:attached", {
+      task: next,
+      prUrl: input.url,
+    });
+
+    if (hookResult.task) {
+      taskSchema.parse(hookResult.task);
+      await saveTask(input.workspaceRoot, stored.status, hookResult.task);
+      next = hookResult.task;
+    }
+
+    return { status: "attached", task: next };
+  });
+};
+
+export const refreshPrForTask = async (input: {
+  workspaceRoot: string;
+  identifier: string;
+  message?: string;
+}): Promise<RefreshPrResult> => {
+  return withWorkspaceLock(input.workspaceRoot, async () => {
+    const stored = await resolveTask(input.workspaceRoot, input.identifier);
+    const prUrl = stored.task.metadata.pr?.url;
+    if (!prUrl) {
+      return { status: "no_pr" };
+    }
+
+    const parsed = parseGitHubPrUrl(prUrl);
+    if (!parsed) {
+      throw new Error("Invalid PR URL");
+    }
+
+    const token = await resolveGithubToken(input.workspaceRoot);
+    const fetched = await fetchGitHubPr(parsed, token);
+    if (!fetched) {
+      throw new PrWorkflowError("MISSING_TOKEN", "No GitHub token configured");
+    }
+
+    const baseUpdated: Task = {
+      ...stored.task,
+      metadata: {
+        ...stored.task.metadata,
+        pr: buildPrAttachment(parsed, fetched),
+      },
+      updated_at: nowIso(),
+    };
+
+    const decision = resolvePrTransition({
+      taskStatus: stored.task.status,
+      previousState: stored.task.metadata.pr?.fetched?.state,
+      nextState: fetched.state,
+      message: input.message,
+    });
+
+    let finalTask = baseUpdated;
+    let nextStatus = stored.status;
+
+    if (decision.action) {
+      const result = applyTransition(baseUpdated, decision.action, decision.message);
+      finalTask = result.task;
+      nextStatus = result.nextStatus;
+    }
+
+    await saveTask(input.workspaceRoot, stored.status, finalTask);
+    if (nextStatus !== stored.status) {
+      await moveTaskFile(input.workspaceRoot, finalTask.id, stored.status, nextStatus);
+    }
+
+    // Emit hook and apply task modifications from plugins
+    const hookResult = await emitHook(input.workspaceRoot, "pr:refreshed", {
+      task: finalTask,
+      previousState: stored.task.metadata.pr?.fetched?.state,
+      newState: fetched.state,
+    });
+
+    if (hookResult.task) {
+      taskSchema.parse(hookResult.task);
+      await saveTask(input.workspaceRoot, nextStatus, hookResult.task);
+      finalTask = hookResult.task;
+    }
+
+    return {
+      status: "refreshed",
+      task: finalTask,
+      nextStatus,
+      transitioned: nextStatus !== stored.status,
+    };
+  });
+};

package/core/schemas/dayAssignment.ts

@@ -0,0 +1,11 @@
+import { z } from "zod";
+
+export const dayAssignmentSchema = z.object({
+  date: z.string(),
+  action: z.enum(["assign", "unassign", "reorder"]),
+  ts: z.string(),
+  order: z.number().int().positive().optional(),
+  msg: z.string().optional(),
+});
+
+export type DayAssignment = z.infer<typeof dayAssignmentSchema>;

package/core/schemas/logEntry.ts

@@ -0,0 +1,11 @@
+import { z } from "zod";
+
+import { taskStatuses } from "../types";
+
+export const logEntrySchema = z.object({
+  ts: z.string(),
+  msg: z.string(),
+  status: z.enum(taskStatuses).optional(),
+});
+
+export type LogEntry = z.infer<typeof logEntrySchema>;

package/core/schemas/pr.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+
+const prRepoSchema = z.object({
+  host: z.string(),
+  owner: z.string(),
+  name: z.string(),
+});
+
+export const prFetchedSchema = z.object({
+  at: z.string(),
+  title: z.string(),
+  author: z.object({
+    login: z.string(),
+  }),
+  state: z.enum(["open", "closed", "merged"]),
+  draft: z.boolean(),
+  updated_at: z.string(),
+});
+
+export const prAttachmentSchema = z.object({
+  url: z.string(),
+  provider: z.literal("github"),
+  repo: prRepoSchema.optional(),
+  number: z.number().int().positive().optional(),
+  fetched: prFetchedSchema.optional(),
+});
+
+export type PrFetched = z.infer<typeof prFetchedSchema>;
+export type PrAttachment = z.infer<typeof prAttachmentSchema>;

package/core/schemas/task.ts

@@ -0,0 +1,41 @@
+import { z } from "zod";
+
+import { taskStatuses, taskTypes } from "../types";
+import { dayAssignmentSchema } from "./dayAssignment";
+import { logEntrySchema } from "./logEntry";
+import { prAttachmentSchema } from "./pr";
+
+export const taskMetadataSchema = z.object({
+  url: z.string().optional(),
+  pr: prAttachmentSchema.optional(),
+});
+
+export const taskSchema = z
+  .object({
+    id: z.string(),
+    ref: z.string(),
+    type: z.enum(taskTypes),
+    title: z.string(),
+    status: z.enum(taskStatuses),
+    created_at: z.string(),
+    updated_at: z.string(),
+    metadata: taskMetadataSchema,
+    logs: z.array(logEntrySchema),
+    day_assignments: z.array(dayAssignmentSchema),
+  })
+  .superRefine((task, ctx) => {
+    if (task.type === "review" && !task.metadata.pr?.url) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: "Review tasks require metadata.pr.url",
+        path: ["metadata", "pr", "url"],
+      });
+    }
+  });
+
+export type TaskMetadata = z.infer<typeof taskMetadataSchema>;
+export type Task = z.infer<typeof taskSchema>;
+
+export const validateTaskOrThrow = (task: Task): Task => {
+  return taskSchema.parse(task);
+};

package/core/search.ts

@@ -0,0 +1,25 @@
+import type { Task } from "./schemas/task";
+
+export const taskMatchesQuery = (task: Task, query: string): boolean => {
+  const needle = query.toLowerCase();
+  const contains = (value?: string): boolean =>
+    value ? value.toLowerCase().includes(needle) : false;
+
+  if (contains(task.title)) {
+    return true;
+  }
+
+  if (task.logs.some((log) => contains(log.msg))) {
+    return true;
+  }
+
+  if (contains(task.metadata.pr?.url)) {
+    return true;
+  }
+
+  if (contains(task.metadata.pr?.fetched?.title)) {
+    return true;
+  }
+
+  return false;
+};

package/core/taskFactory.ts

@@ -0,0 +1,29 @@
+import { generateStableRef, generateTaskId } from "./id";
+import type { Task, TaskMetadata } from "./schemas/task";
+import { nowIso } from "./time";
+import type { TaskType } from "./types";
+
+export type NewTaskInput = {
+  type: TaskType;
+  title: string;
+  metadata?: TaskMetadata;
+};
+
+export const buildTask = (input: NewTaskInput): Task => {
+  const id = generateTaskId(input.type);
+  const ref = generateStableRef(input.type, id);
+  const timestamp = nowIso();
+
+  return {
+    id,
+    ref,
+    type: input.type,
+    title: input.title,
+    status: "backlog",
+    created_at: timestamp,
+    updated_at: timestamp,
+    metadata: input.metadata ?? {},
+    logs: [],
+    day_assignments: [],
+  };
+};

package/core/taskOperations.ts

@@ -0,0 +1,104 @@
+import { getNextStatus } from "./fsm";
+import type { DayAssignment } from "./schemas/dayAssignment";
+import type { LogEntry } from "./schemas/logEntry";
+import type { Task } from "./schemas/task";
+import { nowIso } from "./time";
+import type { TaskAction, TaskStatus } from "./types";
+
+const defaultMessages: Record<TaskAction, string> = {
+  start: "Started task",
+  pause: "Paused task",
+  complete: "Completed task",
+  cancel: "Cancelled task",
+};
+
+export const appendLog = (task: Task, message: string, status?: TaskStatus): Task => {
+  const log: LogEntry = {
+    ts: nowIso(),
+    msg: message,
+    status,
+  };
+
+  return {
+    ...task,
+    logs: [...task.logs, log],
+    updated_at: nowIso(),
+  };
+};
+
+export const applyTransition = (
+  task: Task,
+  action: TaskAction,
+  message?: string,
+): { task: Task; nextStatus: TaskStatus } => {
+  const nextStatus = getNextStatus(task.status, action);
+  const logMessage = message ?? defaultMessages[action];
+  const log: LogEntry = {
+    ts: nowIso(),
+    msg: logMessage,
+    status: nextStatus,
+  };
+
+  const updated: Task = {
+    ...task,
+    status: nextStatus,
+    updated_at: nowIso(),
+    logs: [...task.logs, log],
+  };
+
+  return { task: updated, nextStatus };
+};
+
+export const isAssignedOnDate = (task: Task, date: string): boolean => {
+  const latest = getLatestDayAssignment(task, date);
+  if (!latest) {
+    return false;
+  }
+
+  return latest.event.action === "assign" || latest.event.action === "reorder";
+};
+
+export const getLatestDayAssignment = (
+  task: Task,
+  date: string,
+): { event: DayAssignment; index: number } | null => {
+  let latestIndex = -1;
+  for (let i = 0; i < task.day_assignments.length; i += 1) {
+    if (task.day_assignments[i]?.date === date) {
+      latestIndex = i;
+    }
+  }
+
+  if (latestIndex === -1) {
+    return null;
+  }
+
+  const event = task.day_assignments[latestIndex];
+  if (!event) {
+    return null;
+  }
+
+  return { event, index: latestIndex };
+};
+
+export const appendDayAssignment = (
+  task: Task,
+  date: string,
+  action: DayAssignment["action"],
+  msg?: string,
+  order?: number,
+): Task => {
+  const event: DayAssignment = {
+    date,
+    action,
+    ts: nowIso(),
+    order,
+    msg,
+  };
+
+  return {
+    ...task,
+    day_assignments: [...task.day_assignments, event],
+    updated_at: nowIso(),
+  };
+};

package/core/taskRepo.ts

@@ -0,0 +1,109 @@
+import { access, readdir, rename } from "node:fs/promises";
+import path from "node:path";
+
+import { STATUS_ORDER, TASKS_DIR } from "./constants";
+import { readJsonFile, writeJsonAtomic } from "./json";
+import type { Task } from "./schemas/task";
+import { taskSchema } from "./schemas/task";
+import type { TaskStatus } from "./types";
+
+export type StoredTask = {
+  task: Task;
+  status: TaskStatus;
+  filePath: string;
+};
+
+const taskFileName = (taskId: string): string => `${taskId}.json`;
+
+const getStatusDir = (workspaceRoot: string, status: TaskStatus): string =>
+  path.join(workspaceRoot, TASKS_DIR, status);
+
+export const getTaskPath = (workspaceRoot: string, status: TaskStatus, taskId: string): string => {
+  return path.join(getStatusDir(workspaceRoot, status), taskFileName(taskId));
+};
+
+const fileExists = async (filePath: string): Promise<boolean> => {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+export const findTaskPathById = async (
+  workspaceRoot: string,
+  taskId: string,
+): Promise<{ filePath: string; status: TaskStatus } | null> => {
+  for (const status of STATUS_ORDER) {
+    const candidate = getTaskPath(workspaceRoot, status, taskId);
+    if (await fileExists(candidate)) {
+      return { filePath: candidate, status };
+    }
+  }
+
+  return null;
+};
+
+export const loadTaskFromPath = async (filePath: string): Promise<Task> => {
+  const parsed = await readJsonFile<Task>(filePath);
+  return taskSchema.parse(parsed);
+};
+
+export const loadTaskById = async (workspaceRoot: string, taskId: string): Promise<StoredTask> => {
+  const found = await findTaskPathById(workspaceRoot, taskId);
+  if (!found) {
+    throw new Error(`Task not found: ${taskId}`);
+  }
+
+  const task = await loadTaskFromPath(found.filePath);
+  return { task, status: found.status, filePath: found.filePath };
+};
+
+export const listTasksByStatus = async (
+  workspaceRoot: string,
+  status: TaskStatus,
+): Promise<StoredTask[]> => {
+  const statusDir = getStatusDir(workspaceRoot, status);
+  const entries = await readdir(statusDir, { withFileTypes: true });
+  const tasks = await Promise.all(
+    entries
+      .filter((entry) => entry.isFile() && entry.name.endsWith(".json"))
+      .map(async (entry) => {
+        const filePath = path.join(statusDir, entry.name);
+        const task = await loadTaskFromPath(filePath);
+        return { task, status, filePath };
+      }),
+  );
+
+  return tasks;
+};
+
+export const listAllTasks = async (workspaceRoot: string): Promise<StoredTask[]> => {
+  const all = await Promise.all(
+    STATUS_ORDER.map((status) => listTasksByStatus(workspaceRoot, status)),
+  );
+  return all.flat();
+};
+
+export const saveTask = async (
+  workspaceRoot: string,
+  status: TaskStatus,
+  task: Task,
+): Promise<string> => {
+  const filePath = getTaskPath(workspaceRoot, status, task.id);
+  await writeJsonAtomic(filePath, task);
+  return filePath;
+};
+
+export const moveTaskFile = async (
+  workspaceRoot: string,
+  taskId: string,
+  fromStatus: TaskStatus,
+  toStatus: TaskStatus,
+): Promise<string> => {
+  const fromPath = getTaskPath(workspaceRoot, fromStatus, taskId);
+  const toPath = getTaskPath(workspaceRoot, toStatus, taskId);
+  await rename(fromPath, toPath);
+  return toPath;
+};

package/core/taskResolver.ts

@@ -0,0 +1,44 @@
+import { resolveAlias } from "./aliasRepo";
+import type { StoredTask } from "./taskRepo";
+import { findTaskPathById, listAllTasks, loadTaskFromPath } from "./taskRepo";
+
+const stableRefPattern = /^[TR]-[A-Z0-9]{6}$/;
+
+export const resolveTaskId = async (workspaceRoot: string, identifier: string): Promise<string> => {
+  const aliasMatch = await resolveAlias(workspaceRoot, identifier);
+  if (aliasMatch) {
+    return aliasMatch;
+  }
+
+  if (stableRefPattern.test(identifier)) {
+    const tasks = await listAllTasks(workspaceRoot);
+    const match = tasks.find((stored) => stored.task.ref === identifier);
+    if (!match) {
+      throw new Error(`Task not found for ref: ${identifier}`);
+    }
+
+    return match.task.id;
+  }
+
+  const found = await findTaskPathById(workspaceRoot, identifier);
+  if (!found) {
+    throw new Error(`Task not found: ${identifier}`);
+  }
+
+  return identifier;
+};
+
+export const resolveTask = async (
+  workspaceRoot: string,
+  identifier: string,
+): Promise<StoredTask> => {
+  const taskId = await resolveTaskId(workspaceRoot, identifier);
+  const found = await findTaskPathById(workspaceRoot, taskId);
+
+  if (!found) {
+    throw new Error(`Task not found: ${identifier}`);
+  }
+
+  const task = await loadTaskFromPath(found.filePath);
+  return { task, status: found.status, filePath: found.filePath };
+};

package/core/taskStore.ts

@@ -0,0 +1,14 @@
+import { allocateAlias, writeAliases } from "./aliasRepo";
+import type { Task } from "./schemas/task";
+import { saveTask } from "./taskRepo";
+
+export const createTaskInStore = async (
+  workspaceRoot: string,
+  task: Task,
+): Promise<{ alias: string; task: Task }> => {
+  const prefix = task.type === "review" ? "R" : "T";
+  const { alias, aliases } = await allocateAlias(workspaceRoot, prefix, task.id);
+  await writeAliases(workspaceRoot, aliases);
+  await saveTask(workspaceRoot, task.status, task);
+  return { alias, task };
+};